原作者：Ken Jones
原文链接：http://inter7.com/vpopmail/vpopmail.html
英文版权所有：http://inter7.com 

译者：黄丽红
联系地址：kinki@freebsdchina.org
中文版权所有：freebsdchina.org (如要转载请保留版权声明) 

快速安装指南
快速安装vpopmail
解开vpopmail 分发包
添加vchkpw 组
添加vpopmail 用户，并指定为vchkpw组
./configure
make 
make install-strip

现在可以添加虚拟邮件域和虚拟邮件域用户。使用vadddomain 和 vadduser.。还须要修改你的pop 服务器的启动参数以使用vchkpw 程序来认证用户。

.设置所有的邮件用户成为虚拟邮件域的用户
我们推荐所有的邮件域都设置为虚拟邮件域。
配置选项
常用选项
(1)--enable-roaming-users=n|y Enable or dissable open relay after pop authentication.Default is no
配置这个选项为Yes意味着客户端的IP地址是添加到一个IP地址列表中，用于允许用户在他们的pop认证通过以后利用smtp转发信件。服务器端有一个cron job ：clearopensmtp，会从这个IP 地址列表中清除认证超过3个小时的IP地址。这个选项需要你以tcpserver的方式运行smtp,并且提供-x /etc/tcp.smtp.cdb 参数(或者其它你放置tcp.smtp.cdb文件的路径)。

(2)--enable-hardquota=#|n Set and Enable hard quota or n for no quota
为每个pop用户设置磁盘配额的最大值（硬）。默认值为50M。当用户的磁盘配额的最大值达到以后，所有新的发给用户的邮件将会被退回，并附上一条信息。这条信息可以被自定义定制。假如你想关掉磁盘配额设置，可以设置这个值为：NOQUOTA，例如 --enable-hardquota=NOQUOTA

(3)--enable-default-domain=name Default domain name, default is null
我们推荐把所有的邮件以虚拟邮件域的方式运行。你可以设置其中一个为缺省。如果你只有一个域，那么把它设置为缺省。缺省设置的邮件域的用户可以直接用用户名进行认证,即不需要使用用户名%虚拟邮件域的格式。

(4)--enable-ip-alias-domains=y|n enable virutal domain lookup via reverse ip address lookup for virtual domains.
每个域缺省都使用基于虚拟邮件域的用户名。也就是说：用户必须提供包含所属的域的名称的用户名，例如：用户名 %虚拟邮件域。这也可以通过设置--enable-default-domain option来覆盖这个规则。
Vpopmail也支持基于IP地址的虚拟邮件域。假如这个选项打开后，而用户没有提供%<虚拟邮件域>，那么就会触发一个对用户连接的服务器的IP地址的反向查询。如果服务器的IP地址能解析到一个域名，那么vpopmail使用那个域名做为邮件域。例如：
IP地址 w.x.y.z反向解析到test.com。用户设置他们的pop服务器的IP地址为w.x.y.z 并开始连接。vpopmail接收到这个连接，检查连接的服务器端的IP地址。做一个IP地址的反向查询从而获得test.com这个域名。用户 发送joe作为他们的pop用户名，vpopmail使用test.com作为域名。
你可以混合使用基于名称和基于IP地址的形式的虚拟主机。

(5)--enable-relay-clear-minutes=360 expire time for roaming users after pop authentication.
如果设置了--enable-roamin-users=y 选项，那么这个选项就设置了clearopensmtp应该保留用户的IP地址在列表中多长时间。默认值是3小时。

Mysql选项

(1)--enable-mysql=n|y use mysql, default is no
启用mysql认证方式。
注意：确认编辑vmysql.h以及设置mysql 服务器名称或者IP地址，mysql用户和mysql用户密码。这个mysql用户必须有创建vpopmail数据库和在此数据库里生成表的权限。

(2)--enable-sqlincdir= Directory where sql include files are.
设置mysql include文件的目录位置。默认值是设置为/usr/local/mysql。

(3)--enable-sqllibdir=/usr/lib/mysql Directory where sql libs are.
设置mysql libmysqlclient.a文件所在的目录。默认的会在/usr/lib/mysql中查找。

(4)--enable-sqllibs=mysqlclient libraries for sql linking.
设置连接的库。默认会是libmysqlclient.a

(5)--enable-large-site=n|y Default is no, tune for large numbers of users per domain
默认的，vpopmail放置所有的域信息在一个vpopmail表中。这是维护很多邮件站点的最有效的方法。假如你在运行一个有大量用户的站点，你也许会想设置这个选项为YES。假如设置为YES，vpopmail会为每个虚拟域生成一个表。主要的不同在于域名不存储在数据库中，因为表名包含了域名。对有500,000+用户的站点来说，这种设置可以节省非常有价值的硬盘空间。然而，对于有大量的邮件虚拟域的站点来说，这会导致mysql系统性能的降低。

