Vpopmail is a set of programs for creating and managing
multiple virtual domains on a qmail server.

It is geared toward ease of use for system administrators as well
as security and efficency. With the associated command line programs,
system administrators never need touch any of the underlying qmail files
and processes. All details are automatically handled.

--------------------------------------------------------------------------

Features include
  * Support for 1 to 23 million virtual email domains using a
    "grow as it goes" balenced directory tree.
  * Support for 1 to 23 million email users per domain using the
     same balenced tree structure.
  * Automates all qmail configurations into handy and scriptable
    command line programs and documented API library calls.
  * Automates Unix user/group/other permissioning of directories
    and files.
  * Supports authenticated relay control of your qmail smtp server.
  * Virtual email file/directories can be assigned to any user/group
    or do the default vpopmail/vchkpw 89/89.
  * Does not require email user accounts in /etc/passwd
  * Supports name or IP based virtual domains
  * Optionally automates support for:
      * Storing clear text passwords to help tech support workers
      * Record last authentication and automates deletion of
        stale accounts.
      * Storing alias/forwards in mysql or oracle
  * Configurable logging based on real world admin's comments
    and requirements.
  * Support for MySQL, Oracle, PostgreSQL, /etc/passwd, /etc/shadow,
     LDAP, Sybase, and default cdb authentication storage.
  * Delivers directly to Maildir for use with qmail-pop3d,
    .qmail files or any other Maildir program.
  * No need to have hundreds of .qmail files for virtual domains.
    Each domain gets it's own directory under vpopmail user with a
    separate password file for each domain.
  * Documented C library for all vpopmail features and transactions.

--------------------------------------------------------------------------

Latest versions of vpopmail are available from
http://sourceforge.net/projects/vpopmail

Recommended mailing lists:

mailto:vchkpw@inter7.com  -  general discussion

mailto:vpopmail-devel@lists.sourceforge.net - developement

--------------------------------------------------------------------------

For general installation instructions see INSTALL file

For people upgrading please read UPGRADE

--------------------------------------------------------------------------

By default, vpopmail stores all the account configuration and settings
in CDB files. CDB is a fast, reliable & simple database package that was
written by Dan Bernstein (the author of qmail). CDB is a good choice
for small vpopmail sites, but if you are running a larger server,
there are other authentication modules available that can help increase
performance or improve managability :

  For help with mysql see README.mysql

  For help with postgres see README.pgsql

  For help with LDAP see README.ldap

  For help with oracle see README.oracle

  For help with sybase see README.sybase

--------------------------------------------------------------------------

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.
Basically, it can be a directory to deliver the email to, an email address to
forward the email to or the string "bounce-no-mailbox" to bounce the mail
back to the sender.

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.

--------------------------------------------------------------------------

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

--------------------------------------------------------------------------

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.

--------------------------------------------------------------------------

Sorting qmail control files

vpopmail now sorts the qmail control files.  When adding a record vpopmail
uses an insertion sort to keep entries in order.  As it is doing this
sort, it verifies the order of all records in the file.  If if finds entries
that are out of order, it will sort the entire file by loading it into
memory and using qsort.

The files that are sorted:  rcpthosts, morercpthosts, virtualdomains,
users/alias.  I don't believe there will be any problem having these
files sorted, since they work in random order already.  It is much
more convienent searching for a domain with the files in order, and
programs like vdominfo and vpopmaild will report domain names in order.

At first glance, the sort order may seem bizarre, but once you work with
it, it should become natural.  Here is a small example from my test server:

developersdesk.com
admin.developersdesk.com
mail.developersdesk.com
test.developersdesk.com
developersdesk.net
developersdesk.org
mvas.com
mvas.net
mvas.org
test.com

They are actually sorted as if they were written like this:

developersdesk.com.mail

I bet for most people that tends to group customers together.  A special
sort may be apropriate for domains that end in a country code.  If someone
has any ideas, post it on the SourceFORGE vpopmail-devel mailing list.

--------------------------------------------------------------------------

The origin and status of the ActiveDirectory module is unknown

It is believed this module was written to allow a once-off migration
of accounts from an ActiveDirectory server over to another vpopmail
authentication system

This module has been removed.  The CDB and MySQL modules are the two
that are recommended for production environments.

--------------------------------------------------------------------------

I have tweaked a bit authvchkpw module for vpopmail. It includes most of the function needed to authenticate.
To install it you need to apply patch to vpopmail-5.4.26d. It modifies Makefile.am, configure.in, vpopmail.c,
vpopmail.h and creates a new file authvchkpw.c. I have tested it on my laptop and found it to work. But I give
no warranty.

AUTHMODULES in courier-imap needs to have authvchkpw as one of the authentication modules
The module does the following
reads 5 lines from imaplogin or pop3login. Authenticates the user and if successful executes the imapd or pop3d
executable. If the authentication is not successful, the data is passed to the next authmodule in chain.
On successful authentication the module adds entry to lastauth and a entry in relay table.
Instructions are in INSTALL section below. If you need more help let me know. If more modifications are needed
let me know.

	/*
	 * Courier-IMAP authmodules Protocol
	 * imap\n
	 * login\n
	 * postmaster@test.com\n
	 * pass\n
	 * newpass\n
	 * argv[0]=/var/indimail/libexec/authlib/authvchkpw
	 * argv[1]=/var/indimail/libexec/authlib/authpam
	 * argv[2]=/var/indimail/bin/imapd
	 * argv[3]=Maildir
	*/

INSTALLATION

1. Extract vpopmail Development tar.gz file vpopmail-5.4.26d.tar.gz
   wget http://downloads.sourceforge.net/vpopmail/vpopmail-5.4.26d.tar.gz
   cd /home/local/src
   gunzip -c vpopmail-5.4.26d.tar.gz |tar xf -

2. patch -p0 authvchkpw-vpopmail-5.4.26d.patch

3. cd vpopmail-5.4.26
   su
   ./configure # with the usual options
   make
   make install-strip

Version 4.9.7 Release Notes

FILE I/O and LOCKING CODE
------------------------------------------------------------------
The file i/o locking code has been audited. All code was changed to
update files by opening the orignal file in read only mode, unless
it is the first time, then create it. Then open a temp file with
a .pid extension. Make all the changes to the temp file. Then use
the rename(2) function call to automically move the new file over
the old file. This is similar to how some qmail file modification
is done.

No read locks are requested for read only i/o.

Write locks are requested for modify i/o.

To reduce the locking load on the file system, a lock is
not requested for the .dir-control file. If we miss counting
a user during a simulatious user addition, it's not the
end of the world. The number of user entry in that file
is not meant to be exact. It is more of a guide line on
how to spread out user directories across the vpopmail
3 level user directory tree.

This should reduce the over all file i/o synchronicity
requirements. And hence reduce the possiblity of lost
file data (like loosing a complete vpasswd user file!!!)

At least we are using the more reliable rename(2) function.

VPOPMAIL'S "IP ALIAS" DOMAINS
-----------------------------

When performing an auth in vpopmail, you would generally use the full email
address as the username

If many of your users are from a single domain, then you can optionally put
that domain into the ~vpopmail/etc/defaultdomain file. Then if a user doesnt
include a domain when they auth, the auth will be automatically performed
against the domain nominated in the defaultdomain file.

This system works well as most mail servers only need to have one domain
nominated as a default. However what would happen if you later inherit
another large domain full of users who have their email clients setup
to login with just a username only? A vpopmail server can have only one
default domain. It is going to be a lot of work to have to go to each email
client and change it over to login with full email address.

vpopmail provides a solution for this scenario : IP Alias Domains.

To use IP Alias Domains, you need to bind some more IP addresses to your
mail server. Then use the vipmap program to associate a particular domain
to a particular IP address.

Then when the auth request arrives, if it does not contain a domain,
vpopmail will attach the matching domain from the IP alias table.

---
Contributed by Michael Bowe 7th Dec 2003

--------------------------------------------------------------------------

Using vpopmail with LDAP is not very common.
The LDAP modules are functional, but because it not as popular as using
CDB or MySQL auth systems, you should be wary of implementing the LDAP
system on a production server.

--------------------------------------------------------------------------

So far this file is just a collection of everything that has ever been
written about ldap.  It would be nice for someone who is actually using
it, or even better someone who has to figure it out for the first time,
to go through this file and clean it up.  If you do, please send a copy
to the vpopmail-devel@lists.sourceforge.net so it can be included in
the next release...

--------------------------------------------------------------------------

README file from ldap patch [1609348]



OS: FreeBSD devhost.kingdom.lan 6.0-RELEASE FreeBSD 6.0-RELEASE #0: Fri Nov 24 14:49:25 EET 2006
    life@devhost.kingdom.lan:/usr/src/sys/i386/compile/DEVHOST  i386

##########

gcc:	Using built-in specs.
	Configured with: FreeBSD/i386 system compiler
	Thread model: posix
	gcc version 3.4.4 [FreeBSD] 20050518

##########

LDAP: openldap-2.3.20

##########

OpenLdap Built:
    LD_LIBRARY_PATH="/usr/local/lib:/usr/local/lib/sasl2:/usr/local/BerkeleyDB.4.3/lib"
    LDFLAGS="-L/usr/local/lib -L/usr/local/lib/sasl2 -L/usr/local/BerkeleyDB.4.3/lib \
             -R/usr/local/lib -R/usr/local/lib/sasl2 -R/usr/local/BerkeleyDB.4.3/lib" \
    CPPFLAGS="-I/usr/local/include -I/usr/local/BerkeleyDB.4.3/include"
 ./configure --prefix=/usr/local/ldap --enable-syslog --enable-local \
 --with-threads --with-tls --with-multiple-precision --with-kerberos \
 --enable-slapd=yes --enable-slurpd=yes --enable-cleartext=no --enable-crypt=yes \
 --enable-lmpasswd=yes --enable-spasswd=yes --enable-rewrite=yes --enable-rlookups=yes \
 --enable-wrappers=yes --enable-dnssrv=yes --enable-modules=yes \
 --enable-ldap=yes --enable-ldbm=yes --enable-meta=yes --enable-monitor=yes \
 --enable-null=yes --enable-passwd=yes --enable-perl=yes --enable-relay=yes \
 --enable-shell=no --enable-sql=no --enable-overlays=yes --enable-dynamic=yes \
 --with-dyngroup=yes --with-proxycache=yes \
 --with-cyrus-sasl=yes --enable-spasswd=yes \
 --enable-bdb=yes --enable-hdb=yes &&
  make depend &&
  make &&
  make install &&

##########

vpopmail-5.4.17

##########

1. configure and configure.in
    "-lresolv" is not used, thus replaced.
    path to lib has been changed to "-L/usr/local/ldap/lib"
    path to includes has been changed to "-I/usr/local/ldap/include"


2. qmailUser.schema
    the "qmailUser" objectClas is derived from "person" objectClass
    so there MUST be both "cn" and "sn" objectClass'es.


3. vauth.h
    two struct members have been added to "struct vqpasswd"
    for "cn" and "sn" objectClass'es
	char *pw_cn;                  /* LDAP's "cn" demanded by "objectClass: qmailUser" */
	char *pw_sn;                  /* LDAP's "sn" demanded by "objectClass: qmailUser" */


4. vldap.h
    two objectClass'es have been added to char *vldap_attrs[]
    "cn",               /* LDAP's "cn" demanded by "objectClass: qmailUser" */
    "sn",               /* LDAP's "cn" demanded by "objectClass: qmailUser" */


5. vldap.c
    NUM_LDAP_FIELDS constant has been given new values
    char *ldap_fields[] has been added objectClass'es "cn" and "sn"
	"cn",	/* 7 LDAP's "cn" demanded by "objectClass: qmailUser" */
	"sn",	/* 8 LDAP's "cn" demanded by "objectClass: qmailUser" */

    "cn" and "sn" objectClass'es have been added to char *ldap_fields[]
	"cn",	/* 7 LDAP's "cn" demanded by "objectClass: qmailUser"           */
	"sn",	/* 8 LDAP's "cn" demanded by "objectClass: qmailUser"           */

    in function vauth_getpw() according to the above mentioned changes:
	vals = ldap_get_values(ld, msg, "cn");
	    ...
	vals = ldap_get_values(ld, msg, "sn");
	    ...
    have been added

    in function vauth_adduser() "cn" and "sn" values are processed
        snprintf(common_name, sizeof(common_name), "%s@%s", user, domain);
        lm[7]->mod_values[0] = safe_strdup(common_name); for "cn"
        lm[8]->mod_values[0] = safe_strdup(gecos); for "sn"


    in function vauth_setpw() the same "cn" and "sn" values are processed
	lm[7]->mod_values[0] = safe_strdup(inpw->pw_cn);            /* coonardoo@gmail.com */
	lm[8]->mod_values[0] = safe_strdup(inpw->pw_sn);            /* coonardoo@gmail.com */


    comments have been added for funtion safe_free() as for the warning:
    "dereferencing type-punned pointer will break strict-aliasing rules"
    that pops up during compilation. this warning doen't occur with gcc-2.91.* && gcc-4.0.2


