How to setup virtual users on Open WebMail using Postfix & vm-pop3d
                         Written by Kevin L. Ellis

    (The latest version of this document is available at
     http://www.bluelavalamp.net/owmvirtual/)


               This tutorial will show you how to setup Open WebMail
   (OWM) so that you can have both real users and pure virtual users
   access mail by either pop3 (i.e. Netscape, etc) or by using a web
   interface (Open WebMail).  A "pure" virtual user to me is one that
   does not have an account on the machine, there is no entry in
   /etc/passwd for them.  They only exist to the e-mail system.  You will
   be able to setup virtual users for both the main domain of the box and
   virtual domains that the box hosts.  You will also be able to use the
   same user name for different domains, there are no limitations with
   user names.

               Get down Open WebMail, Postfix, and vm-pop3d and install
   them all.  Read through how vm-pop3d works so you have a general
   understanding of how it's able to service virtual users.

               We are going to configure OWM to use the standard unix
   authentication, so we need to setup auth_unix.pl to point to our
   passwd file.  For me this is /etc/shadow,  your system may vary.

               Next we need to setup auth_pop3.pl.  This authentication
   module will be used for virtual users and users to virtual domains.
   Make the appropriate changes to  $pop3_authserver, $pop3_authport, and
   $local_uid.

               Now we need to make changes to openwebmail.conf.  Setup
   mailspooldir to point to your normal mail spool directory.  For me
   this is /var/spool/mail.  This is the spool that actual users get
   their mail delivered to.  We also want to setup OWM to use unix sytle
   authentication,  so set auth_module  to  auth_pop3.pl.

   mailspooldir            /var/spool/mail.
   auth_module             auth_unix.pl.

               Also add these configurations to openwebmail.conf:

   use_homedirspools          no
   use_homedirfolders         no
   enable_changepwd           no
   enable_autoreply           no
   enable_setforward          no
   enable_loadfrombook        no
   getmail_from_pop3_authserver    no
   auth_withdomain            no

               This will configure OWM so that real users will be able to
   access either regular e-mail using Open WebMail without having to do
   anything special.  When a real user of the system logs in using just
   their user name (e.g. john), then OWM will authenticate that user
   using the systems passwd file.

               Virtual users must be setup and created before they will
   work.

   Step 1

               If this virtual user is at a virtual domain your machine
   is hosting, then add a mapping for the user in
   /etc/postfix/virtual.cf.  The lines you will add will look something
   like this:

   virtualdomain                  anything
   username@virtualdomain         username.virtualdomain

               The first line only needs to be done once per virtual
   domain name.

               Example:

   virtualcompany.com             anything
   john@virtualcompany.com        john.virtualcompany.com

               This will map any incoming mail to john@virtualcompany.com
   to a user named john.virtualcompany.com.   Once you've added this run
   the command 'postmap /etc/postfix/virtual.cf' to update the virtual
   table.

               Note: if this is a virtual user to the main domain of the
   machine, you don't have to add an entry to virtual.cf.

   Step 2

               Add a local alias to /etc/aliases for this user.  If this
   is a virtual user to the domain of the host machine, then you'll add a
   line like this:

   username:  /var/spool/virtual/domain/name

               For example, if you are adding a virtual user (joe) for
   the domain of the machine (widgets.com), you'd add:

   joe:       /var/spool/virtual/widgets.com/joe


               On the other hand, if it's to a virtual domain, then the
   username should be the username.domain and 'domain' will be that
   virtual domain.  Continuing the example in step 1, we'd add:

   john.virtualcompany.com:
   /var/spool/virtual/virtualcompany.com/john

               After that we need to update Postfix's alias database, so
   run the command 'postalias /etc/aliases'.

               Step 1 tell postfix that mail directed to
   john@virtualcompany.com  should first be mapped to a user named
   john.virtualcompany.com  and step 2 tells postfix to then place that
   users mail in the mail spool file
   /var/spool/virtual/virtualcompany.com/john

   Step 3

               Now we need to make a mail spool directory for it.  Make a
   directory in /var/spool/virtual with the name of the domain.

               For our virtual user joe at the main domain of the host
   machine, we'd do:

   mkdir /var/spool/virtual/widgets.com

               For our virtual user john at the virtual domain , we'd do:

   mkdir /var/spool/virtual/virtualcompany.com

               Once that's done we need to execute these two commands:

   chown root.mail /var/spool/virtual/domain
   chmod og+wt /var/spool/virtual/domain

               For our example we started in step 1, we'd execute:

   mkdir /var/spool/virtual/virtualcompany.com
   chown root.mail /var/spool/virtual/virtualcompany.com
   chmod og+wt /var/spool/virtual/virtualcompany.com

               If this mail spool directory already exists we can skip
   this step.  Thus, once you perform this step for one virtual user at
   this domain, any other virtual users at this domain you create you
   don't have to do this.

   Step 4

               Now we need to configure OWM for virtual users at these
   domains using Open WebMail's per site configuration feature.  Go to
   /usr/local/apache/cgi-bin/openwebmail/etc/sites.conf  (or to your Open
   WebMail location) and make a new file named 'domain', then add these
   lines:

   mailspooldir            /var/spool/virtual/DOMAIN
   auth_withdomain         yes

               For our virtual user joe at widgets.com we'd create a text
   file called widgets.com containing:

   mailspooldir            /var/spool/virtual/widgets.com
   auth_withdomain         yes
   auth_module             auth_pop3.pl

               And for john at virtualcompany.com, create a text file
   called virtualcompany.com  containing:

   mailspooldir            /var/spool/virtual/virtualcompany.com
   auth_withdomain         yes
   auth_module             auth_pop3.pl


               This will configure OWM so that when a virtual user logs
   in using their full e-mail address (e.g. john@virtualcompany.com, or
   joe@widgets.com),  OWM will use the configuration file for that domain
   (i.e. virtualcompany.com or widgets.com).  The config file for these
   sites will tell OWM to authenticate the user using the pop3
   (vm-pop3d).  The full address will be sent to vm-pop3d which will then
   authenticate this user using the virtual passwd for this domain.

   Step 5

               We need to make a directory in /etc/virtual to hold the
   password file for this domain.  This is the directory that vm-pop3d
   looks in when it authenticates a user.  So we'd do this:

   mkdir /etc/virtual/domain

               For our user joe, we'd execute:

   mkdir /etc/virtual/widgets.com

               For our user john, we'd execute:

   mkdir /etc/virtual/virtualcompany.com


   Step 6

               Now we need to create a password for this user.  Using the
   addpasswd script laid out on the vm-pop3d homepage, we'd execute this
   command:

   addpasswd username password >> /etc/virtual/domain/passwd

               For our example, if user john wanted the password
   'turtle', we'd execute:

   addpasswd john turtle >> /etc/virtual/virtualcompany.com/passwd



   Conclusion

               And that's it!  A real user with an e-mail account at the
   domain of the machine can log into Open WebMail by just putting in
   their user name in the login screen.  A virtual user needs to put in
   their full e-mail address (i.e. username@domain).

               For pop3 mail retrieval, a real user would send just their
   user name to the pop3 server, a virtual user would send their full
   e-mail address (in either the form 'username:domain" or
   'username@domain').