Vpasswd/cdb 选项
(1)--enable-ucspi-dir=dir Directory where the compiled ucspi package is.
设置uspi-tcp包所在目录。默认设置为../ucspi-tcp-0.84。vpopmail使用在目录中的headers以及两个.a文件。

Logging选项
(1)--enable-logging=e|y|n Turn on (y) or off (n) logging to syslog or (e) only log errors 
设置日志纪录的等级。默认只记录pop认证错误。可以通过设置此选项为no，以关闭所有日志记录。也可以通过设置此选项为YES记录所有的pop认证。

(2)--enable-log-name=vpopmail set syslog name.
覆盖默认的vpopmail系统日志名称。

User/group 选项
(1)--enable-vpopuser=vpopmail user vchkpw was installed as.
假如基于某个原因你希望用一个不同的用户安装这个软件，那么使用这个选项。

(2)--enable-vpopgroup=vchkpw group vchkpw was installed as.
假如基于某个原因你希望用一个不同的组安装这个软件，那么使用这个选项。

(3)--enable-admin-email=email-address e-mail of system administrator.
覆盖默认的管理员邮件地址。

Directory and file location 选项
(1)--enable-tcpserver-file=/etc/tcp.smtp File where tcpserver -x relay information is stored.
设置你的tcp. smtp文件名。默认的设置程序在/etc中查找，然后再在/etc/tcprules.d目录查找。

(2)--enable-qmaildir=dir directory where qmail is installed.
假如在其它的目录中安装了qmail，而不是在/var/qmail，那么使用这个选项。

(3)--enable-tcprules-prog=/usr/local/bin/tcprules where is your tcprules program.
假如在其它的目录中安装了tcprules程序，而不是在/usr/local/bin，那么使用这个选项。

(4)--enable-apop-file=/etc/apop-secrets directory where apop secrerts are stored.
覆盖默认的apop-secrets文件的位置。

其它选项
(1)--enable-apop=y|n Enable or disable apop authentication.
通过设置这个选项为NO来禁用apop。默认为YES(pop and apop)。

(2)--enable-passwd=y|n Enable or disable /etc/passwd (or shadow) authentication.
覆盖默认的自动设置。默认的配置程序自动检测你的系统是否使用passwd 和 shadow passwords。通过设置这个选项为NO，你将禁止所有的/etc/passwd 认证。

Qmail 和 虚拟邮件域

qmail的邮件域有本地的和虚拟的两种分别。本地的邮件域是使用/etc/passwd 作为验证文件。而虚拟邮件域则以qmail的控制文档“virtualdomains”为依据。vpopmail使用qmail用户/认证文档和虚拟域文档。其中用户/认证会合并到一个user/cdb数据库内。user/cdb是一个hash数据库，用以加快匹配项的查询。如果一个项匹配到，那么qmail的发送程序将会投递邮件到在文件中定义的目录中去，并且使用预定义好的uid和gid进行投递操作的身份。Vpopmail使用这个方法来使qmail 投递程序使用单一的vpopmail用户和vchkpw组来投递所有的虚拟域的邮件。同时也使用它来直接投递邮件到/vpopmail/domains/虚拟邮件域目录中。

一旦qmail-local程序从users/assign获得信息，他会执行在目录中的标准的.qmail文件。一般来说，.qmail-文件可以用于转发，别名或者调用程序，例如ezmlm。如果没有匹配的项目，则qmail-local会查找一个.qmail-default文件。这是qmail-locals发送机制的最后一步。这个程序使用两个参数，第一个并不使用（只是为了向后兼容）。第二个参数是指定了如果一个虚拟域的用户找不到的情况下，那么该邮件默认发送到的地址。原则上，第二个参数可以是邮件应该投递到的目录，或者一个用于转发过去的邮件地址，或者字符串 “邮箱不存在”，和邮件一起退回给发送方。

一旦vdelivermail起来后，它就会使用核心的vpopmail api 来检查一个虚拟域用户。如果用户退出了，邮件将被投递到他的目录。如果vpopmail有hard quotas(默认是50M的磁盘配额)，然后，用户的maildir/new邮件文件和Maildir/cur目录都会被计算。如果用户的磁盘配额使用完，邮件会被配回给发送方，并附上一个可以自定义的消息。如果新的邮件只有1K字节或者更小，那么不管配额是否使用完，仍会被投递而不受磁盘配额的限制。所以系统管理程序一直能够给用户发送消息。