a shortened variant of slapd configuration of mine is given in the subdirectory ldap here.

###
#EOF
###



--------------------------------------------------------------------------

2006/Jun/30 : Pavel Vinogradov <blaze.cs@gmail.com>

    Now LDAP connection info is stored in ~vpopmail/etc/vpopmail.ldap.
The format of the file is as follows:

   ldap server|ldap port|ldap user|ldap password|ldap basedn

Comments (lines starting with '#') are allowed.
Port should be the actual port.

For example:

# This is the LDAP configuration file for vpopmail.
localhost|389|cn=vpopmailuser, o=vpopmail|vpoppasswd|o=vpopmail


2003/Dec/29 : Michael Bowe <mbowe@pipeline.com.au>

A QUICK GUIDE TO VPOPMAIL WITH LDAP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Latest version of this guide is available from
http://www.bowe.id.au/michael/isp/vpopmail-ldap.htm

Note that I am not an LDAP expert, so some of the terminology used within
this guide may not be 100% correct. I wrote this guide because many people
on the vchkpw mailing list had questions about how to get vpopmail/ldap
running. The docs we had so far (below) were a little difficult to understand
and follow for an LDAP beginner, so I decided to put together this doc
in the hope of presenting an easy-to-follow installation guide.



OpenLDAP can operate with a number of database filesystems. For this example
we are going to use the bdb database system.

Download/compile BDB

  cd /usr/local/src
  wget http://www.sleepycat.com/update/snapshot/db-4.2.52.tar.gz
  tar xzf db-4.2.52.tar.gz
  cd db-4.2.52
  cd build_unix
  ../dist/configure
  make
  make install
  cd ..

Download/compile OpenLDAP

  http://www.openldap.org/software/download/
  wget http://www.planetmirror.com/pub/openldap/openldap-release/openldap-2.1.23.tgz
  tar xzf openldap-2.1.23.tgz
  cd openldap-2.1.23

  env CPPFLAGS=-I/usr/local/BerkeleyDB.4.2/include \
    LDFLAGS=-L/usr/local/BerkeleyDB.4.2/lib \
    ./configure

  make depend
  make
  make install
  cd..

Download/configure/compile vpopmail

  Make the user accounts

    # If you are using RH8.0, you will probably need to run this following command,
    # because RH8.0 comes preconfigured with UID/GID 89 allocated to postfix
    #
    # userdel postfix

    groupadd -g 89 vchkpw
    useradd -g vchkpw -u 89 vpopmail

    # We recommend you use the user and group id's of 89. The FreeBSD folks
    # have reserved 89 for the group and 89 for the user for vpopmail.  Feel
    # free to have the OS assign the group/user id (for example, Solaris won't
    # allow gid 89).

  Download and unpack the source

    cd /usr/local/src
    wget http://telia.dl.sourceforge.net/sourceforge/vpopmail/vpopmail-5.4.4.tar.gz
    tar xzf vpopmail-5.4.4.tar.gz
    chown -R root.root vpopmail-5.4.4
    cd vpopmail-5.4.4

  Setup the LDAP support in the vpopmail sources

    echo "localhost|389|cn=vpopmailuser, o=vpopmail|vpoppasswd|o=vpopmail" > ~vpopmail/etc/vpopmail.ldap
    chown vpopmail.vchkpw ~vpopmail/etc/vpopmail.ldap
    chmod 640 ~vpopmail/etc/vpopmail.ldap

  Compile vpopmail with options like this

    ./configure --enable-auth-module=ldap
    make
    make install-strip

Configure/start the OpenLDAP server

  Copy the vpopmail ldap schema into the OpenLDAP schema directory

    cd ldap
    cp qmailUser.schema /usr/local/etc/openldap/schema

  Configure OpenLDAP to host the vpopmail database

    cp slapd.conf /usr/local/etc/openldap
    chmod 600 /usr/local/etc/openldap/slapd.conf
    chown root.root /usr/local/etc/openldap/slapd.conf

  Start the OpenLDP server

    /usr/local/libexec/slapd

  If all goes well, 'ps axf' should give something like this :

    18415 ?        S      0:00 /usr/local/libexec/slapd
    18416 ?        S      0:00  \_ /usr/local/libexec/slapd
    18417 ?        S      0:00      \_ /usr/local/libexec/slapd

  Now create the vpopmail database in the LDAP system

    ldapadd -f vpopmail.ldif -x -w vpoppasswd -D'cn=vpopmailuser,o=vpopmail'

  If all goes well you will see something like :

    adding new entry "o=vpopmail"

  Get the ldap server to confirm that the vpopmail database exists

    ldapsearch -x -b 'o=vpopmail'

Now you should be right to go!

As you start adding domains and users, the ldap directory tree will eventually look like this :

  vpopmail (o)
    somedomain1.com (ou)
      someuser1
      someuser2
      someuser3
   somedomain2.com (ou)
      someuser1
      someuser2
      someuser3


Other useful references I found on the net :

  http://marc.theaimsgroup.com/?l=vchkpw&m=105781736114278&w=2
  http://www.tiski.de/linux/patches/vpopmail/LDAP-VPOPMAIL.html




**************************************************************************

PREVIOUS VPOPMAIL/LDAP DOCUMENTATION :

See the ldap directory for the
qmailUser.schema and slapd.conf files

!!!!!!!!!!!!!!!!!!!!! IMPORTANT !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Only for 2.07+ (Not only but tested on it)
I used OpenLDAP from SuSe 7.2 version OpenLDAP 2.0.7-Release 21 July 2000 7
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Start:

first install one of ldap sources (rpm is fine :) )
then create base ldif file thats looks like this ( or similar)

second set up ldap (ok these are basic steps not a real ldap setup howto...)
first create slapd.conf (or use default created by instalation)
put into it next lines (on begining of file)
------------------
include     /etc/openldap/schema/qmailUser.schema
schemacheck off
------------------
(file definitions qmailUser.schema could be found at the end of this file)

What that above means?
That is include of qmailUser.schema definiton of qmail (vpopmail) specific
attributes and is needed.
then put these lines for database defitinion
---------------------------------------------
#######################################################################
# ldbm database definitions
#######################################################################

database ldbm
suffix      "o=vpop"
rootdn      "cn=Manager, o=vpop"
rootpw      proba
directory   /var/lib/ldap
index   objectClass             pres,eq
index   cn,sn,uid               eq
index   qmailUID,qmailGID   eq
access to *
        by self write
        by dn="cn=manager,o=vpop" write
        by * write

------------------------------------------------


-------------------------------
# vpop
dn: o=vpop
objectClass: Organization
o: vpop
-------------------------------
name it first.ldif or whatever

then if all step above works  do next:

-------- command to execute ----------
ldapadd -x -w proba -D'cn=manager,o=vpop' < first.ldif
-------- -----------------------------


and that should reply to you something like

adding new entry "o=vpop"


Next thing you should check is does it realy works ;)

check it simply typing command

-----------command --------
ldapsearch -x -b 'o=vpop'
---------------------------
output is shown below (something like propably not same)

---out---
version: 2

#
# filter: (objectclass=*)
# requesting: ALL
#

# vpop
dn: o=vpop
objectClass: Organization
o: vpop

---out---

Ok if all that passed ok ( I'll return to qmailUser.schema later)
you have ldap server up and running (this will not make you ldap guru :)
even I do not know ldap that much to call myself "good ldaper or like" :) )


Next you should compile vpopmail source
you could use next steps for it
edit vldap.h and change next lines to yuore settings( // lines are my
comments you will not find them in vldap.h :) )
--------
#define VLDAP_SERVER "localhost" // change this line to point
                                 // to your ldap server

#define VLDAP_PORT LDAP_PORT // no need to change if you didn't
                             //change anything)

#define VLDAP_USER "cn=Manager, o=vpop" // MUST change to reflect youre
                                        //settings from
#define VLDAP_PASSWORD "proba"  // MUST change to reflect youre
                                // setting from /etc/openldap/slapd.conf

#define VLDAP_BASEDN "ou=%s, o=vpop" // MUST change to reflect youre
                                     // setting from /etc/openldap/slapd.conf
--------
then type
"./configure --enable-auth-module=ldap " and that "should" setup ldap in vpopmail
without hasle :)
"make" "make install" and that should get you to running version of vpopmail
in ~vpopmail/bin dir
try adding new domain with ~vpopmail/bin/vadddomain terere.com dddddasfa
if there is no any stupid error
"Error: Unable to chdir to vpopmail/users directory"

that's it :)
again you can check does it work with
ldapsearch -x -b'o=vpop' if there is terere.com in output


Resources non known except www.openldap.org and www.inter7.com


-------------------qmailUser.schema---------------------------

attributetype ( 1.3.6.1.4.1.8868.3.1.2
        NAME 'qmailGID'
        DESC 'qmail group id'
        EQUALITY caseIgnoreIA5Match
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.26{100}
        SINGLE-VALUE )

attributetype ( 1.3.6.1.4.1.8868.3.1.3
        NAME 'qmailUID'
        DESC 'qmail userid'
        EQUALITY caseIgnoreIA5Match
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.26{100}
        SINGLE-VALUE )

attributetype ( 1.3.6.1.4.1.8868.3.1.4
        NAME 'qmaildomain'
        DESC 'qmail Domain'
        EQUALITY caseIgnoreIA5Match
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.26{100}
        SINGLE-VALUE )
attributetype ( 1.3.6.1.4.1.8868.3.1.6
        NAME 'mailQuota'
        DESC 'qmail quota'
        EQUALITY caseIgnoreIA5Match
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.26{100}
        SINGLE-VALUE )
attributetype ( 1.3.6.1.4.1.8868.3.1.7
        NAME 'mailMessageStore'
        DESC 'qmail Store'
        EQUALITY caseIgnoreIA5Match
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.26{100}
        SINGLE-VALUE )

objectclass ( 1.3.6.1.4.1.8868.3.1
        NAME 'qmailUser'
        DESC 'qmail local mail recipient'
        SUP ( top $ person $ organizationalPerson )
        MAY ( qmailGID $ qmailUID $ qmaildomain $
                mailQuota $ mailMessageStore $ name $ sn $ cn $ userPassword) )


LDAP FAQ


2. After installing vpopmail successfully, running vadddomain gives a core
   dump error. What's wrong?

You probably configured --with-hardquota=xxxxx. This is a known bug. Hopefully
it will be fixed soon =)

3. After installing vpopmail successfully, running vadddomain gives an error:

Error: Unable to chdir to vpopmail/users directory

I don't know :(
From looking at the permissions in /home/vpopmail, everything looks fine.
If you found a solution to this problem, please let me know (and share
with other vpopmailers on the mailing list :)

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
All errors are fixed for ldap module :)
This only works on OpenLDAP 2.0.7-Release     21 July 2000
( I don't use openldap ver 1)

error No. 2 from README.ldap

Fixed ... (snprintf error %s instead %i was in vldap.c on line 463)

error No. 3 from README.ldap

Fixed ... ( everything changed is in vpopmail.patch)

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Explanation:


2 error (stupid typo error :] )
3. error(s) were not that stupid :(
	and need more explaining

Ok here it is ;)

Fist there is a big diference in openldap ver 1 and openldap ver 2

first ther is more strict schema checking
uid attribute cann't be used with this patch
need for PosixAccount objectClass ...

third error was or it is not who knows

  memset((char *)crypted, 0x0, 100);
  if ( password[0] != 0 ) {
    mkpasswd3(password, crypted, 100);
//    crypted[0] = 0;
  } else {
    mkpasswd3(password, crypted, 100);
  }

that check simply do not work I know it should but solution is simple ;)

and I think these are all errors


This was for all folks trying to make it working with openldap  V2


---------- OLD LDAP README ----------------------
From: vol [mailto:vol]On Behalf Of vol@inter7.com
Sent: Wednesday, December 05, 2001 1:15 PM
To: vchkpw@inter7.com
Subject: vpopmail, the LDAP module, and OpenLDAP


Alright.  I've responded to about 15 messages on this list
about the use of the OpenLDAP module.  I'm going to do my best
to explain everything that has ever been asked.  In case you
aren't aware, I'm the author of the LDAP module.  A little background
on the project, we needed to convert a large LDAP solution over
to a vpopmail-based LDAP solution as per the client's request.
I knew nothing of LDAP before I began work on the project, and believe
you me, I had a hell of a time figuring out exactly how LDAP functioned.

