vpopmail Adminstration Guide

by Ken Jones

http://www.inter7.com/vpopmail

Quick Install Guide

To quickly install vpopmail

unpack vpopmail distribution

add vchkpw group

add vpopmail user with vchkpw group

./configure

make

make install-strip

You are now ready to add virtual domains and virtual users. See vadddomain and vadduser. You also need to modify your pop server startup line to use the vchkpw program for authentication.

Setting up all email to be virtual

We recommend that all domains be setup as virtualdomains.

Configuration options

Most used options

--enable-roaming-users=n|y Enable or disable open relay after pop authentication. Default is no

Setting this to yes means that the clients IP address is added to the list of IP's that are allowed to relay through the smtp server after they authenticate with pop. A cronjob program, clearopensmtp, clears out any IP's that were authenticated over 3 hours ago. This option requires you run the smtp server with tcpserver and the -x /etc/tcp.smtp.cdb option (or where ever you put your tcp.smtp.cdb file).

--enable-hardquota=#|n Set and Enable hard quota or n for no quota

Set's the default hard quota limit for each pop account. The default is 50 megs. Any incoming mail which would take the user over their hard quota limit is bounced with a message. This message can be customized.

If you wish to turn off quotas set this option to NOQUOTA, i.e. --enable-hardquota=NOQUOTA

--enable-default-domain=name Default domain name, default is null.

We recommend you run all your email as virtual domains. You can pick one domain to be the default. If you have just one domain set it with this option. The default domain name users can authenticate with just their user name, and don't need to use <user>%<virtualdomain>.

--enable-ip-alias-domains=y|n enable virutal domain lookup via reverse ip address lookup for virtual domains.

By default, ever domain uses name based virtual domains. That is: users must supply their domain name in their pop name. i.e. <user>%<virtualdomain>. This can be overridden for one domain using the --enable-default-domain option.

Vpopmail also supports IP based virtual domains. If this option is turned on, and the user does not supply %<virtualdomain> then a reverse IP lookup is done on the server IP address that the client connected to. If the servers IP address resolves to a domain name, then vpopmail uses that name as the domain. For example:

IP w.x.y.z resolves to test.com. User sets their pop server ip to w.x.y.z and connects. Vpopmail gets the connection, checks the IP of the SERVER side of the connection. Does a reverse IP lookup and obtains test.com. User sends joe as their pop user name. Vpopmail uses test.com as the domain.

You can mix and match name and ip based virtual domains.

--enable-relay-clear-minutes=360 expire time for roaming users after pop authentication.

If --enable-roamin-users=y is set then this option sets how long clearopensmtp should keep IP's in the list. The default is 3 hours.

Mysql options

--enable-mysql=n|y use mysql, default is no

Enable using mysql authentication.

NOTE: be sure to edit vmysql.h and set the mysql server name/ip, mysql user and mysql users password. This user must have the ability to create a database vpopmail and create tables within that database.

--enable-sqlincdir= Directory where sql include files are.

Set the directory where the mysql include files are. By default it is set to /usr/local/mysql.

--enable-sqllibdir=/usr/lib/mysql Directory where sql libs are.

Set the directory where the mysql libmysqlclient.a file is. By default it looks in /usr/lib/mysql

--enable-sqllibs=mysqlclient libraries for sql linking.

Set the library to link in. By default this is libmysqlclient.a.

--enable-large-site=n|y Default is no, tune for large numbers of users per domain

By default vpopmail puts all domain information in one table - vpopmail. This is the most efficent method for sites most sites. If you are running one site with a very large number of users, you may want to set this option to be yes. If set to yes, vpopmail will create a table for each virtual domain. The main difference is that the domain name is not stored in the database since the table contains the domains name. For sites with 500,000+ users it can save significant disk space. However, for sites with large numbers of virtual domains it can decrease mysql system performance.

Vpasswd/cdb options

--enable-ucspi-dir=dir Directory where the compiled ucspi package is.

Set the directory where the ucspi-tcp package is located. By default this is set to ../ucspi-tcp-0.84. Vpopmail uses headers in this directory and uses two .a files.

Logging options

--enable-logging=e|y|n Turn on (y) or off (n) logging to syslog or (e) only log errors

Set the level of logging. By default it only logs pop authentication errors. You can turn off all logging by setting it to no. And you can log all pop authentications by setting it to yes.

--enable-log-name=vpopmail set syslog name.

Over ride the default vpopmail syslog name.

User/group options

--enable-vpopuser=vpopmail user vchkpw was installed as.

If for some reason you want to install this package under a different user name, use this option.

--enable-vpopgroup=vchkpw group vchkpw was installed as.

If for some reason you want to install this package under a different group name, use this option.

--enable-admin-email=email-address e-mail of system administrator.

Override the default email administrator address.

Directory and file location options

--enable-tcpserver-file=/etc/tcp.smtp File where tcpserver -x relay information is stored.

Set the file name of your tcp.smtp file. By default the configure program looks in /etc and then in /etc/tcprules.d directories.

--enable-qmaildir=dir directory where qmail is installed.

