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.  Get all these working together before you proceed any further.

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

            Now we need to setup the authentication module for virtual users.  For this we are going to use auth_vdomain.pl.  You could also use  auth_pop3.pl for this, which I'll talk about briefly later.  The only thing you need to setup in auth_vdomain.pl is $local_uid and that needs to match how you configured Postfix and vm-pop3d.  All three need to match to use the same user id.  

            For Postfix you want to see what you have default_privs set to in main.cf.  For vm-pop3d you need to determine what user id it's running as for a virtual user.  You could either configure vm-pop3d by editing vm-pop3d.h and changing the #define VIRTUAL_UID or by passing it the '--user' or '-u' commandline option to change the user id it will run as.  In the auth_vdomain.pl module you need to set the my $local_uid line to match Postfix and what you have for vm-pop3d.  Postfix and vm-pop3d normally have these set to the nobody user, which is what auth_vdomain.pl defaults too, so you don't have to do anything.  I'm running my system to have Postfix and vm-pop3d set to user id of mail, so on my system I have vm-pop3d.h set as:

#define VIRTUAL_UID     8

            And in auth_vdomain.pl I have it set to:

my $local_uid=getpwnam('mail');

            If you wanted the whole thing to use a different user id, like vwebmail, you could create a new user and use that id.  Just make sure all three programs are using the same user id.  

            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 real users get their mail delivered to.  We also want to setup OWM to default to using unix style authentication,  so set auth_module  to  auth_unix.pl. 

mailspooldir            /var/spool/mail
auth_module             auth_unix.pl

            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. 

            I also have this in my config file:

enable_setfromemail    no

            I don't want my users to be able to change their e-mail address to anything they want, so I turn off this feature in the main config.

            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.  Adding new users can also be done through a web interface using openwebmail-vdomain.pl module.  We'll also set that up with an administrator so you can add, change, or delete users using a browser.
 

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
auth_module             auth_vdomain.pl
domainnames             DOMAIN
use_homedirspools       no
use_syshomedir          no
enable_autoreply        no
enable_setforward       no

            If you want to setup admin account(s) for this virtual domain then you should also turn on vdomain support and specify an admin user name.  Here's an example of how to turn it on with an admin named admin_tom:

enable_vdomain                yes
vdomain_admlist               admin_tom
vdomain_vmpop3_pwdpath        /etc/virtual
vdomain_vmpop3_pwdname        passwd
vdomain_vmpop3_mailpath       /var/spool/virtual
vdomain_postfix_aliases       /etc/aliases
vdomain_postfix_virtual       /etc/postfix/virtual.cf
vdomain_postfix_postalias     /usr/sbin/postalias
vdomain_postfix_postmap       /usr/sbin/postmap

            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_vdomain.pl
domainnames             widgets.com
use_homedirspools       no
use_syshomedir          no
enable_autoreply        no
enable_setforward       no

            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_vdomain.pl
domainnames             virtualcompany.com
use_homedirspools       no
use_syshomedir          no
enable_autoreply        no
enable_setforward       no

 
            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 virtual password files of vm-pop3d.  Optionally, you would also include all the vdomain config lines in each sites.conf file above if you wanted to use your browser to maintain the virtual users.
 

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
 
 

Possible Step 7

            If you are using Sendmail or are keeping your virtual user table in the normal Sendmail location you might need to set the virtusertable  configuration option.  What happens is OWM will pull in the virtual user table and transform the address before it tries authenticating the user using the vm-pop3d password files.  To resolve this add this option to openwebmail.conf:

virtusertable  /etc/notable

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'). 

Using  auth_pop3.pl

            There might be situations where you want or need to use the auth_pop3.pl module to authenticate your virtual users.  One situation would be where the mail for this virtual domain is stored on a different computer from where OWM is running.  For this you'd need to use this module.  It's fairly straight forward to setup, just make the appropriate changes to $pop3_authserver, $pop3_authport, and $local_uid for your system.  Once these are setup just change auth_module in your sites.conf file to use this module.

Last modified: March 13th, 2003