First of all, there is absolutely NO RELATIONSHIP between
vpopmail's LDAP module, and qmail-ldap.  qmail-ldap is an
LDAP-enabled qmail-based MTA.  The vpopmail LDAP module reads
user authentication information out of an LDAP database.

Second, the LDAP module DOES work, however, it is not actively
maintained because here at Inter7, we dislike LDAP, and anything
using it with a passion.  LDAP is the most terribly conceived idea
ever to hit the database industry, and to top it off, it is widely
used with bulky commercial mail solutions.  I wish I knew why.
Just to quelch any flaming I might get for my opinions in this area;
I've been over the code, I've worked with the big solutions, and I've
seen many benchmarks.

Here are common problems that will arise when trying to use the vpopmail
LDAP module:



  1) Unable to add new information to the database (domains, users, etc)
     and/or unable to authenticate out of the database

     Various misconfigurations can occur here:
        A) Bad authentication information (see vldap.h)
        B) Bad BASEDN information (see vldap.h)
        C) Mismatched schema (see vldap.h, and your ldap configurations)

     This will be the main problem people run into.  This is a
     misconfiguration on your end.  Not the module.  As far as I know,
     there have been no major re-writes of the OpenLDAP API that would
     cause the base functions to work differently causing database
     information retrieval to fail or act differently.

  2) Things are not properly removed from the database

     This worked in the original code.  Someone reported an error
     where something was not properly removed from the database.
     I have not worked with the LDAP module since early 4.x versions.
     As you know, 5.0 is a big re-write of a lot of the base vpopmail
     code.  I cannot verify if this is a true bug or not.

Instructions for installing the vpopmail LDAP module:

  Okay, folks.  I need to say right up front.  If you don't know
  enough about LDAP to construct a database from scratch without
  reading for hours on end, you're not going to have great success
  with this installation.  If you're not already an LDAP guru,
  please just decide upon another database.  You will be a lot
  happier in the long run.

  First of all, you need to configure your LDAP server.  For our
  purposes, this will be slapd.  You'll need to edit your slapd.conf
  and your slapd.oc.conf (I think its called that still).  Add
  the new schema information.  You can find all this in vldap.c/vldap.h
  source files (or you used to be able to).  Again, if you don't know
  what a 'schema' is, you really shouldnt be mucking with LDAP.  Do
  NOT attempt to modify the structure.  It will BREAK.  Follow the
  schema from vldap.h/vldap.c.

  Modify vldap.h for the authentication information.

  Now, in the old version I worked with, you had to create the basedn
  to start.  If this is no longer needed, ignore this step.  Create
  a little LDIF (you'll probably want to save this in case of problems)
  and pipe it into the database.

  If you followed these instructions, and understood everything you
  were doing more or less, your vpopmail LDAP configuration should be
  working smoothly.

Last words:

  As I said above, the LDAP module has not been verified as extremely
  functional since early 4.x versions.  We'd prefer, if you must use
  backend database, that you go with MySQL.  I'd really suggest you
  look at the benchmarking on the MySQL site.  MySQL cant hold 2
terabytes
  of authentication information, but it's three times faster than
Oracle.
  On the flip side, Oracle CAN hold 2 terabytes of authentication
  information, but unless you're a fortune 500 company, you probably
  will not need to bother with that type of database storage.

  Any further questions about LDAP, we will not be able to help you with
  unless you want to fund some sort of documentation, update project.
  We always welcome funding for any project, of course. :)

I hope this has helped those of you who absolutely cannot live without
LDAP authentication.

Good luck!
--
vol@inter7.com
Inter7 Internet Technologies, Inc.
www.inter7.com - 847-492-0470
Prices at http://www.inter7.com/prices

4/28/2007

* Maildrop Support in vdelivermail

Vdelivermail can call maildrop during local delivery to a Maildir.  To enable
this, simply compile vpopmail with --enable-maildrop=y.  Configure will
look for the maildrop program in /usr/bin and /usr/local/bin.  If it is not
found, you will need to specify the location with the additional
--enable-maildrop-prog='/path/to/maildrop' option.

If you want to disable maildrop processing for a user or all users in a domain,
you may do so with the vmoduser program:

vmoduser -m user@domain.com
or
vmoduser -m domain.com

When compiled with maildrop support, maildrop processing defaults to on for
users.  If you want to override this default on a system or per domain basis,
these can be set as well with the following entries to vlimits.default, or
.qmailadmin-limits, respectively:

disable_maildrop

maildrop is called with no arguments, allowing for the default maildroprc
location (/etc/maildroprc on Linux, /usr/local/etc/maildroprc on FreeBSD).
You can find two sample maildroprc files in the maildrop subdirectory.  The
file maildroprc.v1 is for maildrop versions below 2.0, and maildroprc.v2 is
for maildrop versions 2.0 or higher.  (Some expression syntax change at 2.0).

If you want to automatically run spamc before calling maildrop, see
README.spamassassin


Bill Shupp
hostmaster@shupp.org

--------------------------------------------------------------------------

Using vpopmail with MySQL is becoming increasingly popular.
The code is well tested and can be considered to be just
as stable as the default CDB authentication system.

--------------------------------------------------------------------------

2003/Dec/29 : Michael Bowe <mbowe@pipeline.com.au>
(Document originally contributed on this date, but has had some
minor tweaks done since that time)


A QUICK GUIDE TO VPOPMAIL WITH MYSQL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Full doc available from :
http://www.bowe.id.au/michael/isp/vpopmail-mysql.htm


MYSQL :

Setup an account for the MySQL server to run under :

	groupadd mysql
	useradd -g mysql mysql

Go to their website and download the latest binaries to /usr/local/src.
In this example I have used the file: mysql-max-3.23.57-pc-linux-i686.tar.gz
(Note, MySQL v4 has recently been released as "stable", however I am yet
to do any testing under this new version. I would recommend that you stay with
v3.23 until the v4 series is more mature)

Unzip / configure the binaries so they get installed to /usr/local/mysql

	cd /usr/local
	tar xzf /usr/local/src/mysql-max-3.23.57-pc-linux-i686.tar.gz
	ln -s mysql-max-3.23.57-pc-linux-i686 mysql

Run the installation script that creates/verifies all the various system-use tables etc

	cd mysql
	scripts/mysql_install_db
	cd ..

Setup permissions on the MySQL dirs

	chown -R root.mysql mysql-max-3.23.57-pc-linux-i686
	chmod -R 640 mysql
	chmod -R u+X,g+X mysql
	chmod -R ug+x mysql/bin
	chmod -R g+w mysql/data
	chmod -R u+x mysql/scripts

Let the MySQL server know what amount of resources it is allowed to use

	# choose an appropriate config file from the samples provided
	cp /usr/local/mysql/support-files/my-medium.cnf /usr/local/mysql/data/my.cnf
	# adjust the permissions on the file so that mysql daemon can read the contents
	chgrp mysql /usr/local/mysql/data/my.cnf

Fire up the server

	cd /usr/local/mysql
	bin/safe_mysqld --user=mysql &

At this point the mysql daemons should be running. A good way to verify this is to use this command :

	ps axf

If all is well, you should be able to see something like this :

	1073 ? S 0:00 /bin/sh ./bin/safe_mysqld --datadir=/usr/local/mysql/data --pid-file=/usr/local/mysql/data/.pid
	1117 ? S 0:00  \_ /usr/local/mysql/bin/mysqld --defaults-extra-file=/usr/local/mysql/data/my.cnf --basedir=/usr/local/m
	1125 ? S 0:00      \_ /usr/local/mysql/bin/mysqld --defaults-extra-file=/usr/local/mysql/data/my.cnf --basedir=/usr/loc
	1126 ? S 0:00          \_ /usr/local/mysql/bin/mysqld --defaults-extra-file=/usr/local/mysql/data/my.cnf --basedir=/usr
	1143 ? S 0:00          \_ /usr/local/mysql/bin/mysqld --defaults-extra-file=/usr/local/mysql/data/my.cnf --basedir=/usr
	1419 ? S 0:00          \_ /usr/local/mysql/bin/mysqld --defaults-extra-file=/usr/local/mysql/data/my.cnf --basedir=/usr
	1449 ? S 0:00          \_ /usr/local/mysql/bin/mysqld --defaults-extra-file=/usr/local/mysql/data/my.cnf --basedir=/usr
	1471 ? S 0:00          \_ /usr/local/mysql/bin/mysqld --defaults-extra-file=/usr/local/mysql/data/my.cnf --basedir=/usr

(If you received errors, look in the file /usr/local/mysql/data/hostname.err for debugging info)

Next setup a password for the MySQL root user

	/usr/local/mysql/bin/mysqladmin -u root password 'mysql-root-pwd'

Configure MySQL so it is running all the time from bootup onwards

	cp /usr/local/mysql/support-files/mysql.server /etc/rc.d/init.d/mysql
	chmod 744 /etc/rc.d/init.d/mysql
	chkconfig --add mysql

Then I like to use the ntsysv program to double-check that mysql is set to launch at boot time


VPOPMAIL

Make the user accounts

	# If you are using RH8.0, you will probably need to run this following command,
	# because RH8.0 comes preconfigured with UID/GID 89 allocated to postfix
	#
	# userdel postfix

	groupadd -g 89 vchkpw
	useradd -g vchkpw -u 89 vpopmail

	# We recommend you use the user and group id's of 89. The FreeBSD folks
	# have reserved 89 for the group and 89 for the user for vpopmail.  Feel
	# free to have the OS assign the group/user id (for example, Solaris won't
	# allow gid 89).

Download and unpack the source

	cd /usr/local/src
	wget http://telia.dl.sourceforge.net/sourceforge/vpopmail/vpopmail-5.4.7.tar.gz
	tar xzf vpopmail-5.4.7.tar.gz
	chown -R root.root vpopmail-5.4.7
	cd vpopmail-5.4.7

Setup the MySQL support in the vpopmail sources

	# Create the configuration file that vpopmail will use
	# to setup the connection to the mysql database
	#
	# This example will tell vpopmail :
	#   * Log into the server running on localhost
	#   * Use the default mysql port
	#       (In fact if the server is localhost, and you don't specify a port number, then
	#        I believe the that communications are done via unix sockets rather than TCP/IP)
	#   * Login with username vpopmailuser
	#   * Login with password vpoppasswd
	#   * Use the database called vpopmail
	#

	echo "localhost|0|vpopmailuser|vpoppasswd|vpopmail" > ~vpopmail/etc/vpopmail.mysql
	chown vpopmail.vchkpw ~vpopmail/etc/vpopmail.mysql
	chmod 640 ~vpopmail/etc/vpopmail.mysql

	# log into MySQL as the MySQL root user
	# and then create the database for vpopmail to use
	# and then setup the appropriate permissions on this database
	/usr/local/mysql/bin/mysql --password="mysql-root-pwd"

		CREATE DATABASE vpopmail;
		GRANT select,insert,update,delete,create,drop ON vpopmail.*
		TO vpopmailuser@localhost IDENTIFIED BY 'vpoppasswd';
		quit

Now, build the program with options something like this :

	./configure \
	  --disable-roaming-users \
	  --enable-logging=p \
	  --disable-passwd \
	  --enable-clear-passwd \
	  --disable-domain-quotas \
	  --enable-auth-module=mysql \
	  --enable-auth-logging \
	  --enable-sql-logging \
	  --enable-valias \
	  --disable-mysql-limits

	make
	make install-strip

Notes :
	I used to recommend the --disable-many-domains switch - which
	tells vpopmail to create one MySQL table per email domain. When
	I first started building vpopmail servers, I found this to be the
	most logical way, having each domain in its own table. However there
	has been some discussion about this config option on the vpopmail
	mailing lists, and it sound like this option may be removed at some
	point in the future.  If you have a lot of domains on your server,
	having each domain in its own table can hurt performance. I now agree
	that --enable-many-domains is probably the better choice

Review the contents of the file is used to set the default limits for any
domains / mailboxes in the vpopmail system. Make sure it contains reasonable
defaults for your system.

	vi ~vpopmail/etc/vlimits.default

Optionally, nominate a "default domain". Users in this domain can login to
POP3 etc using just their username. Users from all other domains need to use
their full email address as their login name.

	echo "yourdomain.com" > /home/vpopmail/etc/defaultdomain


--------------------------------------------------------------------------

A HANDY TRICK :