If you installed qmail into a directory other than /var/qmail, use this option.

--enable-tcprules-prog=/usr/local/bin/tcprules where is your tcprules program.

If you installed the tcprules program into a directory other than /usr/local/bin, use this option.

--enable-apop-file=/etc/apop-secrets directory where apop secrerts are stored.

Over ride the default location of the apop-secrets file.

Other options

--enable-apop=y|n Enable or disable apop authentication.

Disable apop by setting this option to no. The default is yes (pop and apop).

--enable-passwd=y|n Enable or disable /etc/passwd (or shadow) authentication.

Over ride the automatic configuration. By default the configuration program will automatically detect if you are using passwd and shadow passwords. By setting this option to no, you will disable all /etc/passwd authentication.

Qmail and Virtual domains

Qmail has an idea of email domains that are "local" and "virtual". Local domains are ones which primarily match against /etc/passwd. Virtual domains match against domains listed in the qmail control file "virtualdomains". Vpopmail makes use of the qmail users/assign file and virtualdomains file. The users/assign file gets compiled into a users/cdb file. It is a hashed database to speed searches for patterns. If a pattern is matched then qmail delivers the email to the directory defined in the file using the uid and gid which as also defined. Vpopmail makes use of this method to have qmail deliver all virtual domain email as the single uid/gid vpopmail/vchkpw. It also uses it to direct delivery to a vpopmail/domains/<virtualdomain> directory.

Once qmail-local gets the information from the users/assign file it performs standard .qmail file processing in the directory. Normal .qmail-<user> files can be used for forwarding, aliases or invoking programs such as ezmlm. If no matches are found qmail-local looks for a .qmail-default file. This is the last stage in qmail-locals delivery mechansim. Vpopmail uses this file to invoke the vdelivermail program. This program takes two parameters, the first is not used (it is there for backward compatibility). The second parameter is the default delivery if a virtual domain user can not be found. Basicly, it can be a directory to deliver the email to, an email address to forward the email to, the string "bounce-no-mailbox" to bounce the mail back to the sender or the string "delete" to drop/delete the mail.

Once vdelivermail is started up, it uses the core vpopmail api calls to check for a virtual domain user. If the user exists, the email is delivered into their directory. If vpopmail was configured for hard quotas (default is yes with 50Meg quota), then the size of the users current email files in their Maildir/new and Maildir/cur directories are counted. If the user is over quota the email is bounced back to the user with a bounce message that can be customized. If the message is 1Kbytes or smaller the email will always be delivered. This is so system administration programs can always get a message through to the user.

Converting current user accounts

