owmvirtual.html

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