----- Original Message -----
From: "Ken Jones" <kbo@inter7.com>
To: <vchkpw@inter7.com>
Sent: Thursday, September 09, 2004 3:48 AM
Subject: Re: [vchkpw] vpopmail + billing server integration
> On Wednesday 08 September 2004 12:25 pm, Chris Ess wrote:
> > On Wed, 8 Sep 2004, Ken Jones wrote:
> > > Hi,
> > >
> > > Here is something we built into vpopmail for sites like yours.
> > >
> > > Use mysql on the email server. Have the billing system
> > > insert an entry in the vpopmail table, leaving the directory
> > > field blank. vpopmail will automatically create the users
> > > directory and update the database when any program
> > > tries to deliver mail to the user, or authenticate as the user.
> >
> > That's really neat!  I didn't realize you could do this.  (Now someone
> > will tell me that it's in the documentation that I seem to've not read
> > recently.)
>
> It is probably in the mailing list archives. I'm not sure if anyone has
> updated the documentation.
>
> >
> > (I know this is getting offtopic...) So I could use an INSERT statement in
> > SQL instead of vadduser?  Or am I not understanding this correctly?
>
> That is the idea. A while back some folks wanted to hook up their billing
> systems to vpopmail. Basicly they would insert into the vpopmail sql table.
> The only thing they couldn't do easily was create the hashed directory path.
> So we put in vpopmail code to check if the path is blank and automatically
> create the new path and update the database.
>
> You will also need to set the encrypted password using mysql's CRYPT function.
> Mysql's standard encryption functions are not compatible with unix/linux.
>
> Ken
>


----- Original Message -----
From: "Michael Bowe" <mbowe@pipeline.com.au>
To: <vchkpw@inter7.com>
Sent: Thursday, September 09, 2004 7:32 AM
Subject: Re: [vchkpw] vpopmail + billing server integration
>
> ----- Original Message -----
> From: "Chris Ess" <inter7@cae.tokimi.net>
>
> > On Wed, 8 Sep 2004, Ken Jones wrote:
>
> > > Use mysql on the email server. Have the billing system
> > > insert an entry in the vpopmail table, leaving the directory
> > > field blank. vpopmail will automatically create the users
> > > directory and update the database when any program
> > > tries to deliver mail to the user, or authenticate as the user.
> >
> > That's really neat!  I didn't realize you could do this.  (Now someone
> > will tell me that it's in the documentation that I seem to've not read
> > recently.)
> >
> > (I know this is getting offtopic...) So I could use an INSERT statement in
> > SQL instead of vadduser?  Or am I not understanding this correctly?
>
> Yes that feature has been around for a while
>
> It has definitely been discussed in the archives of this list, but I would
> agree that I don't remember seeing it mentioned in the docs.
>
> I use this feature to allow an IIS webserver to create mailboxes on my
> vpopmail server. This is achieved by using an ASP script that creates an
> appropriate record and inserts it into the vpopmail MySQL. Of course the
> same sort of thing could be achieved using Apache/PHP.
>
> I have some more information and some example code here :
> http://www.pipeline.com.au/staff/mbowe/isp/webmail-server.htm#Example_scripts
>
> ps. one catch with inserting users directly... The mailbox on the disk isnt
> created until the 1st POP/IMAP login is done, or the 1st mailbox message is
> received. This can cause a glitch with qmailadmin, because if the user tries
> to login to qmailadmin before their mailbox on the disk exists, qmailadmin
> will barf because it cant write a lockfile to the user's dir. So when I
> insert users directly, the same script also sends the user a "welcome"
> message to ensure that the mailbox is created immediately.
>
> Michael.


--------------------------------------------------------------------------

PREVIOUS VPOPMAIL / MYSQL DOCUMENTATION... :

vpopmail now supports mysql. Here is a brief outline on how to
get it running.

NOTE: make sure you are running the latest stable release of mysql.
If you have 3.22 installed, you will need to upgrade. The dir_control
table in vpopmail uses a "unique index (domain)" syntax which isn't
supported in the 3.22 releases. Thanks to Chris Scheller for
tracking this down.

There are some things you need to edit by hand to get it to work.

1) Create a ~vpopmail/etc/vpopmail.mysql file and put these fields in
the file (replacing them with the actual information):

read_server|read port or socket path|read_user|read_password|database_name
update_server|update port or socket path|update_user|update_password|database_name

For example:

# This is the MySQL configuration file for vpopmail.
localhost|0|readonly|somepass|vpopmail
localhost|0|root|secret|vpopmail

You can make changes to this file at any time without needing to
recompile vpopmail.

If you are NOT using mysql replication then set both of
these sets to be your primary mysql server information.

If you ARE using mysql replication then set the UPDATE
set to be your master mysql server and set the READ
set to be your local mysql server.

After changing the file, make sure it has the correct permissions:

chown vpopmail.vchkpw vpopmail.mysql
chmod 0640 vpopmail.mysql

2) configure options for mysql support.

--enable-auth-module=mysql

First thing. This turns on mysql code and authentication module.

Now if you aren't lucky and your mysql include and libraries aren't
in the "default" locations, you will need to use these options.

If your include files are not in /usr/include/mysql or
/usr/local/include/mysql, add the following configuration option:

--enable-incdir=/path-to-your-include-dir

If your library files are not in /usr/lib/mysql or in
/usr/local/lib/myqsl , add the following configuration option:

--enable-libdir=/path-to-your-lib-dir

On my machine I do:
$ ./configure --enable-auth-module=mysql

3) make the software

$ make

4) install as root

$ su
# make install-strip


## CONVERSION FROM CDB TO MYSQL: ##

If you have domains that are already setup as cdb modules and
you want to convert them to sql:

1) Convert your current virtual domains to sql.

use the vconvert program. You can convert one domain at a time,
or convert them all.

# ./vconvert -c -m
this will convert them all from the vpasswd.cdb format to the default
single table database

# ./vconvert -c -m virtualdomain1 virtualdomain2 ...
will convert the list of virtual domains from vpasswd.cdb layout to
single table database

What does the conversion program do? First it creates a table with the name
of the domain. domain names with "-" or "." are converted to "_". Mysql
doesn't like "-" or "." in table names.  For example: test-dom.com domain
gets a table named test_dom_com

Next, the conversion program reads the contents of the vpasswd file and
adds those records to the mysql database.


## OPTIONAL TABLE CUSTOMISATION: ##

1) Customizing the fields in the sql tables.

It is possible to add additional fields to the database table layout.
vpopmail won't touch these additional fields, but they would be available
for any other programs to access and use.

Edit vmysql.h and add fields to either SMALL_TABLE_LAYOUT or LARGE_TABLE_LAYOUT
be sure not to delete any of the fields. Each field in the default layout
is required for vpopmail.

If --enable-onchange-script is added to the ./configure command
many vpopmail commands, and calls into the library will call the
script ~vpopmail/etc/onchange.  Commands that add or update call
the script after making their changes.  Commands that delete
something call the script before doing the delete.

When a command calls other commands in the process of doing its job
only the inital call triggers the script.  For example vadddomain uses
vadduser and vmoduser to create the postmaster user, and set its
attributes.  Your script will be called once with cmd set to
add_domain, and arg1 set to the domain being added.  By the time the
script is called, the domain and the postmaster user have already
been created.

When the script is called, it will be passed the following values
on the command line to indicate what was changed.  Your script should
check the cmd value to determine what has happened and act accordingly.


function called         cmd               arg1            arg2
----------------------  ------------      -----------     ----------

vadddomain()            add_domain        domain
vdeldomain()            del_domain        domain
vadduser()              add_user          user@domain
vdeluser()              del_user          user@domain
vaddaliasdomain()       add_alias_domain  domain          real_domain
vauth_setpw             mod_user          user@domain
valias_insert           insert_alias      user@domain     alias_line
valias_remove           remove_alias      user@domain     alias_line
valias_delete           del_alias         user@domain
valias_delete_domain()  del_all_alias     domain



The program, daemon command or function call that triggered the onchange
script will not return until the script ends.  That means that you should
keep the run time of the script down, or have the script trigger any
long running process.

This is based on the onchange patch by John Simpson, used to support
his validrcptto.cdb patch.  Robin Bowes made the suggestion to return
information on what was done.

http://qmail.jms1.net/vpopmail



List of code changes to implement onchange, and what is sent to the script:

file	function		cmd		arg1		arg2
-----	---------		----		-----		-----
vcdb.c
	vauth_setpw()		mod_user	user@domain

vldap.c
	vauth_setpw()		mod_user	user@domain

vmysql.c
	vauth_setpw()		mod_user	user@domain
	valias_insert()		insert_alias	user@domain	alias_line
	valias_remove()		remove_alias	user@domain	alias_line
	valias_delete()		del_alias	user@domain
	valias_delete_domain()	del_all_alias	domain

vpalias.c
	valias_insert()		insert_alias	user@domain	alias_line
	valias_delete()		del_alias	user@domain

vpgsql.c
	vauth_setpw()		mod_user	user@domain
	valias_insert()		insert_alias	user@domain	alias_line
	valias_delete()		del_alias	user@domain	alias_line
	valias_delete_domain()	del_all_alias	domain

vsybase.c
	vauth_setpw_size()	mod_user	user@domain

vpopmail.c
	vadddomain()		add_domain	domain
	vdeldomain()		del_domain	domain
	vadduser()		add_user	user@domain
	vdeluser()		del_user	user@domain
	vaddaliasdomain()	add_alias_domain domain		real_domain

--------------------------------------------------------------------------

Using vpopmail with Oracle is very rare.

The Oracle modules are understood to be functional, but because it not
as popular as using CDB or MySQL auth systems, you should be very wary
of implementing the Oracle system on a production server.

--------------------------------------------------------------------------

Edit voracle.h and set the service, user and password information.

Then run: proc voracle.pc

proc or Pro-C is oracle's precompiler.
See your oracle documetation for more
information.

You might also need to create the tables by hand

relay table

/*
   $Id: README.pgsql,v 1.15 2007-05-22 03:58:58 rwidmer Exp $
*/
--------------------------------------------------------------------------

Using vpopmail with PostgreSQL is not very common.
The PostgreSQL modules are understood to be functional, but because it not
as popular as using CDB or MySQL auth systems, you should be wary of
implementing the PostgreSQL system on a production server.

The PostgreSQL backend has improved greatly as of vpopmail 5.4.8, and many
have been using it on production servers.

--------------------------------------------------------------------------

If you are upgrading an existing PostgreSQL installation (that is using
valiases) to version 5.4.8 or later for the first time, please run the
following script to convert the columns from char to varchar:

BEGIN;
ALTER TABLE valias RENAME alias TO alias2;
ALTER TABLE valias RENAME domain TO domain2;
ALTER TABLE valias RENAME valias_line TO valias_line2;
ALTER TABLE valias ADD alias varchar(32);
ALTER TABLE valias ADD domain varchar(64);
ALTER TABLE valias ADD valias_line varchar(160);
UPDATE valias SET alias=trim(alias2), domain=trim(domain2),
valias_line=trim(valias_line2);
ALTER TABLE valias ALTER alias SET NOT NULL;
ALTER TABLE valias ALTER domain SET NOT NULL;
ALTER TABLE valias ALTER valias_line SET NOT NULL;
ALTER TABLE valias DROP alias2;
ALTER TABLE valias DROP domain2;
ALTER TABLE valias DROP valias_line2;
COMMIT;
VACUUM ANALYZE valias;

(Thanks to Sven Willenberger for the previous script.)

------------------------------------------------------------------------------
2003/Dec/29 : Michael Bowe <mbowe@pipeline.com.au>

A QUICK GUIDE TO VPOPMAIL WITH POSTGRESQL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Full doc available from :
http://www.bowe.id.au/michael/isp/vpopmail-postgresql.htm

Note :
  You should not permit end-users to have shell access to this server.
  PostgreSQL by default allows any local user to access any database on
  the server. You can certainly tighten the security of the default
  PostgreSQL installation, but it is pretty much futile considering that
  vpopmail stores the PostgresSQL login/pass in the "libvpopmail.a" file.
  It is straightforward for any knowledgeable local user to be able to
  extract the user/pass from this file


PostgreSQL:

Setup an account for the PostgreSQL server to run under :

	useradd postgres

Download and unpack the source

	cd /usr/local/src
	wget ftp://ftp.au.postgresql.org/pub/postgresql/v7.3.4/postgresql-7.3.4.tar.gz
	tar xzf postgresql-7.3.4.tar.gz
	chown -r root.root postgresql-7.3.4
	cd postgresql-7.3.4

Compile source (installs to /usr/local/pgsql)

	./configure
	gmake
	gmake install

Create the data directory

	mkdir /usr/local/pgsql/data
	chown postgres /usr/local/pgsql/data