The vconvert program can convert email accounts from one format into another format. Conversion can be between /etc/passwd, vpasswd files, mysql (small version) and mysql (large version.

Most current vpopmail users would probably be interested in how to convert current domains into mysql domains. To make it simple to convert an entire machine to mysql, use the following command: vconvert -c -s This will go through all the domains in ~vpopmail/domains directory and read each vpasswd file and load the contents into the vpopmail.vpopmail mysql table. The vpasswd file is left untouched for safety. Vconvert can also be run against one or more domains at a time. This is done by running the command as so: vconvert \c \s domain1 domain2 ...

To convert all users (except root and system accounts) into a mysql domain run the following command: vconvert -e -s domain. This reads all /etc/passwd accounts and creates mysql entries using their passwords. The passwords can be in either /etc/passwd or /etc/shadow. These passwords should work under vchkpw authentication program.

Security and pop server under tcpserver

If all of your pop email accounts are under virtual domains, you can increase the security of your pop server by running it under the uid and gid of vpopmail/vchkpw using the tcpserver -u and -g options.

Commands

Quota's

Bouncing mail

Directory structure

Overall vpopmail directory structure

Vpopmail gets it's own home directory. Under this directory there are the following:

bin - contains all the binaries

lib - contains the libvpopmail.a file

include - contains the C header files

users - for backward compatibility for people who mix /etc/passwd users with vpopmail users in one domain

domains - where all the virtual domains are kept.

Virtual domain user directory structure

Vpopmail uses an adaptive directory structure based on a state file ".dir-control" which is automatically managed by the core vpopmail api functions "vadduser" and "vdeluser". For sites with 100 users or less, all user directories are stored in the virtual domain directory. For sites that go above 100 users the adaptive directory structure goes into effect. The basic idea is to break up the user Maildir directories across multple directories and sub directories so that there are never more than 100 user directories in a single directory.

The default directory setup allows for 62 directories in 3 levels and 100 user directories per directory. The total number of user directories is equal to 100 + (62 * 100) + (62 * 62 * 100) + (62 * 62 * 62 * 100) = over 24 million directories. This should be more than sufficent for any site and probably goes beyond the technology of directory structures.

If you are going to be storing large numbers of user directories, make sure you set your file system to have a higher than normal percentage of inodes.

Vpopmail will automatically create these directories and sub directories as needed and populate each directory with up to 100 user accounts. As soon as a directory reaches 100 users it will create the next directory or sub directory and store the new users directory there.

Look in the source code release directory contrib/ for a contributed directory reorganization program.

Internationalization

There is two messages that get inserted into emails. These are both for bounced messages. The first is for no such user and the second is for user over quota. Site administrators can customize these messages by creating a .over-quota.msg and .no-user.msg file in a virtual domain directory or in the main virtual domain directory. If a .over-quota.msg file or .no-user.msg file are not found in the virtual domain directory, then they are checked for in the main virtual domain directory. If they are not found there, then the default compiled message is included in the bounce message.

dot-qmail processing

Every virtualdomain get's it's own directory under ~vpopmail/domains. Qmail's user/assign file gets an entry for each domain that

points qmail-local deliveries into this directory. Therefore, all normal .qmail file processing works in each virtual domain. .qmail files just need the user name extension to work, i.e. .qmail-joe for user joe. Ezmlm uses .qmail files for processing, so it will work under vpopmail.

If no user matches a .qmail file then the .qmail-default file is processed. This file contains the vdelivermail program. This program reads the authentication database (mysql or vpasswd.cdb) and deliveres the mail into the users directory. The last parameter of vdelivermail can be a maildir owned by vpopmail/vchkpw so that all default mail reception ends up there. Or it can have an email address, and all default mail is forwarded to this address. Last but not least, the last parameter to vdelivermail can be the text bounce-no-mailbox. This will bounce all non matching emails back to the sender.

qmailadmin

Qmailadmin provides a web based interface for managing vpopmail domains. As of version 0.26, it uses the vpopmail api. Which means it can manage mysql or vpasswd.cdb authentication. It allows for adding pop users, managing forwards/aliases, ezmlm mailing lists and autoresponders.

sqwebmail

Sqwebmail is a web based email client. It reads and writes directly to the users Maildirs. It can talk to vpopmail vpasswd files. We have a modified version of 0.24 on http://www.inter7.com/vpopmail which uses vpopmail api. It also supports setting the users password and lets the user forward their mail. Hopefully these changes will be intergrated into the standard distribution :)

courier-imap

Courier-imap is a IMAP server that supports Maildirs. It's current release supports vpopmail vpasswd files. We will be integrating the vpopmail api into the main distribution soon.

mysql authentication

cdb authentication

vpopmail API

As of version 3.4.10 vpopmail builds a library located in ~vpopmail/lib/libvpopmail.a . Linking this library into your application will provide access to the following C functions. The associated header files are located in ~vpopmail/include.

int vadddomain( char *domain)

domain = the new virtual domain

int vdeldomain( char *domain )

domain = virtual domain to delete

int vadduser( char *user, char *domain, char *password, int apop)

user = new user name

domain = virtual domain

password = clear text password

apop = 0 for pop and 1 for apop

int vdeluser( char *user, char *domain)

user = user to delete

domain = virtual domain

int vpasswd( char *user, char *domain, char *password)

user = user to change password for

domain = virtual domain

password = clear text password

int vsetuserquota( char *user, char *domain, char *quota)

user = user name to change quota for

domain = virtual domain

char = quota in bytes. M/m and K/k abbrieviations apply. 5M 5m and 5000000 all equal 5 million bytes hard quota

vpopmail authentication API

int vauth_addomain( char *domain)

domain = domain name to add to authentication system

int vauth_deldomain( char *domain)

domain = domain name to delete from authentication system

int vauth_adduser( char *user, char *domain, char *crypted_password, char *dir, int apop)

user = user to add from authentication system

domain = domain name

crypted_password = encrypted password

dir = full path to directory where users Maildir is stored.

apop = 0 for POP and 1 for APOP

int vauth_deluser( char *user, char *domain)

user = user to delete from authentication system

domain = domain name

int vauth_password( char *user, char *domain, char *crypted_password)

user = user to change password in authentication system

domain = domain name

crypted_password = the encrypted password

int vauth_setquota( char *user, char *domain, char *quota)

user = user to set quota for in authentication system

domain = domain name

quota = quota in bytes or using M/m or K/k abbrieviations. 5M = 5m = 5000000

struct *passwd vauth_getpw( char *user, char *domain)

user = user name to retrieve password entry from authentication system

domain = domain name

int vauth_setpw( struct *passwd, char *domain)

passwd = pointer to a passwd structure to store in authentication system.

domain = domain name for this passwd structure

struct *vauth_user( char *user, char *domain, char *password, char *apop)

user = user name to authenticate

domain = domain name

password = clear text password

apop = not used in version 3.4.10

struct *vauth_getall( char *domain, int first, int sort_it )

domain = domain name to retrieve password structure from authentication system

first = 1 to get first record, 0 = get next record

sort_it = 1 to have the user list sorted alphabetically. This has no effect on vpasswd/cdb method, since all users are added alphabetically. With mysql it adds an order by pw_name to the query.

int vget_limits( char *domain, struct vlimits *limits )

domain = domain name to get limits for

limits = name of limits structure

int vset_limits( char *domain, struct vlimits *limits )

domain = domain name to set limits for

limits = name of limits structure

int vdel_limits( char *domain )

domain = domain name to delete limits for

limits = name of limits structure