How to setup virtual users on Open WebMail using Postfix & vm-pop3d

Written by Kevin L. Ellis


            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 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  You could also use for this, which I'll talk about briefly later.  The only thing you need to setup in 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  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 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 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 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 

mailspooldir            /var/spool/mail

            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/  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:             anything

            This will map any incoming mail to to a user named   Once you've added this run the command 'postmap /etc/postfix/' 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

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 (, you'd add:

joe:       /var/spool/virtual/

            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:      /var/spool/virtual/

            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  should first be mapped to a user named  and step 2 tells postfix to then place that users mail in the mail spool file /var/spool/virtual/

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/

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

mkdir /var/spool/virtual/

            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/
chown root.mail /var/spool/virtual/
chmod og+wt /var/spool/virtual/

            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 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

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/
vdomain_postfix_postalias     /usr/sbin/postalias
vdomain_postfix_postmap       /usr/sbin/postmap


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

mailspooldir            /var/spool/virtual/
auth_withdomain         yes
use_homedirspools       no
use_syshomedir          no
enable_autoreply        no
enable_setforward       no

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

mailspooldir            /var/spool/virtual/
auth_withdomain         yes
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. or,  OWM will use the configuration file for that domain (i.e. or  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/

            For our user john, we'd execute:

mkdir /etc/virtual/

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/

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


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


            There might be situations where you want or need to use the 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