Run the installation script that creates/verifies all the various
system-use tables etc

	su postgres
	/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data

Fire up the server

	/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data > /usr/local/pgsql/data/serverlog 2>&1 &

At this point the PostgreSQL daemons should be running. A good way
to verify this is to use this command :

	ps axf

If all is well, you should be able to see something like this :

	388 pts/1 S 0:00 /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
	389 pts/1 S 0:00   \_ postgres: stats buffer process
	391 pts/1 S 0:00       \_ postgres: stats collector process

(If you received errors, look in the file /usr/local/pgsql/data/serverlog
for debugging info)

Configure PostgreSQL so it is running all the time from bootup onwards

	# exit back to the root user from the postgres su
	exit
	cp /usr/local/src/postgresql-7.3.4/contrib/start-scripts/linux /etc/rc.d/init.d/postgres
	chmod 744 /etc/rc.d/init.d/postgres
	chkconfig --add postgres

vpopmail:

Make the user accounts

	# If you are using RH8.0, you will probably need to run this following command,
	# because RH8.0 comes preconfigured with UID/GID 89 allocated to postfix
	#
	# userdel postfix

	groupadd -g 89 vchkpw
	useradd -g vchkpw -u 89 vpopmail

	# We recommend you use the user and group id's of 89. The FreeBSD folks
	# have reserved 89 for the group and 89 for the user for vpopmail.  Feel
	# free to have the OS assign the group/user id (for example, Solaris won't
	# allow gid 89).

Download and unpack the source

	cd /usr/local/src
	wget http://telia.dl.sourceforge.net/sourceforge/vpopmail/vpopmail-5.4.4.tar.gz
	tar xzf vpopmail-5.4.4.tar.gz
	chown -R root.root vpopmail-5.4.4
	cd vpopmail-5.4.4

Create the a vpopmail database in PostgreSQL

	/usr/local/pgsql/bin/createdb --username=postgres --owner=postgres vpopmail

Now, build the program with a configure something like this :

	./configure \
	  --disable-roaming-users \
	  --enable-logging=p \
	  --disable-ip-alias-domains \
	  --disable-passwd \
	  --enable-clear-passwd \
	  --disable-domain-quotas \
	  --enable-auth-module=pgsql \
	  --disable-many-domains \
	  --enable-auth-logging \
	  --enable-sql-logging \
	  --enable-valias

	make
	make install-strip

------------------------------------------------------------------------------
PREVIOUS VPOPMAIL / PGSQL DOCUMENTATION :

2002/02/22 : N.Fung <nfung@classY.jp>

Notes on translating vmysql.c to vpgsql.c
* strings in SQL statements are enclosed with ' and not ".
* there is no "replace into" in pgsql.
* 'user' is a reserved column name! Changed 'user' to 'userid'.

To get it going become DBA of PostgreSQL server. Then:

1. /path/to/pgsql/bin/createuser vpopmail

   (no need to grant vpopmail dba rights)

2. /path/to/pgsql/bin/createdb vpopmail

If you want to change "vpopmail", make sure you edit vpgsql.h and compile.

---ends---

   Please see README.vdelivermail

VPOPMAIL AND MAILDIRQUOTAS                               (updated 16/Jan/2004)

* OVERVIEW

    As of version 5.1.1, vpopmail's quota system was changed to support the
    Maildir++ specification used by the Courier Mail Server and its standalone
    components (SqWebmail, Courier-IMAP, maildrop).  The Maildir++
    specification accounts for mail not only in the user's Maildir/new and
    Maildir/cur directories, but in maildirfolders as well.  This is good news
    for people who use vpopmail along with any of the agents mentioned above,
    as ALL messages should be accounted for.

    See http://inter7.com/courierimap/README.maildirquota.html for details on
    the Maildir++ specification, maildirquotas, and maildirfolders.

    This was accomplished by integrating a lot of functions from vdeliverquota,
    a tool shipped with courier-imap (among others) to allow non-Maildir++
    delivery agents to utilize maildirquotas.

* BACKWARDS COMPATIBLE

   The new system is completely backwards compatible with your existing quota
   settings.  The main difference you will see is that current usage
   information is now stored in Maildir/maildirsize rather than
   Maildir/.current_size.

* CONFIGURATION

    QUOTAS

    Quota settings are still stored in vpopmail's authentication module. Just
    set them as you have in the past with vmoduser -q or vsetuserquota.  But two
    different formats are now supported:

    Old vpopmail style: 1000000 or 1MB or 1000KB
    (1MB quota)

    maildirquota style: 1000000S or 1000000S,1000C
    (1MB quota, or 1MB Quota / 1000 Message Count limit, whichever comes first)

    While both styles will work with 5.1.1 and above, the maildirquota
    style will ONLY work with 5.1.1 and above.  If you should downgrade your
    vpopmail installation to a version below 5.1.1, you'll need to make sure
    your quota settings are in the Old vpopmail style.

    QUOTA WARN MESSAGES

    You can have a quota warning delivered to a user when their message is
    delivered successfully, but they are now over 90 percent utilisation.  Just
    edit quotawarn.msg and copy it to ~vpopmail/domains/.quotawarn.msg.  When
    90 percent utilisation or more is reached, this message is copied verbatim
    to their mailbox.

    To change the percentage to something other than 90, edit
    QUOTA_WARN_PERCENT in vdelivermail.c and recompile.

* DOMAIN QUOTAS

    ** NOTE: Domain quotas are currently broken.  Do not use them. **

    If you want to implement a quota for a whole domain, you have 2 options.
    You can either put the domain under a unique system id and implement
    system quotas, or (as of 5.3.18) you can use a non-system domain quota.  To
    implement the former, just use 'vadddomain -u <system user> <domain>' and
    set the system quota for that user.  To implement the latter, you must first
    compile vpopmail with "--enable-domainquotas=y".  Then, you can add this to
    your .qmailadmin-limits file

        quota 50
	maxmsgcount 1000

    This would set a total domain quota of 50MB , and a maximum
    message count of 1000 messages for the entire domain.  Modification of
    domain quotas should be done with the vmoddomlimits program.

    NOTE: Non-system domain quotas are only enforcable when vdelivermail is the
    local delivery agent.  If you pipe your mail into anything else, like
    maildrop, then the non-system domain quota will be ignored.  An alternative
    would be to install the domain under a unique system user (vadddomain -u)
    and set system quotas on that account.

* CAVEATS

    MAILDROP

    If you use maildrop for filtering, compile it with maildirquota support
    if you want to use it with vpopmail 5.1.1 and above with quotas.

    POP SERVERS

    qmail-pop3d does not update maildirsize when you delete messages.
    Furthermore, when using aliases via .qmail files, qmail-local does not
    know about Maildir++, so messages delivered directly by qmail-local do not
    get added to the maildirsize file either.  These problem should correct
    themselves within 15 minutes according to the Maildir++ specification, but
    this does not appear to be that reliable yet.

    The best available solution is to patch qmail with qmail-maildir++.patch,
    included in the contrib directory of the vpopmail source.  It will add
    Maildir++ support to both qmail-pop3d and qmail-local.

* CREDITS

    deliverquota was written by Sam Varshavchik <mrsam@courier-mta.com>
    deliverquota -> vpopmail integration by Bill Shupp <hostmaster@shupp.org>

If you are considering roaming users, you should seriously consider smtp-auth.
Linux users can follow Bill Shupp's toaster, and I believe Matt Simerson's toaster
supports smtp-auth for BSD.

Rick Widmer  20070502


========================================================================================

November 2003 : Michael Bowe <mbowe@pipeline.com.au>

VPOPMAIL ROAMING USERS
~~~~~~~~~~~~~~~~~~~~~~
Latest version available from :
http://www.bowe.id.au/michael/isp/webmail-server.htm


With qmail, the typical way to control mail relaying is to put a list of
rules into a file called tcp.smtp. The tcprules program is then used to
compile this file into cdb database format with the output being stored
in a file called tcp.smtp.cdb. The tcpserver program is configured (using
the -x parameter) to read this file and thus know which SMTP clients are
permitted to relay mail.

This type of configuration works well if there is a known range of IP
addresses that are permitted to relay mail. eg the IP's on the qmail
server's local LAN. However if the qmail server needs to provide outbound
SMTP services for clients who may be connecting from any IP, you are going
to run into problems. What is needed is some way to automate the process
of granting users the ability to relay mail, without opening up access
to all and sundry on the Internet.

vpopmail includes a solution for this problem. The solution is known as
"roaming users" and is typically implemented with a technique known as
"POP-before-SMTP". Once a client has successfully authenticated via POP3,
vpopmail will add the client's IP to a list. vpopmail then merges this
list with the contents of the tcp.smtp file and runs the tcprules
program to compile a new version of the tcp.smtp.cdb file. Thus the client
can now relay mail.

In addition to storing the client's IP address, vpopmail will also store
the time of authentication. The postmaster uses a cronjob on the qmail
server to periodically (eg once per hour) run the clearopensmtp program.
This program scans through the list of roaming clients and removes any
entries that exceed the nominated age (eg 3 hours). This ensures that
the list of IPs does not grow out of bounds, and that the roaming IPs
are closed within a reasonable timeframe after being opened.

configure options for vpopmail that relate to roaming users :

  ./configure \
  --enable-roaming-users \              <- enable roaming users functionality
  --enable-tcprules-prog=path \         <- defaults to /usr/local/bin/tcprules
  --enable-tcpserver-file=path \        <- defaults to /home/vpopmail/etc/tcp.smtp
  --enable-relay-clear-minutes=minutes  <- defaults to 180

Example /var/qmail/supervise/qmail-smtpd/run file for POP-before-SMTP :

  #!/bin/sh
  QMAILDUID=`id -u qmaild`
  NOFILESGID=`id -g qmaild`
  exec /usr/local/bin/softlimit -m 2000000 \
    /usr/local/bin/tcpserver -v -x /home/vpopmail/etc/tcp.smtp.cdb -c 40 -R \
    -u "$QMAILDUID" -g "$NOFILESGID" 0 smtp \
    /usr/local/bin/rblsmtpd -b -C -r list.dsbl.org \
    -t 5 \
    /var/qmail/bin/qmail-smtpd 2>&1


Notes :

qmail servers are typically built with the tcp.smtp files being located in
the /etc directory. This is not usually suitable for vpopmail roaming
users, since the /etc directory will (should) not have write permissions
for the vpopmail user. Therefore it is not going to be possible for vpopmail
to write out updated versions of the tcp.smtp.cdb file. For use with roaming
users, it is recommended that the tcp.smtp files are stored in ~vpopmail/etc

If a user auths, and their IP already exists in the roaming IP list,
the timestamp for the entry is updated, but the tcprules program is not run.
There is no need to rebuild the tcp.smtp.cdb file as the IP address is
already permitted to relay. Rebuilding the file will only waste disk and CPU
time.

If the vpopmail server is using the default cdb authentication backend,
then the list of roaming IPs will be stored in a file called
~vpopmail/etc/open-smtp. If the vpopmail server is using the MySQL backend,
the roaming IPs will be stored in a database table called relay. The SQL
backend will give better performance on a busy server. Either way though,
you should be cautious about enabling roaming user functionality on a very
busy server, as a large amount of disk and CPU will be used with the continual
rebuilding of the tcp.smtp.cdb file. If the server is busy enough you could
run into nasty file locking issues which will cause vpopmail password
authentication to intermittently fail. If you absolutely must have
POP-before-SMTP functionality on your busy server, then there are only two
possible solutions that I can think of  : 1) you could try putting the
tcp.smtp files onto a RAM disk, or 2) use vpopmail's MySQL auth backend
plus use Matt Simerson's tcpserver patch that allows all of the tcp.smtp
files to be stored in MySQL
http://matt.simerson.net/computing/mail/qmail/ucspi-tcp-0.88-mysql.patch

For POP-before-SMTP to work, the POP3 daemon will need to run under the
tcpserver program. This is because vpopmail uses tcpserver's TCPREMOTEIP
environment variable to work out what IP address the POP3 user is
connecting from.

Over time POP-before-SMTP is becoming a less favored way of allowing roaming
users to relay mail. SMTP-Auth appears to becoming the more preferred option,
as it scales much more easily on a busy server. However for a small to medium
sized server, POP-before-SMTP is still quite a workable option. If you would
like investigate the use of SMTP-Auth, take a look at this patch
http://www.fehcom.de/qmail/smtpauth.html#PATCHES