转化现有用户帐户
转化程序可以把邮件账户从一种格式转化成另一种格式。转化程序可以在/etc/passwd,vpasswd文件、mysql(小规模)和mysql(大规模)之间转化。
现在大多数的vpopmail用户也许比较感兴趣怎样转化现有的域到mysql格式的域。转化整个机器的用户到mysql格式,使用以下命令：vconvert -c -s 。这将会检查~vpopmail/domains目录下的所有域，并读取每一个vpasswd 文件并且加载获得的内容到mysql的vpopmail . vpopmail表中。而vpasswd文件基于安全的原因保持不改变。Vconvert也可以同时处理多个一个或多个域。这个可以通过运行一下命令: vconvert \c \s domain1 domain2 ...来实现。

要转化所有用户(除root 和系统帐户)为mysql域格式的用户，可以运行一下命令：vconvert -e -s domain。这将会读取所有的/etc/passwd账号并用他们的密码生成mysql中的项。原来的密码既可以在/etc/passwd或者/etc/shadow。这些密码需要和vchkpw 认证程序一起工作。

Security and pop server under tcpserver
加入所有的pop邮件帐户都在虚拟域中，你通过使用tcpserver -u and -g options来指定使用vpopmail/vchkpw用户和组来运行pop服务器，以增加你的pop服务器的安全性。

命令集
Quota’s
Bouncing mail
Directory structure
Overall vpopmail directory structure
Vpopmail 拥有自己的主目录。在这个目录下有下列内容：

bin -包含所有二进制程序
lib -包含libvpopmail . a文件
include -包含C 程序的头文件
users -为了向后兼容那些在域内既有/etc/passwd也有vpopmail的用户的域
domains -保存所有的虚拟邮件域的目录

Virtual domain user directory structure
vpopmail使用一种基于一个“. dir-control”的状态文件的适应性的目录结构，而这个状态文件是自动由vpopmail的api程序“vadduser”和“vdeluser”进行管理的。对于100或者更少用户的站点，所有的用户目录都存储在虚拟域目录中。对于多于100用户的站点，这个适应性的目录结构特性就开始发挥作用。基本的思路是分拆用户的Maildir目录到多个目录和子目录中，以保证在单一的目录中永远不会多于100个用户目录。
假如你将要存储大量的用户目录，请确认你设置了你的文件系统有一个比常规的文件系统更高的inodes。 
Vpopmail会根据需要自动创建这些目录和子目录，而且通常每个目录最多设置100个用户。当一个目录达到了100个用户，它将会创建另外的目录或者子目录，同时存储新的用户到那新创建的目录中去。

在源文件目录的contrib子目录中有一个重新组织目录的程序。

Internationalization

有两种信息会插入到邮件中。两种信息都是针对需要退回的邮件。第一种是没有这个用户而第二种是用户空间使用已经超过设定的配额。站点管理员可以通过在虚拟邮件域目录里创建 一个. over-quota.msg 和 . no-user.msg文件来自定义这些信息，如果在虚拟邮件域目录中没有找到一个. over-quota.msg或者 . no-user.msg文件，那么程序将会在主要的虚拟邮件域目录中查找他们。假如在那里没有找到他们，那么默认的信息会被包含到退回的邮件内。

dot-qmail processing
所有的虚拟邮件域在~vpopmail/domains下拥有自己的目录。Qmail的 user/assign文件有每一个域的入口，并且把qmail-local投递程序指向这个目录。因此，所有的普通的 . qmail文件在每个虚拟域内工作。 .qmail文件只需要用户名来工作，譬如，对于.qmail文件运行，. qmail-joe 对应用户joe.Ezmlm使用，所以它可以运行在vpopmail下。

如果没有用户匹配到一个.qmail 文件，那么 .qmail-default文件将被使用。这个文件包含vdelivermail程序。这个程序读数据库中的认证信息(mysql 或者 vpasswd.cdb)然后把邮件投递到这个用户的目录。vdelibermal程序的最后一个参数可以是一个vpopmail /vchkpw拥有的邮件目录，所以所有的默认的邮件接收都在那里结束。或者，这个参数也可以是一个邮件地址，那么所有的默认的邮件将会转发到这个地址。最后，vdelivermail的这个最后面的参数可以是邮箱不存在的信息，这将会把所有没有找到匹配用户的邮件退会给发送者。

qmailadmin
qmailadmin提供一个web界面来管理vpopmail邮件域。从版本0.26开始，qmailadmin使用vpopmail的api。这意味着它可以管理mysql或者vpasswd.cdb认证。它允许增加pop用户，管理转发和别名，ezmlm邮件列表和自动回复。

