1 \input texinfo @c -*-texinfo-*-

     2 @c %**start of header

     3 @setfilename HOWTO.info

     4 @settitle VMailMgr HOWTO

     5 @setchapternewpage off

     6 @paragraphindent 5

     7 @footnotestyle end

     8 @c %**end of header

     9 

    10 @ifinfo

    11 Copyright @copyright{} 1998 Bruce Guenter

    12 @end ifinfo

    13 

    14 @titlepage

    15 @title Vmailmgr HOWTO

    16 @author Bruce Guenter

    17 @author Dan Kuykendall

    18 @subtitle @today{}

    19 @end titlepage

    20 

    21 @ifinfo

    22 This document explains how to setup VMailMgr support pop3 virtual domain 

    23 services in conjunction with Qmail.

    24 @end ifinfo

    25 

    26 @c ****************************************************************************

    27 @chapter Introduction

    28 

    29 VMailMgr (an abbreviation for Virtual Mail Manager) is a package of programs

    30 designed to manage multiple domains of mail addresses and mailboxes

    31 on a single host.  It co-operates with qmail for mail delivery and

    32 program control.

    33 

    34 @section What is VMailMgr and why should I use it?

    35 

    36 VMailMgr is a series of utilities for managing virtual domains, including:

    37 @itemize

    38 @item

    39 a password checking interface for qmail, which replaces the usual

    40 checkpassword, and

    41 @item

    42 an authentication module for Courier IMAP

    43 @end itemize

    44 

    45 These utilities provide access to the virtual mailboxes by one of three

    46 methods:

    47 

    48 @itemize

    49 @item

    50 IP-based virtual server access (invisible to the POP3 user)

    51 @item

    52 username-based access (virtual user logs in as @samp{username-virtualuser})

    53 @item

    54 hostname-based access (virtual user logs in as @samp{virtualuser@@virtual.host}

    55 or @samp{virtualuser:virtual.host})

    56 @end itemize

    57 

    58 You should use VMailMgr if you prefer to have each domain controlled by a

    59 seperate username, allowing the use of system quotas and better

    60 security.

    61 

    62 @section New versions 

    63 

    64 The newest version of this document can be found on the VMailMgr homepage

    65 @uref{http://www.vmailmgr.org/} in various formats, including the

    66 texinfo source and HTML and plaintext versions.

    67 

    68 @section Comments 

    69 

    70 Comments on this HOWTO should be directed to the VMailMgr mailing

    71 list.  To subscribe, send a blank email to

    72 @email{vmailmgr-subscribe@@lists.untroubled.org}.

    73 

    74 @section History 

    75 

    76 This document was started by Bruce Guenter and reworked by Dan

    77 Kuykendall, then by Charles Cazabon.

    78 

    79 @section Copyrights and Trademarks 

    80 

    81 Copyright @copyright{} Dan Kuykendall.

    82 

    83 Permission is granted to copy, distribute and/or modify this document

    84 under the terms of the GNU Free Documentation License, Version 1.1

    85 or any later version published by the Free Software Foundation

    86 

    87 A copy of the license is available at 

    88 @uref{http://www.gnu.org/copyleft/fdl.txt,GNU Free Documentation License}.

    89 

    90 @section Acknowledgements and Thanks 

    91 

    92 Thanks to Bruce Guenter for VMailMgr and the core of this

    93 HOWTO.  Thanks to Mike Bell, who always seems to have the answers to

    94 my questions. Finally, thanks to all those on the 

    95 @email{vmailmgr@@lists.untroubled.org}

    96 mailing list who have helped me, or asked the same stuff so many

    97 times that I had to write this to stop the repeat questions.

    98 

    99 @c ****************************************************************************

   100 @chapter Installation

   101 

   102 @section Get the files

   103 

   104 Visit the VMailMgr website @uref{http://www.vmailmgr.org/} or one of its

   105 mirror sites to download the package.  There are two primary methods of

   106 installing:

   107 

   108 @itemize

   109 @item

   110 from source

   111 

   112 @item

   113 from a binary package -- specifically, an @code{RPM} binary package

   114 

   115 @end itemize

   116 

   117 If you get the binary RPMS you will need at least the vmailmgr package.

   118 

   119 @section Install with RPMS

   120 

   121 To install from binary @code{RPM} packages, you can download the binaries,

   122 or build them from the source RPM package.

   123 

   124 @subsection Compiling the Source RPM (SRPM) Package

   125 

   126 If you download the binary packages directly, skip to the next step.

   127 

   128 Download the source rpm package (@samp{vmailmgr-@var{VERSION}.src.rpm}),

   129 and then use the @code{rpm} tool to build the binary RPM package from it

   130 with the @samp{rpm --rebuild} command as follows:

   131 

   132 @example

   133 rpm --rebuild vmailmgr-1.0.0-1.src.rpm

   134 @end example

   135 

   136 @subsection Installing the Binary RPM packages

   137 

   138 After compiling the source RPM, the binary RPM packages will be located 

   139 in the appropriate output directory (typically 

   140 @file{/usr/src/redhat/RPMS/i386/}).

   141 

   142 Install each package using the @samp{-i} option of @code{rpm} (i.e. 

   143 @samp{rpm -ivh @var{PACKAGE}.i386.rpm}) as follows:

   144 

   145 @example

   146 rpm -ivh /usr/src/redhat/RPMS/i386/vmailmgr-1.0.0-1.i386.rpm

   147 rpm -ivh /usr/src/redhat/RPMS/i386/vmailmgr-daemon-1.0.0-1.i386.rpm

   148 @end example

   149 

   150 @section Install from source

   151 

   152 If you dont use RPM packages, you can install from source with the following 

   153 commands. First, as a regular, non-root user:

   154 

   155 @example

   156 tar xzf @file{vmailmgr-@var{VERSION}.tar.gz}

   157 cd @file{vmailmgr-@var{VERSION}}

   158 ./configure

   159 make

   160 @end example

   161 

   162 Then, as user @samp{root}:

   163 

   164 @example

   165 make install

   166 @end example

   167 

   168 @c ****************************************************************************

   169 @chapter Setup

   170 

   171 In the following setup examples, it is assumed that your binaries are installed 

   172 in the @file{/usr/bin]} directory, and configuration files are located in the 

   173 @file{/etc/vmailmgr/} directory, as is the case if you installed from the RPMs.

   174 

   175 If you installed from source, configure instead puts the binaries into

   176 @file{/usr/local/bin/} and the configuration into

   177 @file{/usr/local/etc/vmailmgr/} by default.

   178 

   179 @section Setting Up a Virtual Domain

   180 

   181 The following steps are necessary to set up a virtual domain with

   182 vmailmgr (assuming vmailmgr has been compiled and installed). As an

   183 example, we'll set up a virtual user @samp{me@@mydomain.org},

   184 with aliases of @samp{myself@@mydomain.org} and

   185 @samp{myname@@mydomain.org}.

   186 

   187 @enumerate

   188 @item

   189 Set up a DNS entry for the domain. This is not covered here, as it

   190 is dependant on far too many other things.  I will mention that to

   191 make IP based virtual domains work a @samp{PTR} record which matches an

   192 entry in virtualdomains is nessesary, for example, if nslookup

   193 10.56.33.122 returns @samp{mail.mydomain.com},

   194 @file{control/virtualdomains} needs an entry like

   195 @samp{mail.mydomain.com:myuser}.

   196 

   197 For the example, we'll assume that the mail exchanger for

   198 @samp{mydomain.org} is already set up to point to your computer.

   199 

   200 @item

   201 Set up a base user for the domain.  Create a user, with a name of

   202 your choosing.  Since the maildirs for all the users in the

   203 virtual domain will be stored under this user's home directory,

   204 make sure you set the user up in a partition or disk that is

   205 appropriate for such storage. The tools that you should use to

   206 accomplish this step vary greatly between different systems. For

   207 our example, I'll add a user @samp{myuser}.

   208 

   209 @item

   210 Configure qmail to recognize the domain. To do this, you need to

   211 modify two of qmail's configuration files in

   212 @file{/var/qmail/control}: @file{rcpthosts} and @file{virtualdomains}.

   213 @itemize

   214 @item

   215 To @file{rcpthosts}, add the line @samp{mydomain.org}. 

   216 @item

   217 To @file{virtualdomains}, add the line @samp{mydomain.org:myuser}.

   218 @end itemize

   219 

   220 If you wish to have mail to @samp{anything.mydomain.org}

   221 be delivered in the same way:

   222 @itemize

   223 @item

   224 To @file{rcpthosts}, add the line @samp{.mydomain.org}. 

   225 @item

   226 To @file{virtualdomains}, add the line @samp{.mydomain.org:myuser}.

   227 @end itemize

   228 

   229 @item

   230 Configure @code{qmail-popup}/@code{qmail-pop3d} to use @code{checkvpw} as the 

   231 password checker.  This step is dependant on how you have installed qmail.

   232 @itemize

   233 @item

   234 Replace @code{checkpassword} in the command you use to

   235 invoke @code{qmail-popup}/@code{qmail-pop3d} (either in

   236 @file{/etc/inet.conf} or in a @code{tcpserver}

   237 command) with @code{checkvpw}.

   238 @item

   239 And/Or at the prompt type @samp{echo checkvpw > @file{/var/qmail/control/checkpassword}}.

   240 @end itemize

   241 

   242 @item

   243 Set up the vmailmgr files:

   244 @itemize

   245 @item

   246 Either change user to the user you just created (for example,

   247 type @samp{su - myuser}) or log in (with either telnet or

   248 at the console) as the new user.

   249 @item

   250 Set up the base vmailmgr files by running @code{vsetup}.

   251 @item

   252 Use the included programs to add users and aliases.

   253 For our example, we would type the following commands:

   254 

   255 @example

   256 vadduser me

   257 vaddalias myself me

   258 vaddalias myname me

   259 @end example

   260 

   261 @end itemize

   262      

   263 @end enumerate

   264 

   265 After you have completed all these steps, you will need to kill and

   266 restart @code{qmail-send} to make it read the new

   267 @file{virtualdomains} control file.

   268 

   269 If you are using @code{inetd} to launch @code{qmail-popup},

   270 @samp{kill -HUP} the @code{inetd} process as well.

   271 

   272 @section Using one IP address for mutiple domains

   273 

   274 There are two ways to log in without using multiple IP addresses. 

   275 

   276 @enumerate

   277 @item

   278 The first way is to log in as

   279 @samp{user@var{SEP}virtual.domain.org}, where @samp{user} is the

   280 mailbox name of the virtual user, @var{SEP} is one of @samp{@@} or

   281 @samp{:} (by default; this is configurable in the

   282 @file{/etc/vmailmgr/} directory), and

   283 @samp{virtual.domain.org} is the virtual domain's name, as

   284 listed in @file{/var/qmail/control/virtualdomains}.

   285 

   286 @item

   287 The second way is to use the internal form of the mailbox name --

   288 that is, @samp{baseuser-user}, where @samp{user} is the

   289 same as above, and @samp{baseuser} is the username of the

   290 managing user.

   291 

   292 @end enumerate

   293 

   294 For example, if @file{/var/qmail/control/virtualdomains} contains 

   295 @samp{mydomain.com:myuser} and user @samp{myuser} exists and has

   296 set up a virtual mailbox with the name @samp{me}, and the

   297 @file{separators} configuration file @file{/etc/vmailmgr/} contains @samp{@@},

   298 this virtual user could log in as @samp{me@@mydomain.com},

   299 @samp{me:mydomain.com}, or @samp{myuser-me}.

   300 

   301 @section Catching all misdirected mail in a virtual domain

   302 

   303 In the @code{vmailmgr} configuration directory, there is a

   304 file called @file{default-username}. If mail to a virtual

   305 domain does not match any users or aliases in that domain, it is

   306 delivered to the name listed in this configuration item if it exists

   307 (which defaults to @samp{+}). To make this deliver to you,

   308 simply type @samp{vaddalias + me}.

   309 

   310 @section VMailMgr IMAP support

   311 

   312 VMailMgr supports Courier-IMAP, but Courier-IMAP does not come with

   313 an authentication module for VMailMgr.  This means that some minor

   314 work is required for making the two work together.

   315 

   316 The steps are:

   317 

   318 @itemize

   319 @item

   320 Copy @file{/usr/bin/authvmailmgr} to

   321 @file{/usr/lib/courier-imap/libexec/authlib/authvmailmgr}.

   322 

   323 @item

   324 Modify the @code{AUTHMODULES} statement in

   325 @file{/usr/lib/courier-imap/etc/imapd.config} and add

   326 @samp{authvmailmgr} as the first authentication module.

   327 @end itemize

   328 

   329 @section Enabling enforcement of virtual user quotas

   330 

   331 VMailMgr supports per-virtual-user quotas, but not out of the box,

   332 as it is not needed by the majority of users, and requires an extra

   333 program to be run on each delivery.

   334 

   335 To configure quota support, create the file

   336 @file{/etc/vmailmgr/vdeliver-predeliver}, containing

   337 the following:

   338 

   339 @example

   340 #!/bin/sh

   341 /usr/bin/vcheckquota

   342 @end example

   343 

   344 This is executed as a shell script, so you will need to make it

   345 executable by running the command @samp{chmod +x /etc/vmailmgr/vdeliver-predeliver}.

   346 

   347 @section Enabling processing of autoresponses

   348 

   349 Download and install the qmail-autoresponder package, found at

   350 @uref{http://untroubled.org/qmail-autoresponder/}.

   351 

   352 As with the above section, create a shell script

   353 @file{/etc/vmailmgr/vdeliver-postdeliver}, containing the following:

   354 

   355 @example

   356 #!/bin/sh

   357 if test -s $MAILDIR/autoresponse/message.txt ; then

   358   qmail-autoresponder $MAILDIR/autoresponse/message.txt $MAILDIR/autoresponse

   359 fi

   360 @end example

   361 

   362 @section Web-based interfaces for vmailmgr

   363 

   364 There are currently a few working solutions to administrate

   365 your vmailmgr system via a web interface. Only requirement is

   366 that the vmailmgrd daemon is running, and that you have

   367 a webserver on your system.

   368 

   369 @itemize

   370 @item

   371 For Python fans, there is vpyadmin by Bruce Guenter. The files can

   372 be downloaded at @uref{http://untroubled.org/vpyadmin/}, and

   373 the development code is online at 

   374 @uref{http://bruce-guenter.dyndns.org/cgi-bin/vpyadmin/}

   375 (sample.org / samplevm).

   376 

   377 @item

   378 And if you like PHP, you can use oMail-admin by Olivier Müller:

   379 it fully supports all vmailmgr functions, and speaks englich,

   380 french, italian, spanish, german and russian. Project homepage:

   381 @uref{http://omail.omnis.ch}. Online demo:

   382 @uref{http://admin.omnis.ch/omail/} (test.com / test).

   383 

   384 @item

   385 And there are also C-based CGI scripts in the @file{cgi}

   386 subdirectory of the vmailmgr distribution.

   387 

   388 @end itemize

   389 

   390 @contents

   391 

   392 @bye

   393