IMAP-before-SMTP is possible when using Courier-IMAP v3.x. However it only
works when configured "--with-authvchkpw --without-authdaemon". When running
--without-authdaemon, Courier-IMAP's authvchkpw code is able to make use of
vpopmail's roaming user functions to allow IMAP-before-SMTP functionality.
IMAP-before-SMTP is not possible when Courier-IMAP has been complied
--with-authdaemon, because in this mode the user's IP address is not made
available to the authvchkpw code (the TCPREMOTEIP env var is not set). Also,
in Courier-IMAP v4.x and later, --without-authdaemon functionality is no
longer available this preventing IMAP-before-SMTP from working.

----------------------------------------------------------------------------

4/28/2007

* SpamAssassin Support in vdelivermail

Vdelivermail can call spamc during local delivery to a Maildir.  To enable
this, simply compile vpopmail with --enable-spamassassin=y.  Configure will
look for the spamc program in /usr/bin and /usr/local/bin.  If it not found,
you will need to specify the location with the additional
--enable-spamc-prog='/path/to/spamc' option.

If you want to disable spamc processing for a user or domain, you may do so
with the vmoduser program:

vmoduser -f user@domain.com
or
vmoduser -f domain.com

You may also have vdelivermail discard a message found to be spam.  This also
can be done with vmoduser:

vmoduser -F user@domain.com
or
vmoduser -F domain.com

When compiled with SpamAssassin support, spamc processing defaults to "on" for
users.  Deleting spam defaults to "off".  If you want to override these
defaults on a system or per domain basis, these can be set as well with the
following entries to vlimits.default, or .qmailadmin-limits, respectively:

disable_spamassassin
delete_spam

If you want to automatically filter mail, see README.maildrop


Bill Shupp
hostmaster@shupp.org

--------------------------------------------------------------------------

Using vpopmail with Sybase is very rare.

The Sybase modules are understood to be functional, but because it not
as popular as using CDB or MySQL auth systems, you should be very wary
of implementing the Sybase system on a production server.

--------------------------------------------------------------------------

Edit vsybase.h and set the server, user, password and app information

Vdelivermail is the key to the proper operation of your vpopmail installation.
When qmail attempts to deliver a message to a vpopmail domain the first thing
it does is look for a .qmail file that matches the incoming address within the
top level directory for the domain.  If no such .qmail-* file is found, qmail-local
executes the .qmail-default file for the domain.  This is the point where vpopmail
takes over the the delivery process.  Vdelivermail searches the user database for
the domain, and either delivers the message to one of its existing accounts, or
looks to its second parameter for instructions on what to do with messages to
accounts that do not exist.

For vpopmail to operate properly, the .qmail-default file in the domain directory must
be setup properly.  There should only be one line in the file, and it must look like this:

   | /path/to/vdelivermail '' delivery-instruction


   | - The initial pipe tells qmail-local to execute a program.

   /path/to/vdelivermail - This is the program that must be executed.

   ''  This unused, empty parameter is required for historical reasons.

   delivery-instruction must be one of:

      someone@anotherexample.com   - an email address anywhere in the world.

      /path/to/some/Maildir        - a Maildir on the local server that the
                                     vpopmail user has write access to.

      delete                       - Delete all mail to non-existant users

      bounce-no-mailbox            - Bounce all mail to non-existant users


Bounce-no-mailbox is no longer recommended, as it allows your mail server to be used
in Joe-Jobs.  It now seems better to delete all mail to invalid addresses rather than
spamming the random senders used by spam-bots.


When creating a domain you can use one of the following:

   vadddomain -b someone@anotherexample.com example.com [password]

   vadddomain -b /path/to/some/Maildir example.com [password]

   vadddomain -b delete example.com [password]

   vadddomain -b bounce-no-mailbox example.com [password]



In summary...  the .qmail-default of every virtual domain MUST contain ONLY a single
line that executes vdelivermail.  The ONLY place you should EVER call vdelivermail
is from the .qmail-default file of a vpopmail based virtual domain.  There are
four possible delivery options for non-existant mailboxes that must be the second
parameter to vdelivermail.  The empty first parameter is required.

If you are not sure what you are doing writing .qmail files, and mucking around
the internals of vpopmail, I strongly suggest you leave this file to the programs.
Qmailadmin is probably the easiest way to manage the .qmail-default file once the
domain has been created.

Due to the requirement that Maildirs accessed by vpopmail must be owned by vpopmail
I suggest that if you are going to use vpopmail at all that you place all of your
domains under vpopmail.  While it is possible to continue to have system users, and
other styles of qmail virtual domains on a vpopmail system, you really have to be a
qmail guru to make it all work.

VPOPMAIL DOMAIN LIMITS                                              (1/15/2004)

* OVERVIEW

    Vpopmail can set certain limits for domains. These limits are stored in
    the file ".qmailadmin-limits", in the domain's directory (i.e.
    /home/vpopmail/domains/test.com/.qmailadmin-limits).  Limits can optionally
    be stored in a mysql table (limits) instead when vpopmail is configured
    with --enable-mysql-limits.  If .qmailadmin-limits does not exist for a
    domain (or there is no entry for them in the limits table), then
    ~vpopmail/etc/vlimits.default is used.  ~vpopmail/etc/vlimits.default
    *must* be present, and is installed with vpopmail automatically.  You may
    edit it, but do not remove it.

    Items that can be limited include:

    Default Quota for new users (default_quota, in bytes)
    Default Maximum Message Count Quota for new users (default_maxmsgcount)
    Disable POP Access (disable_pop)
    Disable IMAP Access (disable_imap)
    Disable Dialup Access (disable_dialup)
    Disable Password Changing (disable_password_changing)
    Disable External Relay/Roaming Users (disable_external_relay)
    Disable SMTP AUTHORIZATION (disable_smtp)
    Disable SqWebMail Access (disable_webmail)

    The following 2 limits require that you configure vpopmail with
    --enable-domainquotas=y:

    Quota for Entire Domain (quota, in megabytes)
    Maximum Message Count for Entire Domain (maxmsgcount)

    In addition, you can set QmailAdmin specific limits on the domain
    administrator (usually postmaster), such as:

    Maximum Number of Pop Accounts (maxpopaccounts)
    Maximum Number of Forwards (maxforwards)
    Maximum Number of Autoresponders (maxautoresponders)
    Maximum Number of Mailing Lists (maxmailinglists))

    The following QmailAdmin specific items are mentioned in the
    vlimits.default file, but are NOT YET IMPLEMENTED in QmailAdmin:

    perm_account
    perm_alias
    perm_forward
    perm_autoresponder
    perm_maillist
    perm_quota
    perm_defaultquota

* BACKWARDS COMPATIBILITY

    Before Vpopmail 5.4, vpopmail stored some user limits only in the gid
    field of the user entry, such as NO_POP, NO_IMAP, etc..   When the
    .qmailadmin-limits file was used by QmailAdmin (prior to 1.2), it treated
    these limits as *default* limits, and accordingly set the the gid bit flag
    of the user entry when creating a user.  This is no longer the case since
    these are now *domain* limits, and not *default* limits.

    The difference with domain limits is that the gid field is not set when a
    user is created, so modifying .qmailadmin-limits will immediately reflect
    on all accounts for the domain.  This is accomplished with a new "virtual"
    vqpasswd field, pw_flags.  pw_flags is a combination of the gid field, and
    the domain's limits.

    If the pw_flags field is not present, then the gid field is used for
    backwards compatibility.

    NOTE:  default_quota and default_maxmsgcount use the default approach
    described above.  It's also important to add that these limits *replace*
    the old configure options --enable-defaultquota and --enable-hardquota.

* CONFIGURATION

    Modification of domain limits is done with vmoddomlimits.  If no arguments
    are given, then usage is displayed.  The -S argument will show the current
    domain limits.  For example, if I wanted to set limits on test.com, I
    could issue:

    vmoddomlimits -P 11 -L 2 -g p -q 10485760 test.com

    The above command will limit an administrator logged into QmailAdmin
    (postmaster) to 11 pop accounts, and 2 mailing lists.  It will also deny
    pop access, and set the default quota to 10MB (in bytes).  Here's the
    output of vmoddomlimits -S test.com:

	###############################################################
	Domain: test.com
	--
	Max Pop Accounts: 11
	Max Aliases: -1
	Max Forwards: -1
	Max Autoresponders: -1
	Max Mailinglists: 2
	GID Flags:
	  NO_POP
	Flags (for commandline): p
	Flags for non postmaster accounts:
	  pop account:            DENY_CREATE  DENY_MODIFY  DENY_DELETE
	  alias:                  ALLOW_CREATE ALLOW_MODIFY ALLOW_DELETE
	  forward:                ALLOW_CREATE ALLOW_MODIFY ALLOW_DELETE
	  autoresponder:          ALLOW_CREATE ALLOW_MODIFY ALLOW_DELETE
	  mailinglist:            ALLOW_CREATE ALLOW_MODIFY ALLOW_DELETE
	  mailinglist users:      ALLOW_CREATE ALLOW_MODIFY ALLOW_DELETE
	  mailinglist moderators: ALLOW_CREATE ALLOW_MODIFY ALLOW_DELETE
	  quota:                  ALLOW_CREATE ALLOW_MODIFY ALLOW_DELETE
	  default quota:          ALLOW_CREATE ALLOW_MODIFY ALLOW_DELETE
	Domain Quota: 0 MB
	Default User Quota: 10485760 bytes
	Max Domain Messages: 0
	Default Max Messages per User: 0
	###############################################################

	REMINDER: "The Flags for non postmaster accounts:" are NOT yet supported
    by QmailAdmin

    If you want to edit or show the ~vpopmail/etc/vlimits.default file, just
    use the -d option with vmoddomlimits program and leave off the domain
    argument.

    To set unique limits on a single user, you may still manually set the gid
    flag using vmoduser.  The domain limits are applied in addition to the gid
    flag limits.  So, if you want to *remove* limits for a certain user, like
    allow POP access when it is turned off for a whole domain, you'll need to
    set the V_OVERRIDE flag via vmoduser -o user@test.com.  The V_OVERRIDE
    flag will override any domain limits that are in place.  The user's gid
    flag limits will still apply.

* CREDITS

    The original vlimits idea and code was done by Brian Kolaci (bk@kola.com).
    This document was written by Bill Shupp (hostmaster@shupp.org).

NOTE:  New commands added to daemon, with no mention in the help yet...

get_user_size user@example.com

get_domain_size domain



==========================================================================


Vpopmaild provides a way for authorized clients to perform most of the
tasks you can do with the vpopmail command line tools, without having
to ssh into the server and run them by hand.  We are not yet at a point
where every function available in vqadmin and qmailadmin is available
from the daemon, but that is the plan.

This documentation is still rough, but it is a start.  It is a
combination of the original information provided by Ken Jones, the
original author of vpopmaild, a list of functions available by Rick
Widmer and some pages from John Simpson's qmail web site:

  http://qmail.jms1.net/


If you are looking for step by step instructions for setting up a qmail +
vpopmail server that includes the daemon, try Bill Shupp's toaster:

   http://shupp.org/toaster/


Another source of information on the daemain is Inter7's qmail
wiki:

  http://qmailwiki.inter7.com/Vpopmaild



The most basic capability of vpopmaild is to verify whether or not a
given email address and password are correct.  This can be done with
the slogin command.  Basically, if the slogin command succeeds, the
address and password are valid. If not, then they are not valid.  You
should quit or exit the daemon before you close the connection.

Once you are logged in your personal rights will control which commands
you can use, and how much of the mail system you can control.  The
daemon supports creating and deleting domains only for system
administrators.  Creating addresses, aliasas and such within a domain
for system and domain administrators.  Anyone can change their password,
set up a forward or vacation message.  (Try help from various users.)


There are at least two projects to replace qmailadmin using the daemon.
Rick Widmer has one on SourceForge called pmailadmin.  Currently only
the daemon interface and system library are operational.

   http://pmailadmin.sourceforge.net/

Bill Shupp has announced a project, it is currently only available
if you email the author.


There are five sections to the rest of this document:

  1: Using the service

  2: Command List

  3: Installing the Daemon

  4: Bitmap Values

  5: Interpreting Errors

--------------------------------------------------------------------
--------------------------------------------------------------------
--------------------------------------------------------------------
--------------------------------------------------------------------

1 :   U s i n g   t h e   s e r v i c e