sqwebmail
sqwebmail是一个web界面的邮件客户端。它直接读写用户的邮件目录。它可以和vpopmail vpasswd文件配合工作。我们有一个0.24版本的修订版 在 http://www.inter7.com/vpopmail上，它使用的是vpopmail的api。同时,它也支持设置用户的密码和允许用户转发他们的邮件。希望这些改变会集成到标准的发行版本中。

courier-imap
courier-imap是一个支持Maildirs 格式的IMAP服务器。它的最近的发行版本支持vpopmail的vpasswd文件。我们将会集成vpopmail的api到主要的发行版本中去。

mysql authentication

cdb authentication

vpopmail API
从版本3.4.10开始，vpopmail建立了一个libvpopmail.a库，在~vpopmail/lib/下。连接这个库到你的应用程序将提供到下面的C函数的方法。相关的 header文件在~vpopmail/include下。

int vadddomain(char *domain)

domain=the new virtual domain
# 新的虚拟邮件域；

int vdeldomain(char *domain)

domain=virtual domain to delete
#删除的虚拟邮件域；

int vadduser(char *user,char *domain ,char *password , int apop)
user=new user name
#新建的用户名；
domain=virtual domain
#新建用户的虚拟邮件域
password=clear text password
#明文密码
apop=0 for pop and 1 for apop
#数字0 指定pop , 1 指定apop
int vdeluser(char *user, char *domain)

user=user to delete
#删除的用户
domain=virtual domain
#删除用户的虚拟邮件域

int vpasswd(char *user, char *domain, char *password)
user=user to change password for
#需要修改密码的用户名
domain=virtual domain
#修改密码用户所在的虚拟邮件域
password=clear text password
#明文密码

int vsetuserquota(char *user, char *domain, char *quota)
user=user name to change quota for
#修改用户磁盘配额的用户名
domain=virtual domain
#需要修改磁盘配额的用户所在虚拟邮件域
char=quota in bytes. M/m and K/k abbrieviations apply. 5M 5m and 500000 all equal 5 million bytes hard quota

#字节为单位的磁盘配额，5M 5m 以及500000全部等同于5百万字节的硬配额
vpopmail authentication API

int vauth_addomain(char *domain)
domain=domain name to add to authentication system
#添加到认证系统的域名

int vauth_deldomain(char *domain)
domain=domain name to delete from authentication system
#从认证系统删除的域名

int vauth_adduser(char *user, char *domain, char *crypted_password, char *dir, int apop)
user=user to add from authentication system
#增加到认证系统的用户
domain=domain name
#域名
crypted_password=encrypted password
#加密密码
dir=full path to directory where users Maildir is stored
#Maildir存储的全路径
apop=0 for POP and 1 for APOP
#数字0指定POP ,1 指定 APOP
int vauth_deluser(char *user, char *domain)
user=user to delete from authentication system
#从认证系统删除的用户名
domain=domain name
#域名

int vauth_password(char *user, char *domain, char *crypted_password)
user=user to change password in authentication system
#在认证系统中更改密码的用户
domain=domain name
#域名
crypted_password=the encrypted password
#加密密码

int vauth_setquota(char *user, char *domain, char *quota)
user=user to set quota for in authentication system
#在认证系统中设置配额的用户
domain=domain name
#域名
quota=空间配额，字节，或者使用 M/m K/k 衡量。5M=5m=5000000

struct *passwd vauth_getpw(char *user, char *domain)
user=user name to retrieve password entry from authentication system
#需要从认证系统中重新获得密码的用户名
domain=domain name
#域名

int vauth_setpw(struct *passwd, char *domain)
passwd=pointer to a passwd structure to store in authentication system . 
#指向一个密码结构来存储在认证系统
domain=domain name for this passwd structure
#这个密码结构的域名

struct *vauth_user(char *user, char *domain, char *password, char *apop)
user=user name to authenticate
#认证的用户名
domain=domain name
#域名
password=clear text password
#明文密码
apop=not used in version 3.4.10
#apop不在3.4.10版本中使用

struct *vauth_getall(char *domain, int first, int sort_it)
domain=domain name to retrieve password structure from authentication system
#需要从认证系统中重新获得密码结构的域名
first=1 to get first record, 0 = get next record
#数字1指定提取第一个纪录，0指定提取下一个记录

sort_it=1 to have the user list sorted alphabetically . This has no effect on vpasswd/cdb 
method, since all users are added alphabetically. With mysql it adds an order by pw_name to 
the query.
#数字1指定按照字母顺序排列用户列表。由于所有的用户是按照字母顺序添加的，所以，这个对vpasswd/cdb无效。
而mysql增加的顺序由pw_name决定。