From Qmailwiki
Revision as of 16:14, 14 April 2005 by (Talk)
Jump to: navigation, search



vpopmail is a set of API that manages virtual user accounts on a qmail system, and handles delivery for these virtual users. The command-line utilities, and Qmailadmin all use the vpopmail API, provided by the vpopmail library to manage the system.


Roaming Users

Roaming users provides a non-SMTP_AUTH authentication system for allowing users with dynamic IPs to send mail through the server without allowing relay from non-authenticated users. After a user has authenticated via POP3, IMAP, etc, their IP is set allowed to relay for the next three hours. This provides them plenty of time to read and respond to all their email. Successive authentications during this time extend the time limit.

Where do I get vpopmail?

You can get the most stable release from our website, at http://www.inter7.com, and you can get the current stable, development, and past releases at our Sourceforge page at http://sourceforge.net/projects/vpopmail/.

Command-line utilities

All binaries for user management are, by default, under /home/vpopmail/bin. Almost all the binaries in this directory can be executed, without arguments, to display a usage.


Adds a new domain to the mailserver

vadddomain: usage: vadddomain [options] virtual_domain [postmaster password]
options: -v prints the version
         -q quota_in_bytes (sets the quota for postmaster account)
         -b (bounces all mail that doesn't match a user, default)
         -e email_address (forwards all non matching user to this address [*])
         -u user (sets the uid/gid based on a user in /etc/passwd)
         -d dir (sets the dir to use for this domain)
         -i uid (sets the uid to use for this domain)
         -g gid (sets the gid to use for this domain)
         -O optimize adding, for bulk adds set this for all
            except the last one
         -r[len] (generate a len (default 8) char random postmaster password)

 [*] omit @-sign to deliver directly into user's Maildir: '-e postmaster'


Aliases one domain to another. All users, forwards, autoresponders, etc are the same across the real domain, and the aliased domain.

vaddaliasdomain: usage: [options] real_domain alias_domain
options: -v (print version number)
note: for backward compatability, you can swap real_domain and alias_domain.


This command creates an entry in the qmail/users/assign file directing all transactions for the new, alias domain name, to the current, real domain. This eliminates needing symlinks, and other harddrive intensive operations.


Deletes a domain from the mailserver, all users, and all mail under this domain

vdeldomain: usage: [options] domain_name
options: -v (print version number)


Adds a mailbox to a domain

vadduser: usage: [options] email_address [passwd]
options: -v (print the version)
         -q quota_in_bytes (sets the users quota, use NOQUOTA for unlimited)
         -c comment (sets the gecos comment field)
         -e standard_encrypted_password
         -n no_password
         -r[len] (generate a len (default 8) char random password)


Deletes a mailbox from a domain, including all mail for that user

vdeluser: usage: [options] email_address
options: -v (print version number)


Return basic information about one or all domains hosted on the server

vdominfo: usage: [options] [domain]
options: -v (print version number)
         -a (display all fields, this is the default)
         -n (display domain name)
         -u (display uid field)
         -g (display gid field)
         -d (display domain directory)
         -t (display total users)

Note that to return the usage with vdominfo, you must type

vdominfo -h


Return information about user accounts

vuserinfo: usage: [options] email_address
options: -v (print version number)
         -a (display all fields, this is the default)
         -n (display name field)
         -p (display crypted password)
         -u (display uid field)
         -g (display gid field)
         -c (display comment field)
         -d (display directory)
         -q (display quota field)
         -Q (display quota usage)
         -C (display clear text password)
         -l (display last authentication time)
         -D domainname (show all users on this domain)


Modify user settings and flags

vmoduser: usage: [options] email_addr or domain ( for the entire domain )
options: -v ( display the vpopmail version number )
         -n ( don't rebuild the vpasswd.cdb file )
         -q quota ( set quota )
         -c comment (set the comment/gecos field )
         -e encrypted_passwd (set the password field )
         -C clear_text_passwd (set the password field )
the following options are bit flags in the gid int field
         -u ( set no dialup flag )
         -d ( set no password changing flag )
         -p ( set no pop access flag )
         -s ( set no smtp access flag )
         -w ( set no web mail access flag )
         -i ( set no imap access flag )
         -b ( set bounce mail flag )
         -o ( set override domain limits flag )
         -r ( set no external relay flag )
         -a ( grant qmailadmin administrator privileges)
         -0 ( set V_USER0 flag )
         -1 ( set V_USER1 flag )
         -2 ( set V_USER2 flag )
         -3 ( set V_USER3 flag )
         -x ( clear all flags )
         -f ( disable spamassassin)
         -F ( delete spam)


The vmoduser command is very useful for more advanced user options. Each user has a set of flags that can be set on them. For instance, 'No webmail' will disallow them to use a webmail interface, and 'No POP3' will not allow them to download mail via POP. Generally people use these flags to nudge customers who haven't paid, or to provide specific services to users who are paying for specific services (ie: webmail or pop3, etc). You can also set a flag which disallows them to send mail. Other than user flags, one can also set quotas with this command.

  • -s ( no smtp access ) if you have qmail-smtpd patched to support smtp authentication using the vchkpw program, then this option will cause the smtp connection to be dropped. Which in effect makes it impossible for the user to send email.
  • -r ( no external relay flag ) With this option turned on, the user will be able to only send email to local accounts. They will not be able to send email out to the internet. For example: A company can create internal email only accounts.


Short for vpopmail bulletin, vpopbull mass-mails local users an email.

usage: vpopbull [options] -f [email_file] [virtual_domain] [...]
       -v (print version number)
       -V (verbose)
       -f email_file (file with message contents)
       -e exclude_email_addr_file (list of addresses to exclude)
       -n (don't mail. Use with -V to list accounts)
       -c (default, copy file)
       -h (use hard links)
       -s (use symbolic links)


The vpopbull command solves a number of problems with trying to mail all your users. Firstly, you dont need to maintain a list of all your user accounts to email to. Secondly, emailing users through the actual qmail server would be inefficient. vpopbull drops messages directly into their Maildir directories where they can be picked up by POP3, webmail, etc, making the operation a simple copy operation instead of an actual mailing operation.

The email sent must be a fully valid email message, including From, and Subject headers, followed by a blank line, followed by the message. The one exception is that a To header should not be included.

From: <example@example.com>
Subject: Server maintenance

Dear example.com users,

   We will be performing maintenance on the mail server tomorrow morning.
The maintence window will be between 3am and 5am, and the server will be
down turning this time.

Thank you for your patience,
The example.com Staff

More complicated messages, including ones with attachments, etc, can also be made, however the specifics of generating a multipart message is out of the scope of this document.


vpasswd is used to change passwords for users on the system.

vpasswd: usage: [options] email_address [password]
options: -v (print version number)
         -r generate a random password


vchangepw allows changing of passwords for email addresses hosted on the system. This differs from vpasswd in that it requires you to know the current password for the email address. Note that there is no usage for this binary.

Tom Collins submitted a patch to the vpopmail tree including this binary


vsetuserquota is used to modify quotas for a single user, or on all users on a domain. See Vpopmail#Quotas for details on quotas.

vsetuserquota: [options] email_address|domain_name quota
-v (print version number)

If you specify a domain name rather than an email address,
the quota will be applied to all users in that domain

Other binaries

You will probably notice that there are binaries in the bin directory that aren't listed above. These binaries are either used by vpopmail to handle delivery or other aspects of the mail system management, or they are used by more advanced users or users who are migrating data between databases.


When vpopmail has been compiled with the --enable-roaming-users=y flag enabled, this binary is run out of the crontab every 5 minutes to update the list of IPs that are no longer allowed to send mail. This is a binary used by the Roaming Users feature of vpopmail.


When vpopmail has been compiled with the --enable-valias=y flag, this binary will find all dotqmail files under vpopmail and convert them to valias entries in the database.


When configured with --enable-valias=y, the valias command can be used to add, edit, and delete valiases from the database.


vchkpw is the authentication mechanism used by qmail to check passwords required for downloading mail, and in the case of SMTP_AUTH, sending mail.


vconvert is used during conversions and migrations between different database methods. Specifically, vconvert can convert to and from several databases, all information about the users on a vpopmail system.

vconvert: usage
 The first option sets which format to convert FROM,
 the second option sets which format to convert TO.
 -e = etc format
 -c = cdb format
 -m = sql format
 -S = set sqwebmail passwords
 -v = version
 -d = debug info


vdelivermail is vpopmail's delivery agent. It handles delivery of messages, bouncing, catch-alls, etc. You will find calls to vdelivermail in the .qmail-default file under each domain.


vdeloldusers compares the last authentication time for all users against an age in days provided on the command-line, and removes all users which match.

vdeloldusers: usage: [options]
options: -a age_in_days (will delete accounts older than this date)
                        (default is 6 months or 180 days)
         -v (print version number and exit)
         -d [domain] (process only [domain])
         -e (process every domain)
         -D (actually delete users. no users are deleted without this option)
         -V (verbose -- print old users that will be deleted)


vipmap stands for Vpopmail IP Map. It maps connections on specific IPs, to a particular domain, enabling users to provide just their username for authentication as opposed to the standard user@domain syntax, providing they have connected to a mapped IP.

vipmap: usage: [options] ip domain
options: -d delete mapping
         -a add mapping
         -p print mapping
         -v show version


vkill is used internall by vpopmail to kill it's own processes


vmkpasswd generates the vpasswd.cdb files seen under each of your domain directories. The CDB format allows for faster lookups of information by providing a disk-based hashtable database.


vmoddomlimits provides a command-line interface for modifying the .qmailadmin-limits files that may appear under your domains' directories. This file specifies how many users, forwards, mailing lists, etc that a user with the postmaster password may create with Qmailadmin.

vmoddomlimits: usage: [options] domain
options: -v ( display the vpopmail version number )
         -d ( use the vlimits.default file, instead of domain )
         -S ( show current settings )
         -D ( delete limits for this domain, i.e. switch to default limits)
         -Q quota-in-megabytes ( set domain disk quota, '100' = 100 MB )
         -q quota-in-bytes ( set default user quota, '10M' = 10 MB )
         -M count ( set domain max msg count )
         -m count ( set default user max msg count )
         -P count ( set max amount of pop accounts )
         -A count ( set max amount of aliases )
         -F count ( set max amount of forwards )
         -R count ( set max amount of autoresponders )
         -L count ( set max amount of mailing lists )
the following options are bit flags in the gid int field
          -g "flags"  (set flags, see below)
          gid flags:
            u ( set no dialup flag )
            d ( set no password changing flag )
            p ( set no pop access flag )
            s ( set no smtp access flag )
            w ( set no web mail access flag )
            i ( set no imap access flag )
            r ( set no external relay flag )
            c ( set no spamassasssin flag )
           x ( set delete spam flag )
the following options are bit flags for non postmaster admins
         -p "flags"  (set pop account flags)
         -a "flags"  (set alias flags)
         -f "flags"  (set forward flags)
         -r "flags"  (set autoresponder flags)
         -l "flags"  (set mailinglist flags)
         -u "flags"  (set mailinglist users flags)
         -o "flags"  (set mailinglist moderators flags)
         -x "flags"  (set quota flags)
         -z "flags"  (set default quota flags)
         perm flags:
            a ( set deny all flag )
            c ( set deny create flag )
            m ( set deny modify flag )
            d ( set deny delete flag )


vpopmaild is a daemon, which is under development still, which provides a network-based interface to the vpopmail API. There is no further support yet available for this part of vpopmail.


vqmaillocal is a development testing program, and has no impact on a vpopmail system.

Other Features

Here is a list of features that are not so commonly used, but definately have their place.


valias provides use of special delivery instructions normally found in dotqmail, from a database. Depending upon systems, this may or may not increase efficiency.


Documentation about the vpopmail API to come


How to troubleshoot vpopmail

vpopmail is relatively easy to troubleshoot, given a little background knowledge on how it processes authentication information, and message delivery information. Before you head down below for specific information about a problem you might be having, get aquainted with how vpopmail handles your day-to-day mail activities.


In order to authenticate users, there's a series of steps that is taken. We will be examining vchkpw, the standard binary used for authentication with POP3.

  • Firstly, vchkpw expects a valid username.

Because vpopmail is a virtual domain package, it also needs to know what domain they're on. Depending upon the system configuration, the username will sometimes be simply 'username', with a domain mapped either to an IP, or as a default domain, but generally the username will be 'user@domain'. Does the username contain entirely valid characters? Does the domain contain valid characters?

  • Next vpopmail opens the qmail/users/cdb

file to determine if the domain is valid. Here is where permissions errors come in. Can the process trying to authenticate access the cdb file? Does the cdb file exist? Is it updated with the latest information from the qmail/users/assign file? Is there an issue with the contents of the assign file causing the cdb file not to be updated? As you can see, each step can have a number of actual causes, but generally they all cause a similar symptom, which can make determining the actual cause a little difficult.

  • The next step is to determine if the username provided exists on that domain.

Depending upon the authentication storage scheme, yet more issues can arise here. For the sake of this document, we will assume CDB, however, those of you using MySQL, or another network-based DB may wish to make sure your authentication information is correct. Can the process wishing to authenticate access the vpasswd.cdb file? All processes accessing authentication information for vpopmail must be at least SUID/SGID vpopmail. Note that files under the vpopmail directory should NEVER have their permissions changed to be read by users other than the vpopmail user. Does the vpasswd.cdb file exist? Has it been updated with the latest information from the vpasswd file? Does the vpasswd file contain entirely valid syntax?

  • Next it compares their password.

Obviously the question here is, do they have the correct password?

  • Now user flags are checked.

Are they allowed to access the POP server? At this point, other flags are checked for other services as well. SMTP, IMAP, etc.

  • Now we set up the environment to deal with their mailbox files.

Are the permissions on the user's home directory and Maildir correct?

  • The next, and final step is to execute the POP handler.

If this part fails, make sure your POP binary is there, and that it can be executed by the process.

Specific Issues

One of my users can't authenticate via POP3

  • Is the user using the correct login name?

Sometimes users are simply using the wrong login name. Try verifying their login information yourself before going any further.

  • Is the user using the correct login syntax?

Depending upon the configuration of the system, one may need to log in with different username formats. user@domain is the most common. Be sure your users know that this is the correct format for authenticating for mail.

  • Is the user using the correct password?

Systems with clear-text passwords enabled can allow administrators and technical staff to quickly diagnose this issue.

  • Is the POP3 server running as root?

The POP3 server must run as root so that it may change the proper UID/GID after it determines what that UID/GID is.

  • Does the qmail/users/assign file contain the domain?
  • Does the qmail/users/assign file contain proper syntax?
  • Is the qmail/users/cdb file up to date?
  • Are permissions correct on the vpopmail home directory and sub-directories?

When using MySQL for authentication, I get the error vmysql: sql error[3] MySQL server has gone away

This is almost always caused by permissions, or authentication problems. First, using the information from ~vpopmail/etc/vpopmail.mysql, try to access the MySQL database via the mysql client as the vpopmail system user. (Depending upon your system, you may need to use sudo)

# su vpopmail
$ mysql -u vpopmail -p vpopmail
Enter password:

At this point, you may have received any number of errors. If you get to a MySQL prompt, try the following:

mysql> show tables;

Pick a table. vpopmail is a good one to use

mysql> select count(*) from vpopmail;

The most common problem here is that vpopmail cant access the MySQL socket. Check the location where your MySQL server is creating the socket file, and be sure the vpopmail user can read and write to it.

Personal tools