If you don't yet have the daemon running, skip down to section 3,
Installing the Daemon, and use one of those options to start the daemon.
Once the service is running, you can test it by telnetting to localhost
port 89. This is a sample of what it looks like when running as a service
on port 89.

  $ telnet localhost 89
  Trying 127.0.0.1...
  Connected to 127.0.0.1.
  Escape character is '^]'.
  +OK
  login userid@domain.xyz p@ssw3rd
  +OK+
  vpopmail_dir /home/vpopmail
  domain_dir /home/vpopmail/domains/domain.xyz
  uid 89
  gid 89
  name userid
  comment userid
  quota NOQUOTA
  user_dir /home/vpopmail/domains/domain.xyz/userid
  encrypted_password $1$ZXWVRRi9$X.ZdqlNURS32jD4YdkFkq0
  clear_text_password
  no_password_change 0
  no_pop 0
  no_webmail 0
  no_imap 0
  bounce_mail 0
  no_relay 0
  no_dialup 0
  user_flag_0 0
  user_flag_1 0
  user_flag_2 0
  user_flag_3 0
  no_smtp 0
  domain_admin_privileges 0
  override_domain_limits 0
  no_spamassassin 0
  delete_spam 0
  system_admin_privileges 0
  .
  quit
  +OK
  Connection closed by foreign host.

As you can see, when you successfully log into the service, it shows
you pretty much everything about the account you are logged into.  The
clogin command returns the same information, but does not decode the
gid_flags bitmap.  This reduces the amount of data transferred by about
60%.  Think Compact Login.  It does this for all commands that return
bitmap values for the entire session.  If you are writing a program to
access the daemon, it is probably easier to decode the bitmap than the
lines of text.  The bit values are listed in section 4 near the end of
this file.


  $ telnet localhost 89
  Trying 127.0.0.1...
  Connected to 127.0.0.1.
  Escape character is '^]'.
  +OK
  clogin userid@domain.xyz p@ssw3rd
  +OK+
  vpopmail_dir /home/vpopmail
  domain_dir /home/vpopmail/domains/domain.xyz
  uid 89
  gid 89
  name userid
  comment userid
  quota NOQUOTA
  user_dir /home/vpopmail/domains/domain.xyz/userid
  encrypted_password $1$ZXWVRRi9$X.ZdqlNURS32jD4YdkFkq0
  clear_text_password
  gidflags 196608
  .
  quit
  +OK
  Connection closed by foreign host.


When all you need to know is if the current login is valid, use the slogin
command.  Think Silent Login.  All this returns is +OK if the user exists
and the password is valid or -ERR if either is incorrect.  You should send
the quit command before you disconnect from the service.

  $ telnet 127.0.0.1 89
  Trying 127.0.0.1...
  Connected to 127.0.0.1.
  Escape character is '^]'.
  +OK
  login userid@domain.xyz p@ssw3rd
  +OK
  quit
  +OK
  Connection closed by foreign host.


A few things are worth mentioning here...

The help command will show you a list of all of the commands that you have
permission to use.  Help can be used before or after login.  There are
three kinds of users with increasing commands that they can use.

A simple user can change their password, create forwards and mail robots,
and maintain a set of .vpopmail-extension files similar to the .qmail-extension
capability of qmail-local.

