XMail - Internet/Intranet mail server.
[top]
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation (http://www.gnu.org); either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
you should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
[top]
XMail is an Internet and Intranet mail server featuring an SMTP server, POP3 server, finger server, multiple domains, no need for users to have a real system account, SMTP relay checking, RBL/RSS/ORBS/DUL and custom (IP based and address based) spam protection, SMTP authentication (PLAIN LOGIN CRAM-MD5 POP3-before-SMTP and custom), a POP3 account synchronizer with external POP3 accounts, account aliases, domain aliases, custom mail processing, direct mail files delivery, custom mail filters, mailing lists, remote administration, custom mail exchangers, logging, and multi-platform code.
XMail sources compile under GNU/Linux, FreeBSD, OpenBSD, NetBSD, OSX, Solaris and NT/2K.
This server born due to the need of having a free and stable Mail Server to be used inside my old company, which used a Windows Network. I don't like to reinvent the wheel but the need of some special features drive me to start a new project. Probably if I could use a Linux server on my net, I would be able to satisfy my needs without write code, but this is not my case. It should be also portable to other OSs, like Linux and other Unixes.
Another reason that drove me to write XMail is the presence of the same steps in setting up a typical mail server, ie:
sendmail + qpopper + fetchmail
if one needs SMTP, POP3 and external synchronization, or:
sendmail + qpopper
for only SMTP and POP3 (I've quoted sendmail, qpopper and fetchmail, but there are many other packages you can use to reach these needs). With XMail you get an all-in-one package with a central administration that can simplify the above common steps.
The first code of XMail Server is started on Windows NT and Linux, and now, the FreeBSD and Solaris version ready. The compilers supported are gcc for Linux, FreeBSD, OpenBSD and Solaris and M$ Visual C++ for NT/2K.
[top]
1.21
Gnu Public License http://www.gnu.org
Jan 9, 2005
Davide Libenzi <davidel@xmailserver.org> http://www.xmailserver.org/
Michael Hartle <mhartle@hartle-klug.com>
Shawn Anderson <sanderson@eye-catcher.com>
Dick van der Kaaden <dick@netrex.nl>
Beau E, Cox <beau@beaucox.com>
************************************************************ * <<WARNING>> * * If you're upgrading an existing version of XMail it's * * strongly suggested that you read all the ChangeLog.txt * * notes that range from existing version to the new one. * ************************************************************
See the Change Log.
[top]
This document contains various examples of entries you must make to the XMail configuration tables. These examples are written in a
mono-spaced font like this.
The prototype statement is shown with explicit '[TAB]' and '[NEWLINE]' characters:
"aliasdomain"[TAB]"realdomain"[NEWLINE]
while examples omit these characters:
"simpson.org" "simpson.com" "*.homer.net" "homer.net"
'YOU MUST ALWAYS ENTER THE DATA EXACTLY AS SHOWN IN THE PROTOTYPE.'
When a protype or example statement is too long to easily be shown on the screen or printed, the line is split into multiple lines by showing '=>' at the end of continued lines and indenting the continuation line(s):
"domain"[TAB]"account"[TAB]"enc-passwd"[TAB]"account-id"[TAB]"account-dir"[TAB]=> "account-type"[NEWLINE]
'DO NOT ENTER THE => CHARACTERS. ENTER THE ENTIRE ENTRY AS ONE LINE.'
[top]
[top]
Right now the Linux and NT ports are stable, while the Solaris, FreeBSD and OpenBSD ones have not been tested as well as the previous OSs.
[top]
[top]
Always get the latest sources at the XMail home page http://www.xmailserver.org/ because otherwise you may be using an old version.
Use the correct distribution for your system and don't mix Unix files with Windows ones because this is one of the most common cause of XMail bad behavior.
When you unzip (or untar) the package you've to check that the MailRoot directory contained inside the package itself is complete (look at the directory tree listed below) because some unzippers don't restore empty directories.
[top]
For Windows, Visual C++ project files are supplied, while for *nixes, the following options are given:
[Linux]
# make -f Makefile.lnx
[FreeBSD]
# setenv OSTYPE FreeBSD # gmake -f Makefile.bsd
or (depending on the shell):
# OSTYPE=FreeBSD gmake -f Makefile.bsd
[OpenBSD]
# setenv OSTYPE OpenBSD # gmake -f Makefile.bsd
or (depending on the shell):
# OSTYPE=OpenBSD gmake -f Makefile.bsd
[NetBSD]
# setenv OSTYPE NetBSD # gmake -f Makefile.bsd
or (depending on the shell):
# OSTYPE=NetBSD gmake -f Makefile.bsd
[OSX]
# OSTYPE=Darwin make -f Makefile.bsd
or (depending on the shell):
# setenv OSTYPE Darwin # make -f Makefile.bsd
[Solaris]
# make -f Makefile.sso
Under Linux an init.d startup script is supplied (xmail) to allow you to run XMail as a standard rc? daemon. You must put it into /etc/init.d (it depends on which distro you're using) directory and then create K??xmail - S??xmail links into the proper directories.
Under Windows NT/2000/XP the XMail's executable is a Win32 service by default and if you want to have it built like a standard executable you've to comment the statement:
"#define SERVICE" in MainWin.cpp
When it's built as a service (default) you can run:
XMail --install
to install XMail as a manual startup service or:
XMail --install-auto
to install XMail as an automatic startup service.
If you run '--install' and you want XMail to run at NT boot, you must go in ControlPanel->Services and edit the startup options of XMail. Once you have the service version of XMail you can run it in a 'normal' way by executing:
XMail --debug [options]
[top]
[configuration] [top]
[configuration] [top]
Linux/etc.:
export MAIL_ROOT=/var/XMailRoot
Windows:
set MAIL_ROOT=C:\MailRoot
[configuration] [top]
Mail root directory contain these files:
aliases.tab <file> aliasdomain.tab <file> domains.tab <file> dnsroots <file> extaliases.tab <file> mailusers.tab <file> message.id <file> pop3links.tab <file> server.tab <file> smtpgw.tab <file> smtpfwd.tab <file> smtprelay.tab <file> smtpauth.tab <file> smtpextauth.tab <file> userdef.tab <file> ctrlaccounts.tab <file> spammers.tab <file> spam-address.tab <file> pop3.ipmap.tab <file> smtp.ipmap.tab <file> ctrl.ipmap.tab <file> finger.ipmap.tab <file> filters.in.tab <file> filters.out.tab <file> filters.pre-data.tab <file> filters.post-data.tab <file> smtp.ipprop.tab <file>
and these directories:
bin <dir>
cmdaliases <dir>
tabindex <dir>
dnscache <dir>
mx <dir>
ns <dir>
custdomains <dir>
filters <dir>
logs <dir>
pop3locks <dir>
pop3linklocks <dir>
pop3links <dir>
spool <dir>
local <dir>
temp <dir>
0 <dir>
0 <dir>
mess <dir>
rsnd <dir>
info <dir>
temp <dir>
slog <dir>
lock <dir>
cust <dir>
froz <dir>
...
...
userauth <dir>
pop3 <dir>
smtp <dir>
domains <dir>
and for each domain DOMAIN handled a directory (inside domains):
DOMAIN <dir>
userdef.tab <file>
mailproc.tab <file> [ optional ]
inside of which reside, for each account ACCOUNT:
ACCOUNT <dir>
user.tab <file>
mlusers.tab <file> [ mailing list case ]
mailproc.tab <file> [ optional ]
pop3.ipmap.tab <file> [ optional ]
and
mailbox <dir>
for mailbox structure, while:
Maildir <dir>
tmp <dir>
new <dir>
cur <dir>
for Maildir structure.
[configuration] [top]
TAB ('something.tab') files are text files (in the sense meant by the OS in use: <CR><LF> for NT and <CR> for Linux) with this format:
"value1"[TAB]"value2"[TAB]...[NEWLINE]
The following sections explain each file's structure and use.
[configuration] [top]
"domain"[TAB]"alias"[TAB]"realaccount"[NEWLINE]
Example:
"home.bogus" "davidel" "dlibenzi"
define 'davidel' as alias for 'dlibenzi' in 'home.bogus' domain.
"home.bogus" "foo*bog" "homer@internal-domain.org"
define an alias for all users whose name starts with 'foo' and ends with 'bog' that point to the locally handled account 'homer@internal-domain.org'.
"home.bogus" "??trips" "travels"
define an alias for all users whose names start with any two chars and end with 'trips'. You can have widcard even in the domain field, as:
"*" "postmaster" "postmaster@domain.net"
You 'CANNOT' edit this file while XMail is running because it is an indexed file.
[table index] [configuration] [top]
"aliasdomain"[TAB]"realdomain"[NEWLINE]
where 'aliasdomain' can use wildcards:
"simpson.org" "simpson.com" "*.homer.net" "homer.net"
The first line defines 'simpson.org' as an alias of 'simpson.com' while the second remaps all subdomains of 'homer.net' to 'homer.net'.
You 'CANNOT' edit this file while XMail is running because it is an indexed file.
[table index] [configuration] [top]
"domain"[NEWLINE]
defines domains handled by the server.
[table index] [configuration] [top]
host
This is a file that lists a root name server in each line (this is not a TAB file). This can be created from a query via nslookup for type=ns and host = '.'.
[table index] [configuration] [top]
"external-domain"[TAB]"external-account"[TAB]"local-domain"[TAB]"local-user"[NEWLINE]
Example:
"xmailserver.org" "dlibenzi" "home.bogus" "dlibenzi"
This file is used in configurations in which the server does not run directly on Internet (like my case) but acts as internal mail exchanger and external mail gateway. This file defines 'Return-Path: <...>' mapping for internal mail delivery. If you are using a Mail client like Outlook, Eudora, KMail ... you have to configure your email address with the external account say 'dlibenzi@xmailserver.org'. When you post an internal message to 'foo@home.bogus' the mail client puts your external email address ('dlibenzi@xmailserver.org') in the 'MAIL FROM: <...>' SMTP request. Now if the user 'foo' replies to this message, it replies to 'dlibenzi@xmailserver.org', and then is sent to the external mail server. With the entry above in 'EXTALIASES.TAB' file the 'Return-Path: <...>' field is filled with 'dlibenzi@home.bogus' that leads to an internal mail reply.
You 'CANNOT' edit this file while XMail is running because it is an indexed file.
[table index] [configuration] [top]
"domain"[TAB]"account"[TAB]"enc-passwd"[TAB]"account-id"[TAB]"account-dir"[TAB]=> "account-type"[NEWLINE]
(remember, enter as one line.) Example:
"home.bogus" "dlibenzi" "XYZ..." 1 "dlibenzi" "U"
defines an account 'dlibenzi' in domain 'home.bogus' with the encrypted password 'XYZ...', user id '1' and mail directory 'dlibenzi' inside '$MAIL_ROOT/domains/home.bogus'. To allow multiple domain handling the POP3 client must use the entire email address for the POP3 user account; for example. if a user has email user@domain it must supply:
user@domain
as POP3 account login.
The directory 'account-dir' 'must' case match with the field 'account-dir' of this file. Note that user id 'must' be unique for all users (duplicate user ids are not allowed). The user id 0 is reserved by XMail and cannot be used.
The last field 'U' is the account type:
"U" = User account "M" = Mailing list account
The encrypted password is generated by 'XMCrypt' whose source is 'XMCrypt.cpp'. Even if external authentication is used (see External Authentication) this file 'must' contain an entry for each user handled by XMail.
You 'CANNOT' edit this file while XMail is running because it is an indexed file.
[table index] [configuration] [top]
A file storing a sequential message number. Set it at 1 when you install the server and leave it be handled by the software.
[table index] [configuration] [top]
"local-domain"[TAB]"local-account"[TAB]"external-domain"[TAB]=> "external-account"[TAB]"external-crypted-password"[TAB]"authtype"[NEWLINE]
(remember, enter as one line) where:
'authtype' = authentication method ('CLR' = USER/PASS auth, 'APOP' = APOP auth).
Examples;
"home.bogus" "dlibenzi" "xmailserver.org" "dlibenzi" "XYZ..."=> "APOP"
This entry is used to synchronize the external account 'dlibenzi@xmailserver.org' with encrypted password 'XYZ...' with the local account 'dlibenzi@home.bogus' using 'APOP' authentication. It connect with the 'xmailserver.org' POP3 server and download all messages for 'dlibenzi@xmailserver.org' into the local account 'dlibenzi@home.bogus'. The remote server must support 'APOP' authentication to specify 'APOP' as authtype. Even if using APOP authentication is more secure because clear usernames and password does not travel on the network, if you're not sure about it, specify 'CLR' as authtype. For non local POP3 sync you've to specify a line like this one (@ as the first domain char):
"@home.bogus.com" "dlibenzi" "xmailserver.org:110" "dlibenzi" "XYZ..."=> "CLR"
This entry is used to synchronize the external account 'dlibenzi@xmailserver.org' with encrypted password 'XYZ...' with the account 'dlibenzi@home.bogus.com' using 'CLR' authentication. The message is pushed into the spool having as destination dlibenzi@home.bogus.com , so you've to have some kind of processing for that user or domain in your XMail configuration (for example custom domain processing). you can also have the option to setup a line like this one:
"?home.bogus.com,felins.net,pets.org" "dlibenzi" "xmailserver.org"=> "dlibenzi" "XYZ..." "CLR"
and messages are dropped inside the spool by following these rules:
Obviously the masquerade domain ('home.bogus.com') MUST be handled by the server or MUST be a valid external mail domain. So if a message having as To: address graycat@felins.net is fetched by the previous line a message is pushed into the spool with address graycat@home.bogus.com. Particular attention is to be taken about at not creating mail loops. Another option is:
"&.local,felins.net,pets.org" "dlibenzi" "xmailserver.org" "dlibenzi"=> "XYZ..." "CLR"
where a fetched message whose To: address is graycat@felins.net is replaced with graycat@felins.net.local. You can avoid the matching domain list after the masquerading domain but, in that case, you may have bad destination addresses inside the spool. The list MUST be comma separated WITHOUT spaces. XMail starts PSYNC session with a delay that you can specify with the -Yi nsec command line parameter (default 120). XMail also checks for the presence (inside MAIL_ROOT) of a file named '.psync-trigger' and, when this file is found, a PSYNC session starts and that file is removed.
[table index] [configuration] [top]
"varname"[TAB]"varvalue"[NEWLINE]
This file contains server configuration variables. See SERVER.TAB variables below for details.
[table index] [configuration] [top]
"domain"[TAB]"smtp-gateway"[NEWLINE]
Examples:
"foo.example.com" "@xmailserver.org"
sends all mail for 'foo.example.com' through the 'xmailserver.org' SMTP server, while:
"*.dummy.net" "@relay.xmailserver.org"
sends all mail for ``*'*.dummy.net' through 'relay.xmailserver.org'.
The 'smtp-gateway' can be a complex routing also, for example:
"*.dummy.net" "@relay.xmailserver.org,@mail.nowhere.org"
sends all mail for ``*'*.dummy.net' through '@relay.xmailserver.org,@mail.nowhere.org', in this way: relay.xmailserver.org --> mail.nowhere.org --> @DESTINATION.
[table index] [configuration] [top]
"domain"[TAB]"smtp-mx-list"[NEWLINE]
Examples:
"foo.example.com" "mail.xmailserver.org:7001,192.168.1.1:6123,mx.xmailserver.org"
sends all mail for 'foo.example.com' using the provided list of mail exchangers, while:
"*.dummy.net" "mail.xmailserver.org,192.168.1.1,mx.xmailserver.org:6423"
sends all mail for ``*'*.dummy.net' through the provided list of mail exchangers. If the port (:nn) is not specified the default SMTP port (25) is assumed. you can also enable XMail to random-select the order of the gateway list by specifying:
"*.dummy.net" "#mail.xmailserver.org,192.168.1.1,mx.xmailserver.org:6423"
using the character '#' as the first char of the gateway list.
[table index] [configuration] [top]
"ipaddr"[TAB]"netmask"[NEWLINE]
Example:
"212.131.173.0" "255.255.255.0"
allows all hosts of the class 'C' network '212.131.173.XXX' to use the server as relay.
[table index] [configuration] [top]
"username"[TAB]"password"[TAB]"permissions"[NEWLINE]
is used to permit SMTP clients authentication with protocols PLAIN, LOGIN, CRAM-MD5 and custom. With custom authentication a file containing all secrets (username + ':' + password) is passed as parameter to the custom authentication program which tests all secrets to find the one matching (if exist). For this reason it's better to keep the number of entries in this file as low as possible. Permissions are a string that can contain:
When PLAIN, LOGIN or CRAM-MD5 authentication mode are used, first a lookup in 'MAILUSERS.TAB' accounts is performed to avoid duplicating information with 'SMTPAUTH.TAB'. Therefore when using these authentication modes a user must use as username the full email address (the : separator is permitted instead of @) and as password his POP3 password. If the lookup succeed the 'SERVER.TAB' variable 'DefaultSmtpPerms' is used to assign user SMTP permissions (default MR). If the lookup fails then 'SMTPAUTH.TAB' lookup is done.
[table index] [configuration] [top]
Besides internal SMTP authentication methods a user (XMail administrator) can define custom authentication procedures by setting up this file properly. The section SMTP Client Authentication explains the client part of custom authentication when we put an 'external' line inside the configuration file. The file 'SMTPEXTAUTH.TAB' is the server part of the custom authentication which has the given format:
"auth-name"[TAB]"base-challenge"[TAB]"program-path"[TAB]"arg-or-macro"...[NEWLINE]
This file can contain multiple lines whose 'auth-name' are listed during the EHLO command response. Where 'arg-or-macro' can be:
Example:
"RSA-AUTH" "foochallenge" "/usr/bin/myrsa-authenticate"=> "-c" "@@CHALL" "-f" "@@FSECRT" "-d" "@@DGEST"
The external program must test all lines of '@@FSECRT' to find the one (if it exists) that matches the client digest (@@DGEST). If it finds a match, it must return zero and overwrite '@@FSECRT' with the matching secret (username + ':' + password). If a match is not found, the program must return a value other than zero.
[table index] [configuration] [top]
"varname"[TAB]"varvalue"[NEWLINE]
Example:
"RealName" "??" "HomePage" "??" "Address" "??" "Telephone" "??" "MaxMBSize" "10000"
contains user default values for new users that are not set during the new account creation. This file is looked up in two different places, first in '$MAIL_ROOT/domains/DOMAIN' then in '$MAIL_ROOT', where 'DOMAIN' is the name of the domain where We're going to create the new user.
For each 'domain' handled by the server we'll create a directory 'domain' inside $MAIL_ROOT. Inside $MAIL_ROOT/'domain' reside 'domain'->'account' directories ($MAIL_ROOT/'domain'/'account'). This folder contains a sub folder named 'mailbox' (or 'Maildir/(tmp,new,cur)') that stores all 'account' messages. It also contains a file named 'USER.TAB' that stores``account'' variabiles, example:
"RealName" "Davide Libenzi" "HomePage" "http://www.xmailserver.org/davide.html"; "MaxMBSize" "30000"
[table index] [configuration] [top]
"username"[TAB]"password"[NEWLINE]
This file contains the accounts that are enable to remote administer XMail. The password is encrypted with the 'XMCrypt' program supplied with the source distro.
'REMEMBER THAT THIS HOLDS ADMIN ACCOUNTS, SO PLEASE CHOOSE COMPLEX USERNAMES AND PASSWORDS AND USE CTRL.IPMAP.TAB TO RESTRICT IP ACCESS! REMEMBER TO REMOVE THE EXAMPLE ACCOUNT FROM THIS FILE!'
[table index] [configuration] [top]
"ipaddr"[TAB]"netmask"[NEWLINE]
or:
"ipaddr"[TAB]"netmask"[TAB]"params"[NEWLINE]
or:
"ipaddr/bits"[NEWLINE]
or:
"ipaddr/bits"[TAB]"params"[NEWLINE]
Example:
"212.131.173.0" "255.255.255.0" "212.131.173.0/24"
register all hosts of the class 'C' network '212.131.173.XXX' as spammers, and block them the use of XMail SMTP server. If a match is found on one of those records, XMail will reject the incoming SMTP connection at early stages. It is possible to specify optional parameters to tell XMail which behaviour it should assume in case of match. An example of such setup is:
"212.131.173.0/24" "code=0"
In this case a code=0 tells XMail to flag the connection as possible spammer, but wait later SMTP session stages to reject the connection itself. In this case an authenticated SMTP session can override the SPAMMERS.TAB match. The optional ``params'' field lists parameters associated with the record, separated by a comma:
"param1=value1,param2=value2,...,paramN=valueN"
Currently supported parameters are:
[table index] [configuration] [top]
"spam-address"[NEWLINE]
Example:
"*@rude.net" "*-admin@even.more.rude.net"
blocks mails coming from the entire domain 'rude.net' and coming from all addresses that end with '-admin@'even.more.rude.net.
[table index] [configuration] [top]
"ipaddr"[TAB]"netmask"[TAB]"permission"[TAB]"precedence"[NEWLINE]
This file controls the global IP access permission to the POP3 server if located in the MAIL_ROOT path, and user IP access to its POP3 mailbox if located inside the user directory.
Example:
"0.0.0.0" "0.0.0.0" "DENY" "1" "212.131.173.0" "255.255.255.0" "ALLOW" "2"
This configuration denies access to all IPs except the ones of the class 'C' network '212.131.173.XXX'.
Higher precedences win over lower ones.
[table index] [configuration] [top]
"ipaddr"[TAB]"netmask"[TAB]"permission"[TAB]"precedence"[NEWLINE]
This file controls IP access permission to SMTP server.
Example:
"0.0.0.0" "0.0.0.0" "DENY" "1" "212.131.173.0" "255.255.255.0" "ALLOW" "2"
This configuration denies access to all IPs except the ones of the class 'C' network '212.131.173.XXX'.
Higher precedences win over lower ones.
[table index] [configuration] [top]
"ipaddr"[TAB]"netmask"[TAB]"permission"[TAB]"precedence"[NEWLINE]
This file control IP access permission to CTRL server. Example:
"0.0.0.0" "0.0.0.0" "DENY" "1" "212.131.173.0" "255.255.255.0" "ALLOW" "2"
This configuration deny access to all IPs except the ones of the class 'C' network '212.131.173.XXX'. Higher precedences win over lower ones.
[table index] [configuration] [top]
"ipaddr"[TAB]"netmask"[TAB]"permission"[TAB]"precedence"[NEWLINE]
This file controls IP access permission to FINGER server. Example:
"0.0.0.0" "0.0.0.0" "DENY" "1" "212.131.173.0" "255.255.255.0" "ALLOW" "2"
This configuration denies access to all IPs except the ones of the class 'C' network '212.131.173.XXX'. Higher precedences win over lower ones.
[table index] [configuration] [top]
"variable"[TAB]"value"[NEWLINE]
store user information such as:
"RealName" "Davide Libenzi" "HomePage" "http://www.xmailserver.org/davide.html"; "MaxMBSize" "30000" "ClosedML" "0"
Please refer to USER.TAB variables below.
[table index] [configuration] [top]
If the user is a mailing list this file must exist inside the user account subdirectory and contain a list of users subscribed to this list. The file format is:
"user"[TAB]"perms"[NEWLINE]
where:
Example:
"davidel@xmailserver.org" "RW" "ghostuser@nightmare.net" "R" "meawmeaw@kitty.cat" "RA"
If the 'USER.TAB' file defines the 'ClosedML' variable as '1' then a client can post to this mailing list only if it's listed in 'MLUSERS.TAB' with RW permissions.
[table index] [configuration] [top]
"command"[TAB]"arg-or-macro"[TAB]...[NEWLINE]
stores commands (internals or externals) that have to be executed on a message file. The presence of this file is optional ans if it does not exist the default processing is to store the message in user mailbox. The 'MAILPROC.TAB' file can be either per user or per domain, depending where the file is stored. If stored inside the user directory it applies only to the user whose directory hosts the 'MAILPROC.TAB', while if stored inside the domain directory it applies to all users of such domain. Each argument can be a macro also:
Supported commands:
[EXTERNAL]
"external"[TAB]"priority"[TAB]"wait-timeout"[TAB]"command-path"[TAB]=> "arg-or-macro"[TAB]...[NEWLINE]
where:
Be carefull if using @@FILE to give the external command enough timeout to complete, otherwise the file will be removed by XMail while the command is processing. This is because such file is a temporary one that is deleted when XMail exits from 'MAILPROC.TAB' file processing. In case the external command exit code will be '16', the command processing will stop and all the following commands listed inside the file will be skipped.
[FILTER]
"filter"[TAB]"priority"[TAB]"wait-timeout"[TAB]"command-path"[TAB]=> "arg-or-macro"[TAB]...[NEWLINE]
where:
With filters, it is not suggested to use @@TMPFILE, since the filter will never have the ability to change the message content in that way. Also, to avoid problems very difficult to troubleshoot, it is suggested to give the filter 'ENOUGH' timeout to complete (90 seconds or more). See [MESSAGE FILTERS] for detailed information about return codes. In the filter command, the ``Stop Filter Processing'' return flag will make XMail to stop the execution of the current custom processing file.
The 'filter' command will pass the message file to a custom external filter, that after inspecting it, has the option to accept, reject or modify it. Care should be taken to properly re-format the message after changing it, to avoid message corruption. The 'filter' command 'CANNOT' successfully change the private XMail's header part of the spool message.
[MAILBOX]
"mailbox"[NEWLINE]
With this command the message is pushed into local user mailbox.
[REDIRECT]
"redirect"[TAB]"domain-or-emailaddress"[TAB]...[NEWLINE]
Redirect message to internal or external domain or email address. If the message was for foo-user@custdomain.net and the file custdomain.net.tab contains a line:
"redirect" "target-domain.org"
the message is delivered to 'foo-user@target-domain.org'.
While the line:
"redirect" "user@target-domain.org"
redirects the message to user@target-domain.org.
[LREDIRECT]
"lredirect"[TAB]"domain-or-emailaddress"[TAB]...[NEWLINE]
Redirect the message to internal or external domain (or email address) impersonating local domain during messages delivery. If the message was for foo-user@custdomain.net and the file custdomain.net.tab contains a line:
"redirect" "target-domain.org"
the message is delivered to 'foo-user@target-domain.org'.
While the line:
"redirect" "user@target-domain.org"
redirects the message to 'user@target-domain.org'. The difference between ``redirect'' and ``lredirect'' is the following. Suppose A@B sends a message to C@D, that has a redirect to E@F. With ``redirect'' E@F will see A@B has sender while with ``lredirect'' he will see C@D.
[SMTPRELAY]
"smtprelay"[TAB]"server[:port],server[:port],..."[NEWLINE]
Send mail to the specified SMTP server list by trying the first, if fails the second and so on. Otherwise You can use this syntax:
"smtprelay"[TAB]"#server[:port],server[:port],..."[NEWLINE]
to have XMail random-select the order the specified relays.
[table index] [configuration] [top]
"ip-addr"[TAB]"var0=value0"...[TAB]"varN=valueN"[NEWLINE]
Example:
"192.168.0.7/32" "WhiteList=1"
Address selection mask are formed by an IP address (network) plus the number of valid bits inside the network mask. No space are allowed between the variable name and the '=' sign and between the '=' sign and the value. These are the currently defined variables:
[table index] [configuration] [top]
See [MESSAGE FILTERS]
[table index] [configuration] [top]
See [MESSAGE FILTERS]
[table index] [configuration] [top]
See [SMTP MESSAGE FILTERS]
[table index] [configuration] [top]
See [SMTP MESSAGE FILTERS]
[table index] [configuration] [top]
You can use external modules (executables) to perform user authentication instead of using XMail 'mailusers.tab' lookups. Inside the userauth directory you'll find one directory for each service whose authentication can be handled externally (for now only POP3). Suppose We must authenticate 'USERNAME' inside 'DOMAIN', XMail first tries to lookup (inside userauth/pop3) a file named:
'DOMAIN.tab'
else:
'.tab'
If one of these files is found, XMail authenticates 'USERNAME' - 'DOMAIN' using that file. The authentication file is a TAB file (see at the proper section in this document) which has the given structure:
"auth-action"[TAB]"command"[TAB]"arg-or-macro"[TAB]...[NEWLINE]
Each argument can be a macro also:
The values for 'auth-action' can be one of:
item userauth
executed when user authentication is required
The first line that stores the handling command for the requested action is executed as:
command arg0 ... argN
that must return zero if successful. Any other exit code is interpreted as authentication operation failure, that. in 'userauth' case, means such user is not authenticated.
If the execution of the command fails for system reasons (command not found, access denied, etc ...) then the user is not authenticated.
If none of this file's id are found, then usual authentication is performed ('mailusers.tab'). The use of external authentication does not avoid the presence of the user entry in 'mailusers.tab'.
[top]
When a message is to be sent through an SMTP server that requires authentication, XMail provides a way to handle this task by if the 'userauth/smtp' subdirectory is set up properly.
Suppose a mail is to be sent through the SMTP server 'mail.foo.net', this makes XMail to search for a file named (inside userauth/smtp):
'mail.foo.net.tab'
then:
'foo.net.tab'
then:
'net.tab'
If one of these files is found its content is used to authenticate the SMTP client session. The structure of this file, as the extension says, is the TAB one used for most of the configuration files inside XMail. Only the first valid line (uncommented #) is used to choose the authentication method and lines has this format:
"auth-type"[TAB]"param1"...[TAB]"paramN"[NEWLINE]
Valid lines are:
"plain" "username" "password"
or
"login" "username" "password"
or
"cram-md5" "username" "password"
or
"external" "auth-name" "secret" "prog-path" "arg-or-macro" ...
Where 'auth-name' can be any symbolic name and 'arg-or-macro' can be a program argument or one of these macros:
For example:
"external" "RSA-AUTH" "mysecret" "/usr/bin/myrsa-auth" "-c" "@@CHALL" "-s"=> "@@SECRT" "-f" "@@RFILE"
XMail sends a line like:
AUTH RSA-AUTH
to the SMTP server, and wait for a line like:
3?? base64-challenge
Then XMail decodes 'base64-challenge' and invokes the external program to get the response to send to the SMTP server. The external program must return zero upon success and must put the response into the file @@RFILE (without new line termination).
[top]
If a message that has as target domain of 'sub1.sub2.domain.net' arrives at the XMail server, 'AND' XMail does not have a real domain 'sub1.sub2.domain.net' inside its domain list, XMail decides if this domain gets a custom domain processing by trying to lookup:
sub1.sub2.domain.net.tab .sub2.domain.net.tab .domain.net.tab .net.tab .tab
inside the 'custdomains' directory.
If one of these files is found the incoming mail gets custom domain processing by executing commands that are stored in such a file.
The format is:
"command"[TAB]"arg-or-macro"[TAB]...[NEWLINE]
These tables store commands (internals or externals) that have to be executed on the message file. The presence of one of these files is optional and if none exist the default processing is applied to the message via SMTP.
Each argument can be a macro also:
Supported commands:
"external"[TAB]"priority"[TAB]"wait-timeout"[TAB]"command-path"[TAB]=> "arg-or-macro"[TAB]...[NEWLINE]
where:
Be carefull if using @@FILE to give the external command enough timeout to complete, otherwise the file will be removed by XMail while the command is processing. This is because such file is a temporary one that is deleted when XMail exits from file processing. In case the external command exit code will be '16', the command processing will stop and all the following commands listed inside the file will be skipped.
"filter"[TAB]"priority"[TAB]"wait-timeout"[TAB]"command-path"[TAB]=> "arg-or-macro"[TAB]...[NEWLINE]
where:
With filters, it is not suggested to use @@TMPFILE, since the filter will never have the ability to change the message content in that way. Also, to avoid problems very difficult to troubleshoot, it is suggested to give the filter 'ENOUGH' timeout to complete (90 seconds or more). See [MESSAGE FILTERS] for detailed information about return codes. In the filter command, the ``Stop Filter Processing'' return flag will make XMail to stop the execution of the current custom processing file.
The 'filter' command will pass the message file to a custom external filter, that after inspecting it, has the option to accept, reject or modify it. Care should be taken to properly re-format the message after changing it, to avoid message corruption. The 'filter' command 'CANNOT' successfully change the private XMail's header part of the spool message.
"redirect"[TAB]"domain-or-emailaddress"[TAB]...[NEWLINE]
Redirect message to internal or external domain or email address. If the message was for foo-user@custdomain.net and the file custdomain.net.tab contains a line:
"redirect" "target-domain.org"
the message is delivered to 'foo-user@target-domain.org'.
While the line:
"redirect" "user@target-domain.org"
redirects the message to user@target-domain.org.
"lredirect"[TAB]"domain-or-emailaddress"[TAB]...[NEWLINE]
Redirect the message to internal or external domain (or email address) impersonating local domain during messages delivery. If the message was for foo-user@custdomain.net and the file custdomain.net.tab contains a line:
"redirect" "target-domain.org"
the message is delivered to 'foo-user@target-domain.org'.
While the line:
"redirect" "user@target-domain.org"
redirects the message to 'user@target-domain.org'. The difference between ``redirect'' and ``lredirect'' is the following. Suppose A@B sends a message to C@D, that has a redirect to E@F. With ``redirect'' E@F will see A@B has sender while with ``lredirect'' he will see C@D.
"smtprelay"[TAB]"server[:port],server[:port],..."[NEWLINE]
Send mail to the specified SMTP server list by trying the first, if that fails, the second and so on.
Otherwise you can use this syntax:
"smtprelay"[TAB]"#server[:port],server[:port],..."[NEWLINE]
To have XMail random-select the order the specified relays.
"smtp"[NEWLINE]
Do SMTP delivery.
[top]
CmdAliases implement aliases that are handled only through commands and can be thought of as a user level implementation of custom domain processing commands. The command set is the same of the one that is described above (Custom domain mail processing) and won't be explained again here.
For every handled domain (listed inside 'domains.tab') a directory with the same domain name is created inside the 'cmdaliases' subdirectory. This directory is automatically created and removed when you add/remove domains through the CTRL protocol (or 'CtrlClnt').
When a mail for 'USER@DOMAIN' is received by the server, the domain 'DOMAIN' is to be handled locally, and the standard users/aliases lookup fails, a file named 'USER.tab' is searched inside '$MAIL_ROOT/cmdaliases/DOMAIN'. If such file is found, commands listed inside the file (whose format must follow the one described in the previous section) are executed by the server as a matter of mail message processing. An important thing to remember is that all domain and user names, when applied to the file system, must be lower case.
The use of the command '[SMTP]' must be implemented with great care because it could create mail loops within the server.
[top]
The following variables are for use int the SERVER.TAB configuration file.
"1,4,9"
Default is empty which means no notification is sent upon a delivery attempt failure.
"+X-Deliver-To,To,Cc"
Tags preceded by a '+' character make XMail stop scanning when an address is found inside the header tag.
Tags preceded by a '+' character must be listed before other tags.
The string ``+X-Deliver-To,To,Cc'' is the default if nothing is specified.
"Please open http://www.xmailserver.test/smtp_errors.html to get=>
more information about this error"
Please be aware the RFC821 fix the maximum reply line length to 512 bytes.
maps-root:code,maps-root:code...
Where maps-root is the root for the dns query (ie. dialups.mail-abuse.org.) and the code can be:
SMTP authentication overrides the denial set by this option by giving authenticated users the ability to access the server from 'mapped' IPs.
dns.home.bogus.net:tcp,192.168.1.1:udp,...
The string has the format:
server,port,HTTP-GET-String[,username,password]
For Example:
members.dyndns.org,80,/nic/dyndns?action=edit&started=1&hostname=YES&host_id=yourhost.ourdomain.ext&myip=%s&wildcard=OFF&mx=mail.exchanger.ext&backmx=NO,foouser,foopasswd
or
www.dns4ever.com,80,/sys/u.cgi?d=DOMAIN&u=USERNAME&p=PASSWORD&i=%s
where:
The %s in HTTP-GET-String is replaced with the IP address to register.
[top]
This feature offers a way to filter messages by providing the ability to execute external programs, such as scripts or real executables. These 'filters' may examine and/or modify messages and inform XMail of their actions with a return value.
This feature offers the ability to inspect and modify messages, giving a way to reject messages based on content, alter messages (address rewriting) and so on.
If this filters returns '4, 5 or 6' the message is rejected and is stopped in its travel. If the filter modifies the message it must return '7'.
Additional flags are allowed to be returned to XMail as a result of filter processing by adding the flags value to the exits code above listed. The currently defined flags are :
Filter flags are additive and if more than one flag need to be specified, their values must be added together. If a filter ``raw'' exit code is RC and the filter needs to return extra flags FILTER-SUM, the final return code FRC must be :
FRC = RC + FILTER-SUM
Example. Suppose a filter modified the message and hence needs to return 7 as return code. Suppose also that a filter wants to block the filter selection list processing by specifying a flags value of 16, the value to be returned will be :
FRC = 7 + 16 = 23
Filter selection is driven by two files 'FILTERS.IN.TAB' and 'FILTERS.OUT.TAB' located inside the $MAIL_ROOT/ directory and that have the following format:
"sender"[TAB]"recipient"[TAB]"remote-addr"[TAB]"local-addr"[TAB]"filename"[NEWLINE]
For example:
"*@bad-domain.com" "*" "0.0.0.0/0" "0.0.0.0/0" "av-filter.tab" "*" "clean@purified.net" "0.0.0.0/0" "0.0.0.0/0" "spam-block.tab" "*" "*" "192.168.1.0/24" "0.0.0.0/0" "archive.tab"
where the file ``av-filter.tab'' must be present inside the $MAIL_ROOT/filters directory. The ``sender'' and the ``recipient'' are resolved to the real account when possible. Address selection mask are formed by an IP address (network) plus the number of valid bits inside the network mask. The file 'FILTERS.IN.TAB' lists filters that have to be applied to inbound messages (going to local mailboxes) while the file 'FILTERS.OUT.TAB' lists filters that have to be applied to outbound messages (delivered remotely). All four (sender+recipient+remote-addr+local-addr) selection fields must have a match in order ``filename'' to be evaluated. The syntax of the filter file is:
"command"[TAB]"arg-or-macro"[TAB]...[NEWLINE]
or:
"!flags"[TAB]"command"[TAB]"arg-or-macro"[TAB]...[NEWLINE]
Each file may contain multiple commands, that will be executed in strictly sequential order. The first command that will trigger a rejection code will make the filtering process to end. The 'flags' parameter is a comma-separated list of flags that drives the filter execution. The syntax of each flag is either FLAG or FLAG=VAL. Currently supported flags are:
Each argument can be a macro also:
Here 'command' is the name of an external program that processes the message and returns its processing result. If it returns '6' the message is rejected and a notification message is sent to the sender. By returning '5' the message is rejected without notification. While returning '4' the message is rejected without notification and without being frozen (a '5' response could lead to a frozen message if the SERVER.TAB configuration enables this). If all filters return values different from '6, 5 and 4' the message continues its trip. The filter command may also modify the file (AV scanning, content filter, message rewriting, etc) by returning '7'. The filter 'MUST' return '7' in case it modifies the message. If the filter changes the message file it 'MUST' keep the message structure and it 'MUST' terminate all line with <CR><LF>. The filter has also the ability to return a one-line custom return message by creating a file named @@FILE.rej holding the message in the very first line. This file should be created 'ONLY' when the filter returns a rejection code ('6, 5 and 4')and 'NEVER' in case of passthru code ('7') or modify code.
The spool files has this structure:
Info Data [ 1th line ] SmtpDomain [ 2nd line ] SmtpMessageID [ 3rd line ] MAIL FROM:<...> [ 4th line ] RCPT TO:<...> [ 5th line ] <<MAIL-DATA>> [ 6th line ] ...
After the '<<MAIL-DATA>>' tag (5th line) the message follows. The message is composed of a headers section and, after the first empty line, the message body. The format of the ``Info Data'' line is:
ClientDomain;ClientIP;ClientPort;ServerDomain;ServerIP;ServerPort;Time;Logo
'EXTREME' care must be used when modifying the message because the filter will be working on the real message, and a badly reformatted file will lead to message loss. The spool file header (any data before <<MAIL-DATA>>) 'MUST' be preserved as is by the filter in case of message rewrite happens.
[top]
Besides having the ability to perform off-line message filtering, XMail gives the user the power to run filters during the SMTP session. Two files drive the SMTP on-line filtering, and these are 'FILTERS.PRE-DATA.TAB' and 'FILTERS.POST-DATA.TAB'. The file 'FILTERS.PRE-DATA.TAB' contains one or more commands to be executed after the remote SMTP client sends the DATA command, and before XMail sends the response to the command. Using such filters, the user can tell XMail if or if not accept the following DATA transaction and, in case of rejection, the user is also allowed to specify a custom message to be sent to the remote SMTP client. The file 'FILTERS.POST-DATA.TAB' contains one or more commands to be executed after XMail received the whole client DATA, and before XMail sends the final response to the DATA command (final messages ack). The files 'FILTERS.PRE-DATA.TAB' and 'FILTERS.POST-DATA.TAB' conatins zero or more lines with the following format:
"command"[TAB]"arg-or-macro"[TAB]...[NEWLINE]
or:
"!flags"[TAB]"command"[TAB]"arg-or-macro"[TAB]...[NEWLINE]
Each file may contain multiple commands, that will be executed in strictly sequential order. The first command that will trigger a rejection code will make the filtering process to end. The 'flags' parameter is a comma-separated list of flags that drives the filter execution. The syntax of each flag is either FLAG or FLAG=VAL. Currently supported flags are:
Each argument can be a macro also:
Filter commands have the ability to inspect and modify the content of the message (or info) file. The exit code of commands executed by XMail are used to tell XMail the action that has to be performed as a cosequence of the filter. The exit code is composed by a raw exit code and additional flags. Currently defined flags are:
Currently defined raw exit codes are:
Any other exit codes will make XMail to accept the message, and can be used also when changing the content of the @@FILE file. 'EXTREME' care must be used when changing the @@FILE file, since XMail expect the file format to be correct. Also, it is important to preserve the <CR><LF> line termination of the file itself. When rejecting the message, the filter command has the ability to specify the SMTP status code that XMail will send to the remote SMTP client, by creating a file named @@FILE.rej containing the message in the very first line. Such file will be automatically removed by XMail. The data passed to filter commands inside @@FILE varies depending if the command is listed inside 'FILTERS.PRE-DATA.TAB' or inside 'FILTERS.POST-DATA.TAB'. Commands listed inside 'FILTERS.PRE-DATA.TAB' will receive the following data stored inside @@FILE:
Info Data [ 1th line ]
SmtpDomain [ 2nd line ]
SmtpMessageID [ 3rd line ]
MAIL FROM:<...> [ 4th line ]
RCPT TO:<...> {...} [ 5th line ]
...
The file can have one or more ``RCPT TO'' lines. The format of the ``Info Data'' line is:
ClientDomain;ClientIP;ClientPort;ServerDomain;ServerIP;ServerPort;Time;Logo
Commands listed inside 'FILTERS.POST-DATA.TAB' will receive the following data stored inside @@FILE:
Info Data [ 1th line ]
SmtpDomain [ 2nd line ]
SmtpMessageID [ 3rd line ]
MAIL FROM:<...> [ 4th line ]
RCPT TO:<...> {...} [ 5th line ]
...
<<MAIL-DATA>>
...
After the '<<MAIL-DATA>>' tag the message follows. The message is composed of a headers section and, after the first empty line, the message body. The format of the RCPT line is:
RCPT TO:<address> {ra=real-address}
where ``real-address'' is the ``address'' after it has been translated (if aliases applies) to the real local address. Otherwise it holds the same value of ``address''.
[top]
The following variables are for use in the USER.TAB configuration file.
"RealName" "Davide Libenzi"
"HomePage" "http://www.xmailserver.org/davide.html";
"MaxMBSize" "30000"
"ClosedML" "1"
"ListSender" "ml-admin@xmailserver.org"
This variable should be set to avoid delivery error notifications to reach the original message senders.
[top]
A full implementation of SMTP protocol allows the ability to perform mail routing bypassing DNS MX records by means of setting, in a ruled way, the 'RCPT TO: <>' request. A mail from 'xuser@hostz' directed to '@hosta,@hostb:foouser@hostc' is received by '@hosta' then sent to '@hostb' using 'MAIL FROM: <@hosta:xuser@hostz>' and 'RCPT TO: <@hostb:foouser@hostc>'. The message is then sent to '@'hostc using 'MAIL FROM: <@hostb,@hosta:xuser@hostz>' and 'RCPT TO: <foouser@hostc>'.
[top]
The new spool fs tree format has been designed to enable XMail to handle very large queues. Instead of having a single spool directory (like versions older than 0.61) a two layer deep splitting has been introduced so that its structure is:
0 <dir>
0 <dir>
mess <dir>
rsnd <dir>
info <dir>
temp <dir>
slog <dir>
cust <dir>
froz <dir>
...
...
When XMail needs to create a new spool file a spool path is chosen in a random way and a new file with the format:
mstime.tid.seq.hostname
is created inside the 'temp' subdirectory. When the spool file is ready to be committed, it's moved into the 'mess' subdirectory that holds newer spool files. If XMail fails sending a new message (the ones in mess subdirectory) it creates a log file (with the same name of the message file) inside the 'slog' subdirectory and move the file from 'mess' to 'rsnd'. During the message sending the message itself is locked by creating a file inside the 'lock' subdirectory (with the same name of the message file). If the message has permanent delivery errors or is expired and if the option 'RemoveSpoolErrors' of the 'SERVER.TAB' file is off, the message file is moved into the 'froz' subdirectory.
[top]
These are commands understood by ESMTP server:
[top]
These are commands understood by POP3 server:
[top]
Most of XMail configuration settings are command line tunables. These are command line switches organized by server.
T(i) = T(i-1) + T(i-1)/ratio.
If you set this ratio to zero, T remain unchanged over delivery tentatives. Default 16.
[top]
It's possible to remote admin XMail due to the existence of a 'controller server' that runs with XMail and waits for TCP/IP connections on a port (6017 or tunable via a '-Cp nport') command line option.
Admin protocol details:
The XMail admin server 'speaks' a given protocol that can be used by external GUI utilities written with the more disparate scripting languages, to remote administer the mail server. The protocol is based on sending formatted command and waiting for formatted server responses and error codes. All the lines, commands, and responses are delimited by a <CR><LF> pair. The error code string (I'll call it RESSTRING) has the given format:
"+DDDDD OK"<CR><LF>
if the command execution is successful while:
"-DDDDD ErrorString"<CR><LF>
if the command failed.
The `` character is not included in responses. DDDDD is a numeric error code while ErrorString is a description of the error. If DDDDD equals 00100, a lines list, terminated by a line with a single point (<CR><LF>.<CR><LF>), follows the response.
The input format for commands is similar to the one used in TAB files:
"cmdstring"[TAB]"param1"[TAB]..."paramN"<CR><LF>
where 'cmdstring' is the command string identifying the action to be performed, and param1,... are the parameters of the command.
Immediately after the connection with XMail controller server is established the client receives a RESSTRING that is:
+00000 <TimeStamp> XMail ...
if the server is ready, while:
-DDDDD ...
(where DDDDDD is an error code) if not.
The TimeStamp string has the format:
currtime.pid@ipaddress
and is used in MD5 authentication procedure.
As the first action immediately after the connection the client must send an authentication string with this format:
"user"[TAB]"password"<CR><LF>
where user must be enabled to remote admin XMail. Clear text authentication should not be used due server security. Using MD5 authentication instead, the client must perform an MD5 checksum on the string composed by (<> included):
<TimeStamp>password
and then send to the server:
"user"[TAB]"#md5chksum"<CR><LF>
where md5chksum is the MD5 checksum (note '#' as first char of sent digest). The result of the authentication send is a RESSTRING. If the user does not receive a positive authentication response, the connection is closed by the server.
[admin protocol] [top]
"useradd"[TAB]"domain"[TAB]"username"[TAB]"password"[TAB]"usertype"<CR><LF>
where:
The result is a RESSTRING.
[admin protocol] [top]
"userdel"[TAB]"domain"[TAB]"username"<CR><LF>
where:
The result is a RESSTRING.
[admin protocol] [top]
"userpasswd"[TAB]"domain"[TAB]"username"[TAB]"password"<CR><LF>
where:
The result is a RESSTRING.
[admin protocol] [top]
"userauth"[TAB]"domain"[TAB]"username"[TAB]"password"<CR><LF>
where:
The result is a RESSTRING.
[admin protocol] [top]
"userstat"[TAB]"domain"[TAB]"username"<CR><LF>
where:
The result is a RESSTRING. If successful (00100), a formatted matching users list follows terminated by a line containing a single dot (<CR><LF>.<CR><LF>). This is the format of the listing:
"variable"[TAB]"value"<CR><LF>
Where valid variables are:
[admin protocol] [top]
"aliasadd"[TAB]"domain"[TAB]"alias"[TAB]"account"<CR><LF>
where:
The result is a RESSTRING.
[admin protocol] [top]
"aliasdel"[TAB]"domain"[TAB]"alias"<CR><LF>
where:
The result is a RESSTRING.
[admin protocol] [top]
"aliaslist"[TAB]"domain"[TAB]"alias"[TAB]"account"<CR><LF>
or
"aliaslist"[TAB]"domain"[TAB]"alias"<CR><LF>
or
"aliaslist"[TAB]"domain"<CR><LF>
or
"aliaslist"<CR><LF>
where:
Example:
"aliaslist"[TAB]"foo.bar"[TAB]"*"[TAB]"mickey"<CR><LF>
lists all aliases of user 'mickey' in domain 'foo.bar'.
The result is a RESSTRING. In successful cases (00100) a formatted matching users list follows, terminated by a line containing a single dot (<CR><LF>.<CR><LF>). This is the format of the listing:
"domain"[TAB]"alias"[TAB]"username"<CR><LF>
[admin protocol] [top]
"exaliasadd"[TAB]"local-address"[TAB]"remote-address"<CR><LF>
where:
For example, the following command string:
"exaliasadd"[TAB]"dlibenzi@home.bogus"[TAB]"dlibenzi@xmailserver.org"<CR><LF>
will link the external email address 'dlibenzi@xmailserver.org' with the local email address 'dlibenzi@home.bogus'. The result is a RESSTRING.
[admin protocol] [top]
"exaliasdel"[TAB]"remote-address"<CR><LF>
where:
The result is a RESSTRING.
[admin protocol] [top]
"exaliaslist"[TAB]"local-address"[TAB]"remote-address"<CR><LF>
or
"exaliaslist"[TAB]"local-address"<CR><LF>
or
"exaliaslist"<CR><LF>
where:
Example:
"exaliaslist"[TAB]"*@home.bogus"<CR><LF>
lists all the external aliases linked to local accounts in domain 'home.bogus'.
The result is a RESSTRING. In successful cases (00100) a formatted matching users list follows, terminated by a line containing a single dot (<CR><LF>.<CR><LF>). This is the format of the listing:
"rmt-domain"[TAB]"rmt-name"[TAB]"loc-domain"[TAB]"loc-name"<CR><LF>
[admin protocol] [top]
"uservars"[TAB]"domain"[TAB]"username"<CR><LF>
where:
The result is a RESSTRING. In successfully cases (00100) a formatted list of user vars follow, terminated by a line containing a single dot (<CR><LF>.<CR><LF>). This is the format of the listing:
"varname"[TAB]"varvalue"<CR><LF>
[admin protocol] [top]
"uservarsset"[TAB]"domain"[TAB]"username"[TAB]"varname"[TAB]"varvalue" ... <CR><LF>
where:
There can be multiple variable assignments with a single call. If 'varvalue' is the string '.|rm' the variable 'varname' is deleted. The result is a RESSTRING.
[admin protocol] [top]
"userlist"[TAB]"domain"[TAB]"username"<CR><LF>
or
"userlist"[TAB]"domain"<CR><LF>
or
"userlist"<CR><LF>
where:
Example:
"userlist"[TAB]"spacejam.foo"[TAB]"*admin"<CR><LF>
lists all users of domain 'spacejam.foo' that end with the word 'admin'.
The result are a RESSTRING. If successful (00100), a formatted matching users list follows terminated by a line containing a single dot (<CR><LF>.<CR><LF>). This is the format of the listing:
"domain"[TAB]"username"[TAB]"password"[TAB]"usertype"<CR><LF>
[admin protocol] [top]
"usergetmproc"[TAB]"domain"[TAB]"username"<CR><LF>
where:
Example:
"usergetmproc"[TAB]"spacejam.foo"[TAB]"admin"<CR><LF>
gets mailproc.tab file for user 'admin' in domain 'spacejam.foo'.
The result is a RESSTRING. In successful cases (00100) the mailproc.tab file is listed line by line, terminated by a line containing a single dot (<CR><LF>.<CR><LF>).
[admin protocol] [top]
"usersetmproc"[TAB]"domain"[TAB]"username"<CR><LF>
where:
Example:
"usersetmproc"[TAB]"spacejam.foo"[TAB]"admin"<CR><LF>
sets mailproc.tab file for user 'admin' in domain 'spacejam.foo'.
The result is a RESSTRING. If successful (00101), the client must list the mailproc.tab file line by line, ending with a line containing a single dot (<CR><LF>.<CR><LF>). If a line of the file begins with a dot, another dot must be added at the beginning of the line. If the file has zero length the mailproc.tab is deleted. The client then gets another RESSTRING indicating the final command result.
[admin protocol] [top]
"mluseradd"[TAB]"domain"[TAB]"mlusername"[TAB]"mailaddress"[TAB]"perms"<CR><LF>
or
"mluseradd"[TAB]"domain"[TAB]"mlusername"[TAB]"mailaddress"<CR><LF>
where:
The result is a RESSTRING.
[admin protocol] [top]
"mluserdel"[TAB]"domain"[TAB]"mlusername"[TAB]"mailaddress"<CR><LF>
where:
The result is a RESSTRING.
[admin protocol] [top]
"mluserlist"[TAB]"domain"[TAB]"mlusername"<CR><LF>
where:
The result is a RESSTRING. If successful (00100), a formatted list of mailing list users follows terminated by a line containing a single dot (<CR><LF>.<CR><LF>).
[admin protocol] [top]
"domainadd"[TAB]"domain"<CR><LF>
where:
The result is a RESSTRING.
[admin protocol] [top]
"domaindel"[TAB]"domain"<CR><LF>
where:
The result is a RESSTRING. This is not always a safe operation.
[admin protocol] [top]
"domainlist"<CR><LF>
or:
"domainlist"[TAB]"wildmatch0"[TAB]...[TAB]"wildmatchN"<CR><LF>
The result is a RESSTRING. The wild match versions simply returns a filtered list of domains. If successful (00100), a formatted list of handled domains follows, terminated by a line containing a single dot (<CR><LF>.<CR><LF>).
[admin protocol] [top]
"aliasdomainadd"[TAB]"realdomain"[TAB]"aliasdomain"<CR><LF>
Example:
"aliasdomainadd"[TAB]"xmailserver.org"[TAB]"xmailserver.com"<CR><LF>
defines 'xmailserver.com' as an alias of 'xmailserver.org', or:
"aliasdomainadd"[TAB]"xmailserver.org"[TAB]"*.xmailserver.org"<CR><LF>
defines all subdomains of 'xmailserver.org' as alises of 'xmailserver.org'.
[admin protocol] [top]
"aliasdomaindel"[TAB]"aliasdomain"<CR><LF>
Example:
"aliasdomaindel"[TAB]"*.xmailserver.org"<CR><LF>
removes the '*.xmailserver.org' domain alias.
[admin protocol] [top]
"aliasdomainlist"<CR><LF>
or:
"aliasdomainlist"[TAB]"wild-dom-match"<CR><LF>
or:
"aliasdomainlist"[TAB]"wild-dom-match"[TAB]"wild-adom-match"<CR><LF>
The result is a RESSTRING. The wild match version simply returns a filtered list of alias domains. If successful (00100), a formatted list of alias domains follows, terminated by a line containing a single dot (<CR><LF>.<CR><LF>). The output format is:
"real-domain"[TAB]"alias-domain"<CR><LF>
[admin protocol] [top]
"custdomget"[TAB]"domain"<CR><LF>
where:
Example:
"custdomget"[TAB]"spacejam.foo"<CR><LF>
gets the custom domain file for domain 'spacejam.foo'.
The result is a RESSTRING. If successful (00100), the custom domain file is listed line by line terminated by a line containing a single dot (<CR><LF>.<CR><LF>).
[admin protocol] [top]
"custdomset"[TAB]"domain"<CR><LF>
where:
Example:
"custdomset"[TAB]"spacejam.foo"<CR><LF>
sets custom domain file for domain 'spacejam.foo'.
The result is a RESSTRING. If successful (00101), the client must list the custom domain file line by line, ending with a line containing a single dot (<CR><LF>.<CR><LF>). If a line of the file begins with a dot, another dot must be added at the begin of the line. If the file has zero length the custom domain file is deleted. The client then gets another RESSTRING indicating the final command result.
[admin protocol] [top]
"custdomlist"<CR><LF>
The result is a RESSTRING. If successful (00100), a formatted list of custom domains follows, terminated by a line containing a single dot (<CR><LF>.<CR><LF>).
[admin protocol] [top]
"poplnkadd"[TAB]"loc-domain"[TAB]"loc-username"[TAB]"extrn-domain"=> [TAB]"extrn-username"[TAB]"extrn-password"[TAB]"authtype"<CR><LF>
where:
The remote server must support 'APOP' authentication to specify APOP as authtype. Using APOP authentication is more secure because clear usernames and passwords do not travel on the network; if you're not sure about it, specify 'CLR' as authtype.
The result is a RESSTRING.
[admin protocol] [top]
"poplnkdel"[TAB]"loc-domain"[TAB]"loc-username"[TAB]"extrn-domain"=> [TAB]"extrn-username"<CR><LF>
where:
The result is a RESSTRING.
[admin protocol] [top]
"poplnklist"[TAB]"loc-domain"[TAB]"loc-username"<CR><LF>
or
"poplnklist"[TAB]"loc-domain"<CR><LF>
or
"poplnklist"<CR><LF>
The result is a RESSTRING. If successful (00100), a formatted list of handled domains follows, terminated by a line containing a single dot (<CR><LF>.<CR><LF>). The format of the listing is:
"loc-domain"[TAB]"loc-username"[TAB]"extrn-domain"[TAB]"extrn-username"=> [TAB]"extrn-password"[TAB]"authtype"[TAB]"on-off"<CR><LF>
[admin protocol] [top]
"poplnkenable"[TAB]"enable"[TAB]"loc-domain"[TAB]"loc-username"=> [TAB]"extrn-domain"[TAB]"extrn-username"<CR><LF>
or
"poplnkenable"[TAB]"enable"[TAB]"loc-domain"[TAB]"loc-username"<CR><LF>
where:
In the second format all users, links are affected by the enable operation.
The result is a RESSTRING.
[admin protocol] [top]
"filelist"[TAB]"relative-dir-path"[TAB]"match-string"<CR><LF>
where:
The result is a RESSTRING. If successful (00100), the directory is listed line by line, terminated by a line containing a single dot (<CR><LF>.<CR><LF>). The listing format is:
``filename''[TAB]``filesize''<CR><LF>
[admin protocol] [top]
"cfgfileget"[TAB]"relative-file-path"<CR><LF>
where:
Example:
"cfgfileget"[TAB]"ctrlaccounts.tab"<CR><LF>
The result is a RESSTRING. If successful (00100), the file is listed line by line, terminated by a line containing a single dot (<CR><LF>.<CR><LF>). You CANNOT use this command with indexed files !
[admin protocol] [top]
"cfgfileset"[TAB]"relative-file-path"<CR><LF>
where:
Example:
"cfgfileset"[TAB]"ctrlaccounts.tab"<CR><LF>
The result is a RESSTRING. IF successful (00101), the client must list the configuration file line by line, ending with a line containing a single dot (<CR><LF>.<CR><LF>). If a line of the file begins with a dot, another dot must be added at the beginning of the line. If the file has zero length the configuration file is deleted. The client then gets another RESSTRING indicating the final command result. Remember that configuration files have a strict syntax and that pushing a incorrect one can make XMail not work properly. You CANNOT use this command with indexed files!
[admin protocol] [top]
"frozlist"<CR><LF>
The result is a RESSTRING. If successful (00100), a formatted list of frozen messages follows, terminated by a line containing a single dot (<CR><LF>.<CR><LF>). The format of the listing is:
"msgfile"[tab]"lev0"[TAB]"lev1"[TAB]"from"[TAB]"to"[TAB]"time"[TAB]"size"<CR><LF>
Where:
[admin protocol] [top]
"frozsubmit"[TAB]"lev0"[TAB]"lev1"[TAB]"msgfile"<CR><LF>
where:
You can get this information from the frozlist command. After a message has been successfully rescheduled it is deleted from the frozen fs path. The result is a RESSTRING.
[admin protocol] [top]
"frozdel"[TAB]"lev0"[TAB]"lev1"[TAB]"msgfile"<CR><LF>
where:
You can get this information from the frozlist command. The result is a RESSTRING.
[admin protocol] [top]
"frozgetlog"[TAB]"lev0"[TAB]"lev1"[TAB]"msgfile"<CR><LF>
where:
You can get this information from the frozlist command. The result is a RESSTRING. If successful (00100), the frozen message log file follows, terminated by a line containing a single dot (<CR><LF>.<CR><LF>).
[admin protocol] [top]
"frozgetmsg"[TAB]"lev0"[TAB]"lev1"[TAB]"msgfile"<CR><LF>
where:
You can get this information from the frozlist command. The result is a RESSTRING. If successful (00100), the frozen message file follows, terminated by a line containing a single dot (<CR><LF>.<CR><LF>).
[admin protocol] [top]
"etrn"[TAB]"email-match0"...<CR><LF>
where:
Example:
"etrn" "*@*.mydomain.com" "your-domain.org"
starts queueing all messages with a matching destination address.
[admin protocol] [top]
``noop''<CR><LF>
The result is a RESSTRING.
[admin protocol] [top]
"quit"<CR><LF>
The result is a RESSTRING.
[admin protocol] [top]
Do you want to build GUI configuration tools using common scripting languages (Java, TCL/Tk, etc) and XMail controller protocol? Do you want to build Web configuration tools? Please let me know <davidel@xmailserver.org>.
[admin protocol] [top]
XMail has the ability to deliver locally prepared mail files that if finds in the 'spool/local' directory. The format of these files is strict:
mail from:<...>[CR][LF] rcpt to:<...>[CR][LF] ... [CR][LF] message text in RFC822 format with [CR][LF] line termination
All lines must be [CR][LF] terminated, with one mail-from statement, one or more rcpt-to statements, an empty line and the message text. Mail files must not be created directly inside the '/spool/local' directory but instead inside '/spool/temp' directory. When the file is prepared it has to be moved into '/spool/local'. The file name format is:
stime-seqnr.pid.hostname
where:
Example:
97456928-001.7892.home.bogus
XMail has a number of LMAIL threads that periodically scan the '/spool/local' directory watching for locally generated mail files. You can tune this number of threads with the '-Ln nthreads' command line option. The suggested number ranges from three to seven.
[top]
You can use CtrlClnt to send administration commands to XMail. These commands are defined in the previous section (XMAIL ADMIN PROTOCOL). The syntax of CtrlClnt is:
CtrlClnt [-snuptf] ...
where:
With the command and parameters that follow adhering to the command syntax, ie:
CtrlClnt -s mail.foo.org -u davide.libenzi -p ciao=> useradd home.bogus foouser foopasswd U
executes the command useradd with parameters 'home.bogus foouser foopasswd U'.
CtrlClnt returns 0 if the command is successful and != 0 if not. If the command is a query, then the result is printed to stdout.
[top]
kill -INT `cat /var/run/XMail.pid`
a system administrator can initiate the shutdown process (this can take several seconds). You can use the supplied 'xmail' startup script to start / stop / restart XMail:
xmail start / stop / restart
[top]
This command line utility enables you to create the user accounts structure by giving it a formatted list of users parameters (or a formatted text file). The syntax of the list (or file) is:
domain;username;password;real-name;homepage[NEWLINE]
where a line whose first character is '#' is treated as a comment. This utility can also be used to create a random number users (useful for me to test server performance).
These are MkUsers command line parameters:
MkUsers creates, under the specified root directory, the given structure:
rootdir <dir>
mailusers.tab <file>
domains <dir>
domainXXX <dir>
userXXX <dir>
user.tab <file>
mailbox <dir>
...
...
for the mailbox structure, while:
rootdir <dir>
mailusers.tab <file>
domains <dir>
domainXXX <dir>
userXXX <dir>
user.tab <file>
Maildir <dir>
tmp <dir>
new <dir>
cur <dir>
...
...
for the Maildir structure.
If the file 'mailusers.tab' already exist in the mail root path, MkUsers exits without overwriting the existing copy. This protect you from accidentally overwriting your file when playing inside the real MAIL_ROOT directory. If you want to setup the root directory (-r ...) as MAIL_ROOT, you must delete by hand the existing file (you must know what you're doing). If you setup the root directory (-r ...) as MAIL_ROOT you MUST have XMail stopped before running MkUsers. Existing files and directories are not overwritten by MkUsers so you can keep your users db in the formatted text file (or generate it by a database dump for example) and run MkUsers to create the structure. Remember that you have to add new domains in the 'domains.tab' file by hand. MkUsers is intended as a bulk-mode utility, not to create single user; for this CtrlClnt (or other GUI/Web configuration utilities) is better suited.
[top]
When building XMail, an executable called 'sendmail' is created. This is a replacement of the sendmail program used mostly on Unix systems; it uses the local mail delivery of XMail to send email generated onto the server machine. These sendmail options are supported (other options are simply ignored):
The syntax is:
sendmail [-t] [-f...] [-F...] [--input-file fname] [--xinput-file fname]=> [--rcpt-file fname] [--] recipient ...
The message content is read from the standard input and must be RFC compliant.
The following parameters are XMail extensions meant to be used with mailing lists managers (using sendmail as a mail list exploder):
To be RFC compliant means that the message MUST have the format:
[Headers] NewLine Body
Suppose you have your message in the file 'msg.txt', you're 'xmailuser@smartdomain', and you want to send the message to 'user1@dom1' and 'user2@dom2'. The syntax is:
sendmail -fxmailuser@smartdomain user1@dom1 user2@dom2 < msg.txt
or
sendmail -fxmailuser@smartdomain --input-file msg.txt user1@dom1 user2@dom2
[top]
foo@foodomain.net ==> foo@foodomain.net
and not:
foo@foodomain.net ==> foo
This enables XMail to handle multiple domains in cases where more nic-names are mapped over a single IP address.
To run finger queries you must specify:
foo@foodomain.net@foodomain.net
or as general rule:
username@pop3domain@hostname
You can use the optional configuration variable 'POP3Domain' (see SERVER.TAB VARIABLES above) to set the default domain for POP3 clients connections. This means that users of 'POP3Domain' can use only the name part of their email address as POP3 login, while users of other hosted domains must use their entire email as POP3 login.
Important!Please report XMail errors and errors in this document. If you successfully build and run XMail please let me know at davidel@xmailserver.org, I don't want money ;)
[top]
Version 0.1 (Alpha-1):
[top]
My mother Adelisa, for giving me the light.
My cat Grace, for her patience waiting for food while I'm coding.
All of the free source community, for giving me code and knowledge.
[top]