If the domain_admin_privileges flag is set to 1, you are able to administer
any mailbox within the domain of your account (i.e. if you are logged in as
postmaster@domain.xyz you will be able to create, delete, and modify
mailboxes within the domain.xyz domain.

If the system_admin_privileges flag is set to 1, you are able to administer
any mailbox on the system, plus list, add, remove, and otherwise administer
entire domains.

The various flags associated with each account are manipulated using the
mod_user command within the service, or using the vmoduser command line
program. For example, to set the domain_admin_privileges flag for an
account, you can use the following command:

As root...

  # vmoduser -a postmaster@domain.xyz

You can run vmoduser by itself to see the list of flags which can be set.
Note that some of the flags may not have any effect on your system,
depending on how vpopmail was compiled.

Be very careful with the -S option (which sets the system_admin_privileges
flag.)  If you are going to have user with system admin rights, you might
want to create a domain with an illegal name like  illegal.xyz  vpopmaild
will allow you to login, but there is no way to send email to this domain.

  #  vadddomain illegal.xyz postmaster-password
  #  vmoduser -S postmaster@illegal.xyz



--------------------------------------------------------------------
--------------------------------------------------------------------
--------------------------------------------------------------------
--------------------------------------------------------------------

2 :    C o m m a n d s



consider ordering commands from lesser rights to more rights.

NOTE: mod_user is the one with the breakdown of the gidflage bitmap.


--------------------------------------------------------------------

login user@domain.ext password  - verbose user/domain attributes
clogin user@domain.ext password - compact user/domain attributes
slogin user@domain.ext password - silent, just return success or
                                  failure of login

Rights required: Must be a valid email address.

Action:	Verify the username and password of the person desiring to
	login, and set their access rights.

	For the "login" command, a successful login will return a
	full list of the user's information.

	For the "clogin" command, a successful login wil return a
	compact version of the user's information- bitmap values
	are returned as a single numeric value instead of a line
	for each bit used. This reduces data transfer, but requires
	the client to split up the bitmap.

	For the "slogin" command, a successful login only returns
	the "+OK " response, with no additional information. This
	is useful in cases where the client does not need to know
	anything other than whether or not the login attempt was
	successful (i.e. for the SMTP AUTH command.)

--------------------------------------------------------------------

add_user user@domain.ext password

Rights required: SA_ADMIN, or QA_ADMIN

Action:  Add a new mailbox and user to the specified domain.  ONLY SA_ADMIN
can add users to domains other than the home domain of the login user.


--------------------------------------------------------------------

del_user  user@domain.ext

Rights required: SA_ADMIN, or QA_ADMIN

Action:  Delete a mailbox and user from the specified domain.  ONLY SA_ADMIN
can delete users from domains other than the home domain of the login user.


--------------------------------------------------------------------

mod_user user@domain.ext

Rights required: Only SA_ADMIN can modify users outside
the login user's home domain.  Only QA_ADMIN can modify other users.
Any user can modify part of their own data.

Action:  Modify a user account.

The mod_user command is followed by any number of the following options,
one per line, followed by a line containing only a '.'.  Each flag except
the clear_all_flags expects a 0 or 1 to set the value of the flag.

Anyone can set these values:

comment - The full name of the user.

clear_text_password - Pass it a clear text password, and it will set both
                      the clear_text_password and the encrypted_password
                      field.  It handles encrypting the password internally.

no_spamassassin - Do not run SpamAssasin for this user, if it is set to
                  be run for users of this domain.

delete_spam - If set, mail identified as spam for this user will be deleted.


The QA_ADMIN or SA_ADMIN can change these values:


Only a SA_ADMIN or QA_ADMIN with override rights can change these values:

quota - Number of messages they can store.

clear_all_flags - reset all the following flag values to 0.

no_password_change - The user can not change their own password.

no_pop - The user can not access mail via pop.

no_webmail - The user can not access mail via a webmail program.

no_imap - The user can not access mail via imap.

bounce_mail - I'm not sure, but it sounds like a flag to bounce all
              mail to this user.

no_relay - I'm not sure, but it sounds like a flag to block use of SMTP
           for this user for mail leaving the server.

no_dialup - This is used by the optional radius server as a flag to stop
            radius from allowing this user to login to a modem.

user_flag_0 - Set and check this flag for anything you want.

user_flag_1 - Set and check this flag for anything you want.

user_flag_2 - Set and check this flag for anything you want.

user_flag_3 - Set and check this flag for anything you want.

no_smtp - I'm not sure.

domain_admin_privileges - allow this user limited access to their home domain.

override_domain_limits - Allow this user to change domain limits on their
                         own domain.  Probably also requires domain_admin.


Only a SA_ADMIN can change these values:

encrypted_password - an already encrypted password.  This only sets the
                     encrypted password field.

system_admin_privileges - allow this user full access to all domains.

system_expert_privileges - allow this user to edit .qmail files.



--------------------------------------------------------------------

user_info user@domain.ext

Rights required: SA_ADMIN, or QA_ADMIN

Action:  Return information about a user.

The following items are returned as a string.

name - User name, same as user part of address selected.

comment - Usually the long name of the user.

quota - How much disk space the user is allowed.

user_dir - The home directory for the user.

encrypted_password - The encrypted value of the password.

clear_text_password - The password in clear text.


The following values are returned as the character '1' or '0'. '1'
says the field is active - for example, an active no_password_change field
means the user can not change passwords.

no_password_change, no_pop, no_webmail, no_imap, bounce_mail, no_relay,
no_dialup, user_flag_0, user_flag_1, user_flag_2, user_flag_3, no_smtp


The following items confer extra privileges to the user. A '1' says that
the user has that right.

domain_admin_privileges, override_domain_limits, system_admin_privileges


The following items control the operation of Spamassassin.
no_spamassassin, delete_spam


--------------------------------------------------------------------

add_domain domain password

Rights required: SA_ADMIN

Action:  Add a new, real domain.  The postmaster user is automatically
created, and cannot be deleted.  The password given is assigned to the
postmaster user.


--------------------------------------------------------------------

add_alias_domain domain alias

Rights required: SA_ADMIN

Action:  Add an alias to an existing domain.  Qmail will recognize
the alias domain name, but all incoming mail to that domain will
be sent to the real domain.  Currently the order of the parameters
must be correct.  Consider stealing code from vaddaliasdomain so
it doesn't matter what order you enter them in.


--------------------------------------------------------------------

del_domain domain

Rights required: SA_ADMIN

Action:  Delete a domain from the system.  If the domain is an alias
it will delete only the alias.  If the domain has aliases, the domain
and all of its aliases will be deleted.  If you want to warn the user
of your program when alias domains exist, YOU will have to do it yourself
by using dom_info() to check the status of the domain in question.


--------------------------------------------------------------------

dom_info domain

Rights required: SA_ADMIN

Action: return internal information about a domain.  The information
returned includes: domain directory, userid, groupid, number of users.
If you ask for an alias domain, you will receive information for the
parent domain.  Part of that information will include a list of all
alias names of the parent domain.


--------------------------------------------------------------------

find_domain domain per_page

Rights required: SA_ADMIN

Action: Return the page number that the named domain appears on only if the
domain exists.  Otherwise, just "." is returned.  This can be used when you are
using list_domains with the optional page and lines_per_page parameters.  If
you list the page returned by find_domain, the desired domain will appear on
that page. It may not be at the top of the page.  The page positions are fixed.
If no per_page argument is given, it defaults to one item per_page.  Page
numbers start at 1.

--------------------------------------------------------------------

domain_count

Rights required: SA_ADMIN

Action:  Return the number of domains.  This can be used to determine
the number of pages of domain information that is available.


--------------------------------------------------------------------

user_count domain

Rights required: SA_ADMIN, QA_ADMIN. QA_ADMIN can only manage their
own domain.

Action: Return the number of accounts in a domain.  This can be used to
determine the number of pages of user account information that is available.



--------------------------------------------------------------------

mk_dir directory

Rights required: SA_ADMIN, QA_ADMIN or USER.  QA_ADMIN can only work within
their own domain.  USER can only work within their home directory.

Action:  Create a directory.

Directory can be specified as a real path starting at root, as a domain
name, or as an email address.  When a domain name is specified, that
is replaced by the path to the domain directory for that domain.  When
an email address is specified, that starts at the home directory for
that email address.


--------------------------------------------------------------------

rm_dir directory

Rights required: SA_ADMIN, QA_ADMIN or USER.  QA_ADMIN can only work within
their own domain.  USER can only work within their home directory.

Action:  Remove a directory

Directory can be specified as a real path starting at root, as a domain
name, or as an email address.  When a domain name is specified, that
is replaced by the path to the domain directory for that domain.  When
an email address is specified, that starts at the home directory for
that email address.


--------------------------------------------------------------------

list_dir directory

Rights required: SA_ADMIN, QA_ADMIN or USER.  QA_ADMIN can only work within
their own domain.  USER can only work within their home directory.

Action:  List the contents of a directory.

Directory can be specified as a real path starting at root, as a domain
name, or as an email address.  When a domain name is specified, that
is replaced by the path to the domain directory for that domain.  When
an email address is specified, that starts at the home directory for
that email address.

Directory contents are returned one per line, with an indication of the
type of directory entry.  For example:

Maildir dir
lastauth file

The possible type values are: file, dir, chardev, blkdev, fifo,
link, sock, unknown.


--------------------------------------------------------------------

rm_file filename

Rights required: SA_ADMIN, QA_ADMIN or USER.  QA_ADMIN can only work within
their own domain.  USER can only work within their home directory.

Action:  Remove a file.

Directory can be specified as a real path starting at root, as a domain
name, or as an email address.  When a domain name is specified, that
is replaced by the path to the domain directory for that domain.  When
an email address is specified, that starts at the home directory for
that email address.


--------------------------------------------------------------------

write_file filename

Rights required: SA_ADMIN, QA_ADMIN or USER.  QA_ADMIN can only work within
their own domain.  USER can only work within their home directory.

Action:  Write lines to a file.

Filename can be specified as a real path starting at root, as a domain
name, or as an email address.  When a domain name is specified, it
is replaced by the path to the domain directory for that domain.  When
an email address is specified, that starts at the home directory for
the email address.

File contents are sent, one line sent to the daemon for each line
to add to the file.  After the last line send a line containing only
a period '.' to mark the end of file.


--------------------------------------------------------------------

stat_file filename

Rights required: SA_ADMIN, QA_ADMIN or USER.  QA_ADMIN can only work within
their own domain.  USER can only work within their home directory.

Action: Stat a file.

Filename can be specified as a real path starting at root, as a domain
name, or as an email address.  When a domain name is specified, it
is replaced by the path to the domain directory for that domain.  When
an email address is specified, that starts at the home directory for
the email address.

Currently only the UID of the owner of the file is returned if it exists
or an error (2202) is returned.  It seems to me this should be extended
to include at least access rights in octal, size, owner group, last access,
last mod, last change.


--------------------------------------------------------------------

read_file filename

Rights required: SA_ADMIN, QA_ADMIN or USER.  QA_ADMIN can only work within
their own domain.  USER can only work within their home directory.

Action:  Read lines from a file.

Filename can be specified as a real path starting at root, as a domain
name, or as an email address.  When a domain name is specified, it
is replaced by the path to the domain directory for that domain.  When
an email address is specified, that starts at the home directory for
the email address.

File contents are received, one line from the daemon for each line
in the file.  After the last line of the file a line containing only
a period '.' is sent to mark the end of file.



--------------------------------------------------------------------

list_domains [page lines_per_page]

Rights required: SA_ADMIN

Action:  List all domains on the system, and their parent domain.
If the optional page is given, lines_per_page must also be specified.
When both are given, the data is broken up into pages with lines_per_page
lines on each.  The page returned is specified by page.

Alias domains are identified by the fact that the domain name does
not match the real domain name.


--------------------------------------------------------------------

list_users domain [page lines_per_page]

Rights required: SA_ADMIN, or QA_ADMIN.  QA_ADMIN can only manage their
                 own domain.

Action:  List all Mailbox accounts for a domain.

It returns the same info about a user as something else.  Find it and
copy the info here.  If the optional page is given, lines_per_page must
also be specified.  When both are given, the data is broken up into
pages with lines_per_page lines on each.  The page returned is
specified by page.


--------------------------------------------------------------------

list_alias domain

Rights required: SA_ADMIN, or QA_ADMIN.  QA_ADMIN can only manage their
                 own domain.

Action:  List all aliases for a domain.  Currently, this scans the directory
         for aliases.  It needs to be changed to use the new valias calls
         Tom just added.


List all Mailbox accounts for a domain.


--------------------------------------------------------------------

list_lists domain

Rights required: SA_ADMIN, or QA_ADMIN.  QA_ADMIN can only manage their
                 own domain.

Action:  Send a list of all mailing lists within a domain.  One entry
per line, with a line containing only a '.' at the end.


--------------------------------------------------------------------

get_ip_map ip_address

Rights required: Anyone

Action: Return the domain associated with this IP Address, if any.


--------------------------------------------------------------------

add_ip_map ip_address domain

Rights required: SA_ADMIN

Action:  Make an IP address point to a domain.

WARNING:  It does not look like there is any duplicate checking on
this, so make sure what you enter is valid!  I think I once got the
IP and name backwards, and it was stored that way.  The error checking
belongs in the vpopmail library.


--------------------------------------------------------------------

del_ip_map ip_address domain

Rights required: SA_ADMIN

Action:  Delete an association between an IP address and a domain name.


--------------------------------------------------------------------

show_ip_map

Rights required: SA_ADMIN

Action:  Display the mapping between IP addresses and domain names.


--------------------------------------------------------------------

get_limits domain

Rights required: Any.  SA_ADMIN can read all domains, all other users
                 can only read their own domain.

Action:  Return Limits information for a domain.  If no special limits
         are set, it returns the default limit settings for all domains.
         Find out where these files are kept, and add it here.

max_popaccounts
max_aliases
max_forwards
max_autoresponders
max_mailinglists
maxmailinglists
disk_quota
max_msgcount
default_quota
default_maxmsgcount
disable_pop
disable_imap
disable_dialup
disable_password_changing
disable_webmail
disable_external_relay
disable_smtp
disable_spamassassin
delete_spam
perm_account
perm_alias
perm_forward
perm_autoresponder
perm_maillist
perm_quota
perm_defaultquota


--------------------------------------------------------------------

set_limits domain

Rights required: SA_ADMIN, or QA_ADMIN with override_domain_limits rights.

Action:  Set Limits informaiton for a domain.

max_popaccounts
max_aliases
max_forwards
max_autoresponders
max_mailinglists
maxmailinglists
disk_quota
max_msgcount
default_quota
default_maxmsgcount
disable_pop
disable_imap
disable_dialup
disable_password_changing
disable_webmail
disable_external_relay
disable_smtp
disable_spamassassin
delete_spam
perm_account
perm_alias
perm_forward
perm_autoresponder
perm_maillist
perm_quota
perm_defaultquota


--------------------------------------------------------------------

del_limits domain

Rights required: SA_ADMIN

Action:  Delete the limits file for a domain.  This will make the
         domain revert to the global limits set somewhere. (Find
         out where, and add it here.)


--------------------------------------------------------------------

get_lastauth user@domain.ext

Rights required: Any.  SA_ADMIN can list any user, QA_ADMIN can list
                 any user in their domain, USER can list only their
                 own.

Action:  Return the last time and IP address from the last time the
user logged in.


--------------------------------------------------------------------

get_lastauthip     --    D E L E T E D !

Merged with get_lastauth, use it instead.


--------------------------------------------------------------------

add_list

Rights required: SA_ADMIN, or QA_ADMIN.  QA_ADMIN can only work in
                 its home domain.

Action:  Add an ezmlm mailing list.  Not implemented yet.


--------------------------------------------------------------------

del_list

Rights required: SA_ADMIN, or QA_ADMIN.  QA_ADMIN can only work in
                 its home domain.

Action:  Delete an ezmlm mailing list.  Not implemented yet.


--------------------------------------------------------------------

mod_list

Rights required: SA_ADMIN, or QA_ADMIN.  QA_ADMIN can only work in
                 its home domain.

Action:  Modify an ezmlm mailing list.  Not implemented yet.


--------------------------------------------------------------------

quit, exit, q

Rights required: Any

Action:  Shutdown the daemon.  You should always call this before
         exiting the program communicating with the daemon.


--------------------------------------------------------------------

help

Rights required: Any

Action:	Display a list of the commands currently available to the
	client. The list will adjust itself to match the access
	rights of the userid with which the client is logged in.
	If the client is not logged in yet, only the "login",
	"clogin", "slogin", "help", and "quit" commands are shown.




--------------------------------------------------------------------
--------------------------------------------------------------------
--------------------------------------------------------------------
--------------------------------------------------------------------


3 :    R u n n i n g   v p o p m a i l d


For a simple quick test, just run the daemon at the command line.

As root...

  # ./vpopmaild


To run under tcpserver temporarily from the command line:

As root...

  # tcpserver -vHRD 0 89 ./vpopmaild


Running vpopmaild under daemontools is the only way to run it as a
mission critical service.

There is one important difference between this script and a "generic"
script which usually sets up a service listening on IP address "0", or
listening on every interface on the server. This is a MAJOR security
hole- allowing clients to connect across the network allows somebody
with a packet sniffer to watch every byte which goes across the wire-
including passwords. This script sets up a service which only listens
on 127.0.0.1, which on most systems is the "localhost" interface- which
means that the packets never physically leave the machine, and
therefore cannot be "sniffed" by other machines.

Setting up the service

Note that the commands below assume that your daemontools services are
physically running in the /var/service directory.  If you keep your
services somewhere else, or want to set up your own service directory
somewhere, that works as well- just make sure that the physical location
is not under /service or you will not be able to reliably stop the
service when needed.

As root...

  # mkdir -m 1755 /var/service/vpopmaild
  # cd /var/service/vpopmaild

Copy the following lines into a file named run in the directory you
just created.  Don't include the  --- lines in the file, they just
show the beginning and end of the file.

---------------------------------------------------------------------
#!/bin/sh
exec 2>&1
exec env - PATH="/usr/bin:/bin:/usr/local/bin" \
     tcpserver -vHRD 127.0.0.1 89 ~vpoppmail/bin/vpopmaild
---------------------------------------------------------------------

  # chmod 755 run
  # mkdir -m 755 log
  # cd log

Copy the following lines into a file named run in the directory you
just created.

---------------------------------------------------------------------
#!/bin/sh
VQ="/var/qmail"
exec env - PATH="$VQ/bin:/usr/local/bin:/usr/bin:/bin" \
     multilog t n1024 s1048576 ./mail \
     '-*' '+*ver: status:*' =lstatus
---------------------------------------------------------------------

  # chmod 755 run
  # ln -s /var/service/vpopmaild /service/

Wait a few seconds...

  # svstat /service/vpopmaild
  /service/vpopmaild: up (pid 22457) 7 seconds
  /service/vpopmaild/log: up (pid 22460) 7 seconds



Using the service

Once the service is running, you can test it by telnetting to localhost
port 89.  Go back to the section on Running the deamon for an example
session.



--------------------------------------------------------------------
--------------------------------------------------------------------
--------------------------------------------------------------------
--------------------------------------------------------------------

4 :     B i t m a p   d e f i n i t i o n



This appeared early in the discussion leading to the daemon, so
until I find a better place for it, I'll add it here.  The important
thing is the comments on what each bit is supposed to mean.  This
may get re-worked into documentation on the daemon.


List of bits in the gid or flags field for a user, from a message
from Ken on the vpopmail list.


I'll try to give a detailed listing.
#define NO_PASSWD_CHNG 0x01
If set, the code should not allow the password to be changed

#define NO_POP         0x02
If set, reject pop authentications

#define NO_WEBMAIL     0x04
If set, reject webmail authentications

#define NO_IMAP        0x08
If set, reject imap authentications

#define BOUNCE_MAIL    0x10
If set, bounce any incoming mail back to the sender

#define NO_RELAY       0x20
If set, do not allow the account to relay email.
This is useful for sites that want to have email accounts that
are only allowed to send email internally.

#define NO_DIALUP      0x40
If set, code should not allow dialup access. This was originally
added to support radius sites.

#define V_USER0       0x080
#define V_USER1       0x100
#define V_USER2       0x200
#define V_USER3       0x400
After adding the NO_DIALUP flag we realized there may be other
flags people will want that are not directly used by any email code.

#define NO_SMTP       0x800
If set, do not allow smtp connections.

#define QA_ADMIN     0x1000
If set, the user is granted admin privileges in qmailadmin

#define V_OVERRIDE   0x2000
If set, the user is not subject to domain limits. Part of the
vlimit code.

#define NO_SPAMASSASSIN 0x4000
If set, (and --enable-spamassassin=y) do not process the
incoming mail through spamassassin.

#define DELETE_SPAM  0x8000
with --enable-spamasssassin=y setting this flag
will delete all email above the users required_hits
preference.


==============================================================================
The original readme from Ken:

To run as daemon:
tcpserver -vHRD 0 89 ./vpopmaild

Then as client
telnet localhost 89

Or to run on the command line for testing
./vpopmaild

First login. example:
login postmaster@example.com password

Then for list of commands:
help


--------------------------------------------------------------------
--------------------------------------------------------------------
--------------------------------------------------------------------
--------------------------------------------------------------------

5 :     E r r o r    M e s s a g e    F o r m a t


Error messages are in the form  ERR- major.minor message

Major is the error code that identifies what kind of error has been encountered,
and determines which message is displayed.  Minor is a number that identifies
which test within the source code triggered the error message.  The last two
digits should indicate the error number within a function, and the rest should
identify which function the failure happened in.  You can search the source
code with this value to find the point where an error happened.


The actual error messages are stored in the file vpopmaild.msg for easy translation.
Once there are other language files, I'll create a directory to store the various
language files, and use a symlink to select a language.  Error messages are set
at compile time.

0.X represents a message passed up from vpopmaild primitives, and does not otherwise
follow the standard error reporting structure.  (yet?)

** vqmaillocal has not been actively maintained and should not be used. **

vqmaillocal is a developmental replacement for
qmail-local. It will currently deliver email to
vpopmail existing vpopmail users.

Todo:
1) process .qmail-"user" files and .qmail-default file


How to install:

1) mv /var/qmail/bin/qmail-local /var/qmail/bin/qmail-local.orig

2) cp vqmaillocal /var/qmail/bin/qmail-local

done