XMail LINUX HOW-TO

version 0.0.2
by CyberUX

vistors

Before reading this HOWTO
What is XMail?
- Free software
- Features
Get XMail
Install XMail
Start/Stop/Restart
Configure XMail
- Basic configuration
- Set up root accounts
- Login as root with telnet
- Administative commands
  - Login Logout
  - Domain management
  - User Management
  - Mailing lists
  - Alias Management
  - POP3 links
  - File Management
  - Frozen messages
  - Other Commands
- Main Server Configuration
  - TAB files
  - CTRLACCOUNTS.TAB
  - SERVER.TAB
  - CTRL.IMAP.TAB
  - DOMAINS.TAB
  - MAILUSERS.TAB
  - USERDEF.TAB
  - USER.TAB
  - MLUSERS.TAB
  - ALIASES.TAB
  - ALIASDOMAIN.TAB
  - DNSROOTS.TAB
  - EXTALIASES.TAB
  - MESSAGE.ID
  - POP3LINKS.TAB
  - SMTPGW.TAB
  - SMTPFWD.TAB
  - SMTPRELAY.TAB
  - SMTPAUTH.TAB
  - SMTPEXTAUTH.TAB
  - SPAMMERS.TAB
  - SPAM-ADDRESS.TAB
  - POP3.IPMAP.TAB
  - SMTP.IPMAP.TAB
  - FINGER.IPMAP.TAB
  - MAILPROC.TAB
- Command line configuration
- Command line administration
External Authentication
SMTP client Authentication
Domain message filters
Mail Routing
XMail as local mailer
What commands XMail can understand?
Tutorial 1 : "Make your own local email system"
Cofigure Kmail for XMail
XMail GUIs make work a game

Before reading this HOWTO

Welcome to XMail Linux HOWTO
Before you read this how to you must know these:

this howto is not finished, it is always updated while exploring the software
this howto may has topics that are not written yet but are for future versions
this how to is based on ReadMe file of XMail project (as the only documentation i found) and my experience on the software
this howto may has terible spelling mistakes (sorry)
this howto is not any official documentation for XMail
this howto or myself will not be responsible if you damage your software or your hardware (i think you must try very hard to do something like that but i must make my notice)
this howto assumes that you have a linux box and you've played enought with it so you know the basic administration of it
You can modify, copy, edit this howto as you like to make your own tutorials, or howto. The only thing i ask is your documentation to be copyleft as mine so other people can make the same :)
You can add topics to this howto free. Just contact with me

What is XMail?

XMail is a powerfull mail server created by Davide Libenzi (davidel@xmailserver.org http://www.xmailserver.org/)
XMail is free software under GPL licence.
This means that 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; 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

XMail has these features
1) ESMTP server
2) POP3 server
3) Finger server
4) Multiple domains
5) Users don't need a real system account
6) SMTP relay checking
7) SMTP RBL maps check (rbl.maps.vix.com)
8) SMTP RSS maps check (relays.mail-abuse.org)
9) SMTP ORBS relay check (relays.orbs.org)
10) SMTP DUL map check (dialups.mail-abuse.org)
11) SMTP protection over spammers ( IP based and address based )
12) SMTP authentication ( PLAIN LOGIN CRAM-MD5 POP3/SMTP and custom )
13) SMTP ETRN command support
14) POP3 account syncronizer with external POP3 accounts
15) Account aliasing
16) Domain aliasing
17) Mailing lists
18) Custom mail processing
19) Locally generated mail files delivery
20) Remote administration
21) Custom mail exchangersv 22) Logging
23) Multi platform
24) Domain message filters
25) Custom ( external ) POP3 authentication

Get XMail

You can download Xmail from XMail home page
Visit http://www.xmailserver.org
You can download XMail in many formats RPM, gz, tar, zip etc

Install XMail on LINUX

The best and easiest way to install XMail is to get XMail as RPM package.
With this way you do not have to build XMail and install it manualy.
if you have KDE just click the RPM package and follow KPackage intructions
If you wish to make all the dirty job get a source package like .gz and follow the XMail Readme instructions

Make a test to see what you 've got

Now you can make a test to see what you 've got. Open a Konsole window or use your favorite shell and type 'telnet localhost 25'
If you 've got something like this image you have just connected to smtp server! To disconnect type quit

You can try any other ports you like but our interest is on ports 25 (smtp), 110 (pop3), 79 (finger), 6017 (admin server of XMail).

Start/Stop/Restart

Your XMail distro has a shell script, written by Miquel van Smoorenburg (miquels@cistron.nl) and Modified by Davide Libenzi, that helps you to start - stop - restart XMail servers. This file is placed in your "/etc/rc.d/init.d/" directory if you installed XMail from a RPM.

You can give in your shell a command like:
"xmail start" to start the XMail or
"xmail stop" to stop the XMail or
"xmail restart" to restart the XMail

Configure XMail

To configure XMail the only thing that you have to do is to edit the *.tab files.
These files are the configuration files for each module of XMail.
TAB files are text files ( in the sense meant by OS : for NT and for Linux ) with this format :
"value1"[TAB]"value2"[TAB]...[NEWLINE]
Before you can edit .tab files you must know what options contained in each file and what values you can set.

Basic configuration

The only configuration is needed for the first time is to make a root account for XMail in order to administrate it remotly. Yes XMail has its own administration server. You can login to this server and manage XMail remotly

Set up root accounts

In order to administrate your XMail server you must first set up at least one administrative account.
This account is not an email account. This account is only for administration of XMail server.
To make an admin account you must edit the file CTRLACCOUNTS.TAB. This is located in most cases in "/var/MailRoot/"
This file contains the accounts that are enable to remote administer XMail.
The password is encrypted with 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 !

CTRLACCOUNTS.TAB
SYNTAX	"username"[TAB]"password"[NEWLINE]
Ex.	"root" "01c04b0"

In order to create an encrypted password you have to use XMCrypt which is located in your '/var/MailRoot/bin'
The syntax for XMCrypt is simple, just give the clear password you want to encrypt. XMCrypt will return the encrypted password
So if you want to use as root password for XMail the word 'mypass' just type in Konsole '/var/MailRoot/bin/XMCrypt mypass'

if you 've got something like this then you have your encrypted password.
You can copy it to your CTRLACCOUNTS.TAB file.

Login as root with telnet

Now you can login to port 6017 with telnet. The only thing you have to do is after you 've been connected give your username and password
Let's say you set up your CTRLACCOUNTS.TAB file with name root and encrypted pass 081c15041616 from clear pass mypass
Type in your Konsole
telnet localhost 6017 and
roothit TABmypass

If you 've been connected then you will see something like this image.

Administrative commands

If you can loggin succesfully as root to admin server then you are ready to manage your XMail server. The commands that you have to learn to do it are listed in the next table.
All commands are executed in one line and each one has the format "command"[TAB]"value0"[TAB]...[TAB]"valueN"[NEWLINE]
[TAB] = you hit TAB button from your keyboard
[NEWLINE] = after finish the writing of a wanted command you hit ENTER button from your keyboard
After an execution of a command the server respondes with an error code
This error code has many values of this format. "+DDDDD String"
DDDDD are digits of an error number and String is an error string which describes the response.
If the command was executed succesfully the String will be "OK", in other case it will be the custom error string.
Ex. "+00000 OK" or "+00100 OK" or "-00108 Bad CTRL Command syntax"

Login Logout
Login admin server	"telnet[SPACE]"domain or ipadr"[SPACE]port" after connected type "adminname"[TAB]"password"
Description	This command logins you on admin server
Ex.	"telnet mymailserver.com 6017" "root" "mypass"

Logout from admin server	"quit"
Description	This command logouts you from admin server
Ex.	"quit"

Domain Management
Adding a domain	"domainadd"[TAB]"domain"
Description	This command adds a domain to mail server
Ex.	"domainadd" "mycompany.com"

Deletinging a domain	"domaindel"[TAB]"domain"
Description	This command delete a domain from mail server
Ex.	"domaindel" "mycompany.com"

Listing handled domains	"domainlist" or "domainlist"[TAB]"wildmatch0"[TAB]...[TAB}"wildmatchN"
Description	This command list all the handled domains from the mail server. You can use this command with wildcards as * or ? to search for domains
Ex.	"domainlist" or "domainlist" "*.com"

Adding domain alias	"aliasdomainadd"[TAB]"realdomain"[TAB]"aliasdomain"
Description	This command add an alias for a domain
Ex.	"aliasdomainadd" "mycompany.com" "mycompany2.com
This example define mycompany2.com as an alias of mycompany.com
In domain string you can use wildcards *, ? for more general definitions
Ex.	"aliasdomainadd" "mycompany.com" "*.mycompany2.com
This example define all subdomains of mycompany2.com as aliases of mycompany.com

Deleting domain alias	"aliasdomainadel"[TAB]"aliasdomain"
Description	This command delete an alias domain
Ex.	"aliasdomaindel" "mycompany2.com
In domain string you can use wildcards *, ? for more general definitions

Listing alias domains	"aliasdomainlist" or "aliasdomainlist"[TAB]"wildmatch0"[TAB]...[TAB}"wildmatchN"
Description	This command list all the alias domains from the mail server. You can use this command with wildcards as * or ? to search for domains
Ex.	"aliasdomainlist" or "aliasdomainlist" "*.com"

Getting custom domain file	"custdomget"[TAB]"domain"
Description
Ex.	"custdomget" "spacejam.foo"

Setting custom domain file	"custdomset"[TAB]"domain"
Description
Ex.	"custdomset" "spacejam.foo"

Listting custom domains	"custdomlist"
Description
Ex.	"custdomlist"

User Management
Adding a user account	"useradd"[TAB]"domain"[TAB]"username"[TAB]"password"[TAB]"usertype"
Description	This command adds a user to mail server under a handled domain
Values	domain=a handled domain username=a simple username password=the password for the user usertype=U for normal user or M for mailing list user
Ex.	"useradd" "mycompany.com" "user1" "passofuser" "U"

Deleting a user account	"userdel"[TAB]"domain"[TAB]"username"
Description	This command delete a username for a domain
Ex.	"userdel" "mycompany.com" "cris"

Changing a user's password	"userpasswd"[TAB]"domain"[TAB]"username"[TAB]"newpassword"
Description	This command changes a user's password
Ex.	"userpasswd" "mycompany.com" "cris" "mynewpass"

Authenticate user	"userauth"[TAB]"domain"[TAB]"username"[TAB]"password"
Description	This command authenticate a user
Ex.	"userauth" "mycompany.com" "cris" "mypass"

Retrieve user statistics	"userstat"[TAB]"domain"[TAB]"username"
Description	This command retrieve user statistics
Ex.	"userstat" "mycompany.com" "cris"

Listing user vars	"uservars"[TAB]"domain"[TAB]"username"
Description	This command retrieve user vars
Ex.	"uservars" "mycompany.com" "cris"

Setting user vars	"uservarset"[TAB]"domain"[TAB]"username"[TAB]"varname"[TAB]"varvalue"...
Description	This command set values to user variables. User variables are variables which are stored in USER.TAB file. These varname can be RealName = a string with the full user name Ex. "Jhon Smith" HomePage = a string with the full address of the home page of user Ex. "http://www.myclientcompany.com" MaxMBSixe = Max User mailbox size in Kb ClosedML= Specify if the mailing list is closed only to subscribed users. Set "1" for true "0" for false ListSender= Specify the mailing list sender or administrator SmtpPerms= user smtp permission (see SMTPAUTH.TAB for more info) ReceiveEnable= Set to "1" if the account can receive email or '0" if account is disabled from receiving emails PopEnable= Set to "1" if the account can is enable to fetch POP3 messages or "0" if account is disabled for this service UserReplyTo = Enable/Disable the emission of the Reply-To: header for mailing list's messages MaxMessageSize = Set the maximum message size in Kb that the user will be able to send through the server. (this var overrides SERVER.TAB variable)
Ex.	"uservarset" "mycompany.com" "cris" "PopEnable" "0"

Listing users	"userlist"[TAB]"domain"[TAB]"username" or "userlist"[TAB]"domain" or "userlist"
Description	This command list users domain and username can contain wildcards * or ?
Ex.	"uservars" "mycompany.com" "cris"

Mailing Lists
Adding a mailing list user	"mluseradd"[TAB]"domain"[TAB]"username"[TAB]"mailaddress"[TAB]"permissions" or "mluseradd"[TAB]"domain"[TAB]"username"[TAB]"mailaddress"
Description	This command add a user in a mailing list. Permissions are: R = read or RW = read and write
Ex.	"mluseradd" "mycompany.com" "cris" "cris@crisdomain.com"

Deleting a mailing list user	"mluserdel"[TAB]"domain"[TAB]"mlusername"[TAB]"mailaddress"[TAB]
Description	This command delete a user from a mailing list.
Ex.	"mluserdel" "mycompany.com" "cris" "cris@crisdomain.com"

Listing mailing list users	"mluserlist"[TAB]"domain"[TAB]"mlusername"[TAB]
Description	This command list users for a mailing list.
Ex.	"mluserlist" "mycompany.com" "cris*"

Alias Management
Adding an alias	"aliasadd"[TAB]"domain"[TAB]"alias"[TAB]"username"
Description	This command add an allias domain = domain name ( must be handled by the server ) alias = alias to add username = real email account ( locally handled )
Ex.

Deleting an alias	"aliasdel"[TAB]"domain"[TAB]"alias"[TAB]"username"
Description	This command delete an allias domain = domain name ( must be handled by the server ) alias = alias to add username = real email account ( locally handled )
Ex.

Listing aliases	"aliaslist"[TAB]"domain"[TAB]"alias"[TAB]"username" or "aliaslist"[TAB]"domain"[TAB]"alias" or "aliaslist"[TAB]"domain" or "aliaslist"
Description	This command list alliases domain = domain name ( must be handled by the server ) alias = alias to add username = real email account ( locally handled )
Ex.

POP3 links
Adding a POP3 external link	"poplnkadd"[TAB]"loc-domain"[TAB]"loc-username"[TAB]"extrn-domain"[TAB] "extrn-username"[TAB]"extrn-password"[TAB]"authtype" or "mluseradd"[TAB]"domain"[TAB]"username"[TAB]"mailaddress"
Description	This command make an external POP link for a user on a domain of a hadled xmail domain
Ex.	"poplnkadd" "mycompany.com" "cris" "otherISP.com" "cris@otherISP.com" "cris" "crispassonotherISP" "CLR"

Deleting a POP3 external link	"poplnkdel"[TAB]"loc-domain"[TAB]"loc-username"[TAB]"extrn-domain"[TAB]"extrn-username" or "mluseradd"[TAB]"domain"[TAB]"username"[TAB]"mailaddress"
Description	This command delete an external POP link for a user on a domain of a hadled xmail domain
Ex.	"poplnkadd" "mycompany.com" "cris" "otherISP.com" "cris@otherISP.com" "cris"

Listing POP3 external links	"poplnklist"[TAB]"loc-domain"[TAB]"loc-username" or "poplnklist"[TAB]"loc-domain"[TAB] or "poplnklist"
Description	This command lists external POP links for users or domains
Ex.	"poplnklist" "mylist.com"

Enabling a POP3 external links	"poplnkenable"[TAB]"enable"[TAB]"loc-domain"[TAB]"loc-username"[TAB] "extrn-domain"[TAB]"extrn-username" or "poplnkenable"[TAB]"enable"[TAB]"loc-domain"[TAB]"loc-username"
Description	This command enables or disables external POP links
Ex.

File management
Listing files	"filelist"[TAB]"relative-path"[TAB]"match-string"
Description	Return a list of files for a relative MailRoot path and wildcard match string relative-path = path relative to MailRoot path match-string = wildcard match string
Ex.	"filelist" "/" "."

Getting a configuration file	"cfgfileget"[TAB]"relative-path"
Description	List line by line a configuration file. You can not use this command with indexed files
Ex.	"cfgfileget" "ctrlaccounts.tab"

Setting a configuration file	"cfgfileset"[TAB]"relative-path"
Description	In success case the client must list the configuration file line by line, ending with a line containing a single dot ([NEWLINE].[NEWLINE]). If a line of the file begin with a dot, another dot must be added at the begin of the line. The client must then get another respond string indicating the final command. You can make XMail to not work properly with a bad configured file. You can not use this command with indexed files
Ex.	"cfgfileget" "ctrlaccounts.tab"

Frozen messages
Listing frozen messages	"frozlist"
Description	Return a list of messages which for some reson are frozen
Ex.	"frozlist"

Rescheduling frozen messages	"frozsubmit"[TAB]"lev0"[TAB]"lev1"[TAB]"msgfile"
Description	After a successful frozsubmit command the frozen message will bedeleted from frozlist
Ex.

Deleting frozen messages	"frozdel"[TAB]"lev0"[TAB]"lev1"[TAB]"msgfile"
Description	Delete a frozen message
Ex.

Getting frozen message log file	"frozgetlog"[TAB]"lev0"[TAB]"lev1"[TAB]"msgfile"
Description	Getting frozen message log
Ex.

Other commands
Starting a queue flush	"etrn"[TAB]"email-match0"...
Description
Ex.	"etrn" "@.mydomain.com" "your-domain.org"

Do nothing	"noop"
Description
Ex.	"noop"

Main Server Configuration

TAB Files

As you read all the configuration of XMail is done by editing the *.tab files. Remote administration give you the commands 'cfgfileget" and "cfgfileset" to get and set ready configuration files.
The only thing has left, is to learn how to edit corectly the *.tab files.
Remote administration does not configure all the *.tab files, so for some of them you must manualy edit them. (we hope in next XMail versions Davide make some more commands for remote configuration!)
Each *.tab file has a line per line configuration with this format "value1"[TAB]....[TAB]"value(N)"[NEWLINE]
A # symbol at the begining of a line is a comment, this value is not read by XMail, instead this value is set to default
Let's check out each tab file

CTRLACCOUNTS.TAB
Description	This file contain the accounts that are enable to remote administer XMail. The password is encrypted with 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 !
SYNTAX	"username"[TAB]"password"[NEWLINE]
Ex.	"root" "01c04b0"

SERVER.TAB
Description	This file contain server configuration variabiles.
SYNTAX	"varname"[TAB]"varvalue"[NEWLINE]
Ex.
Values	[RootDomain] Indicate the primary domain for the server. Ex. "RootDomain" "xmailserver.test" [POP3Domain] Set the default domain for POP3 client connections. Ex. "POP3Domain" "xmailserver.test" [PostMaster] Set the postmaster address. Ex. "PostMaster" "root@xmailserver.test" [ErrorsAdmin] The email address that will receive notification messages for every message that has had delivery errors. It can be empty and in such case the notification message will be sent only to the sender. Ex. "ErrorsAdmin" "root@xmailserver.test" [TempErrorsAdmin] The email address that will receive notification for temporary delivery failures. In case it's empty the notification message will be sent only to the sender. Ex. "TempErrorsAdmin" "send-failures@xmailserver.test" [DefaultSMTPGateways] A comma separated list of SMTP servers XMail _must_ use to send its mails. This has the precedence over MX records. Ex. "DefaultSMTPGateways" "192.168.1.2,192.168.1.15" [HeloDomain] If this variable is specified and is not empty, its content will be sent as HELO domain. Otherwise the reverse lookup of the local IP will be sent as HELO domain. This will help to deal with remote SMTP servers that are set to check the reverse lookup of the incoming IP. Ex. "HeloDomain" "xmailserver.test" [CheckMailerDomain] Enable validation of the sender domain ( "MAIL FROM:<...@xxx>" ) by looking up DNS/MX entries. Ex. "CheckMailerDomain" "1" [RemoveSpoolErrors] Indicate if mail has to be removed or stored in froz directory after a failure in delivery or filtering. Ex. "RemoveSpoolErrors" "0" [NotifyMsgLinesExtra] Number of lines of the bounced message that have to be listed inside the notify message ( lines after the headers section ). Default is zero. Ex. "NotifyMsgLinesExtra" "8" [NotifySendLogToSender] Enable/Disable the send of the message log file inside the notify message to the sender. Default is off ( zero ). Ex. "NotifySendLogToSender" "0" [NotifyTryPattern] List of delivery attempts that require the system to send a notification to the sender ( and eventually to TempErrorsAdmin ). The list is a comma separated list of number ( with no extra spaces ) like : "1,4,9" Default is empty that means that no notification is sent upon a delivery attempt failure. Ex. "NotifyTryPattern" "1" [AllowNullSender] Enable null sender ( "MAIL FROM:<>" ) messages to be accepted by XMail. Ex. "AllowNullSender" "1" [MaxMTAOps] Set the maximum number of MTA relay steps before to declare the message as looped ( default 16 ). Ex. "MaxMTAOps" "16" [ReceivedHdrType] Set the verbosity of the Received: message headers tag. 0 = Standard ( client IP shown , server IP not ). Default. 1 = Verbose ( client IP shown , server IP shown ) 2 = Strict ( no IP shown ) Ex. "ReceivedHdrType" "0" [FetchHdrTags] Set the list of headers tags to be used to extract addresses from POP3 fetched messages ( POP3LINKS.TAB ). This is a comma delimited list ( no extra space or TABs must be included inside the list ) like : "+X-Deliver-To,To,Cc" Tags preceded by a '+' character will make XMail to stop scanning when an address is found inside such 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. Ex. "FetchHdrTags" "+X-Deliver-To,+Received,To,Cc" [AllowSmtpVRFY] Enable the use of VRFY SMTP command. This flag may be forced by SMTP authentication. Ex. "AllowSmtpVRFY" "1" [AllowSmtpETRN] Enable the use of ETRN SMTP command. This flag may be forced by SMTP authentication. Ex. "AllowSmtpETRN" "1" [SmtpMinDiskSpace] Minimum disk space ( in Kb ) that is requested before accepting an SMTP connection. Ex. "SmtpMinDiskSpace" "100000" [SmtpMinVirtMemSpace] Minimum virtual memory ( in Kb ) that is requested before accepting an SMTP connection. Ex. "SmtpMinVirtMemSpace" "64000" [Pop3MinVirtMemSpace] Minimum virtual memory ( in Kb ) that is requested before accepting a POP3 connection. Ex. "Pop3MinVirtMemSpace" "64000" [Pop3SyncErrorAccount] This defines the email account ( MUST be handled locally ) that will receive all fetched email that XMail has not been able to deliver. Ex. "Pop3SyncErrorAccount" "psync-errors@xmailserver.test" [EnableAuthSMTP-POP3] Enable SMTP after POP3 authentication ( default on ). Ex. "EnableAuthSMTP-POP3" "0" [MaxMessageSize] Set the maximum message size in Kb that is possible to send through the server. Ex. "MaxMessageSize" "20000" [DefaultSmtpPerms ] This list SMTP permissions assigned to users looked up inside MAILUSERS.TAB during SMTP authentication. It also defines the permissions for users authenticated with SMTP after POP3. Ex. "DefaultSmtpPerms" "MRVZ" [CustMapsList] This is a list a user can use to set custom maps checking. The list has the given ( strict ) format : maps-root:code,maps-root:code... Where maps-root is the root for the dns query ( Ex. dialups.mail-abuse.org. ) and the code can be : 1 = the connection is drooped soon 0 = the connection is kept alive but only authenticated users can send mail -S = the peer can send messages but a delay of S seconds will be introduced between commands Ex. "CustMapsList" "list.dsbl.org.:1,blackholes.mail-abuse.org.:1,dialups.mail-abuse.org.:0" [SMTP-RDNSCheck] Indicate if XMail must do an RDNS lookup before accepting a incoming SMTP connection. If 0 the check is not performed; if 1 and the check fail, the user will receive a "server use forbidden" at MAIL_FROM time; if -S ( S > 0 ) and the check fail, a delay of S seconds between SMTP commands is used to prevent massive spamming. SMTP authentication will override the denial set by this option by giving authenticated users the ability to access the server from "mapped" IPs. Ex. "SMTP-RDNSCheck" "1" [SmartDNSHost] Setup a list of smart DNS hosts to which are directed DNS queries with recursion bit set to true. Such DNS hosts must support DNS recursion in queries. The format is : dns.home.bogus.net:tcp,192.168.1.1:udp,... Ex. "SmartDNSHost" "dns.home.bogus.net:tcp,192.168.1.1:udp" [DynDnsSetup] Give the possibility to handle dynamic IP domain registration to dynamic IP servers. One of these service providers is "www.dyndns.org" whose site You can watch for registrations and more info. The string has the format : server,port,HTTP-GET-String[,username,password] Ex. : 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 : DOMAIN = domain You've registered USERNAME = username You get from service provider PASSWORD = password You get from service provider The %s in HTTP-GET-String will be replaced with the IP address to register. Ex. "DynDnsSetup" "members.dyndns.org,80,/nic/dyndns?action=edit&started=1&hostname=YES& host_id=yourhost.ourdomain.ext&myip=%s&wildcard=OFF&mx=,br> mail.exchanger.ext&backmx=NO,foouser,foopasswd" [SmtpConfig] Default SMTP server config loaded if specific server IP config is not found. Ex. "SmtpConfig" "mail-auth" [SmtpConfig-XXX.YYY.ZZZ.WWW] Specific IP SMTP server config. The variable value is a comma separated sequence of configuration tokens whose meaning is : mail-auth = authentication required to send mail to the server. Please note that by setting this value will require authentication even for sending to local domains, and this is not what you're probably wishing Ex. "SmtpConfig-192.168.0.1" "mail-auth"

CTRL.IPMAP.TAB
Description	This file control IP access permission to CTRL(admin) server.
SYNTAX	"ipaddr"[TAB]"netmask"[TAB]"permisssion"[TAB]"precedence"[NEWLINE]
Ex.	"0.0.0.0"[TAB]"0.0.0.0"[TAB]"DENY"[TAB]"1"[NEWLINE] "212.131.173.0"[TAB]"255.255.255.0"[TAB]"ALLOW"[TAB]"2"[NEWLINE] 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.

DOMAINS.TAB
Description	Define domains handled by the server.
SYNTAX	"domain"[NEWLINE]
Ex.	"localhost.localdomain" "mycompany.com"

MAILUSERS.TAB
Description	Define an account Ex. "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 domains handling the POP3 client must use the entire email address for the POP3 user account, ex. if a user has email user@domain it must supply : user@domai 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 ( can't exist duplicated user ids ). 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 in XMCrypt.cpp. Even if external authentication is used ( see Part 8 External Authentication ) this file _must_ contain an entry for each user handled by XMail. You __CANNOT__ edit this file while XMail is running due to the fact that is an indexed file. You can use instead the remote command "useradd"
SYNTAX	"domain"[TAB]"account"[TAB]"enc-passwd"[TAB]"account-id"[TAB] "account-dir"[TAB]"account-type"[NEWLINE]
Ex.	"home.bogus" "dlibenzi" "XYZ..." 1 "dlibenzi" "U"

USERDEF.TAB / USER.TAB
Description	Set values for users contain 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" will reside "domain" "account" directories ( $MAIL_ROOT/"domain"/"account" ). This folder contain a subfolder named mailbox ( or Maildir/(tmp,new,cur) ) that store all "account" messages. It also contains a file named USER.TAB that store "account" variabiles, ex : "RealName" "Davide Libenzi" "HomePage" "http://www.xmailserver.org/davide.html" "MaxMBSize" "30000"
SYNTAX	"varname"[TAB]"value"[NEWLINE]
Ex.	"RealName" "Jo Smith"

MLUSERS.TAB
Description	If the user is a mailing list this file must exist inside user account subdirectory and contain a list of users subscribed to this list. user = subscriber email address perms = subscriber permissions ( R = read or RW = read/write ) If the USER.TAB file defines a "ClosedML" variable as 1 then a client can post to this mailing list only if It's listed in MLUSERS.TAB with RW permissions.
SYNTAX	"user"[TAB]"perms"[NEWLINE]
Ex.	"davidel@xmailserver.org" "RW" "ghostuser@nightmare.net" "R"

ALIASES.TAB
Description	Define aliases for user accounts You __CANNOT__ edit this file while XMail is running due to the fact that is an indexed file.
SYNTAX	"domain"[TAB]"alias"[TAB]"realaccount"[NEWLINE]
Ex.	"home.bogus" "davidel" "dlibenzi" define "davidel" as alias for "dlibenzi" in "home.bogus" domain. "home.bogus" "foobog" "homer@internal-domain.org" define an alias for all users whose name start with foo and end with bog that point to the locally handled account homer@internal-domain.org. "home.bogus" "??trips" "travels" define an alias for all users whose name start with any two chars and end with trips. You can have widcard even in the domain field, like : "" "postmaster" "postmaster@domain.net"

ALIASDOMAIN.TAB
Description	Define aliases for handled domains
SYNTAX	"aliasdomain"[TAB]"realdomain"[NEWLINE]
Ex.	"simpson.org" "simpson.com" "*.homer.net" "homer.net" The first line define simpson.org as an alias of simpson.com while the second remap all subdomains of homer.net to homer.net

DNSROOTS.TAB
Description	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 = "."
SYNTAX	hosts
Ex.	a.root-servers.net. h.root-servers.net. c.root-servers.net. g.root-servers.net. f.root-servers.net. b.root-servers.net. j.root-servers.net. k.root-servers.net. l.root-servers.net. m.root-servers.net. i.root-servers.net. e.root-servers.net. d.root-servers.net.

EXTALIASES.TAB
Description	This file is used in configutaions in which the server run not directly on internet but act as internal mail exchanger and external mail gateway. This file define "Return-Path: <...>" mapping for internal mail delivery. If You are using a Mail client like Outlook, Eudora, KMail ... You have configured Your email address with the external account say "dlibenzi@xmailserver.org". When You post an inernal message to "foo@home.bogus" the mail client put Your external email address ( "dlibenzi@xmailserver.org" ) in the "MAIL FROM: <...>" SMTP request. Now if the user "foo" reply to this message, it'll reply to "dlibenzimaticad.it" then it'll be 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 lead to an internal mail reply. You __CANNOT__ edit this file while XMail is running due to the fact that is an indexed file.
SYNTAX	"external-domain"[TAB]"external-account"[TAB]"local-domain"[TAB]"local-user"[NEWLINE]
Ex.	"xmailserver.org" "dlibenzi" "home.bogus" "dlibenzi"

MESSAGE.ID
Description	Is a file storing a sequential message number. You set it at 1 when You install the server and leave it be handled by the software.
SYNTAX
Ex.

POP3LINKS.TAB
Description	This entry is used to syncronize an external account like "dlibenzi@xmailserver.org" with encrypted password "XYZ..." with a local account like "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 ASKED authentication to specify ASKED as authtype. Using authentication is more secure coz 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 syncronize the external account "dlibenzi@xmailserver.org" with encrypted password "XYZ..." with the account "dlibenzi@home.bogus.com" using CLR authentication. The message will be 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 : XMail parse the message headers by searching for To:, Cc: and Bcc: addresses Each address's domain is compared with the list of valid domains ( felins.net, pets.org ) For each valid address the username part is taken and joined with the '@' and the masquerade domain name ( the name following '?' ) The message is spooled with the above built destination address 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 otion is : "&.local,felins.net,pets.org" "dlibenzi" "xmailserver.org" "dlibenzi" "XYZ..." "CLR" where a fetched message whose To: address is graycat@felins.net will be 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 will start PSYNC session with a delay that You can specify with the -Yi nsec command line parameter ( default 120 ). XMail will also check for the presence ( inside MAIL_ROOT ) of a file named ".psync-trigger" and, when this file is found, a PSYNC session will start and such file will be removed. authtype = authentication method ( CLR = USER/PASS auth APOP = APOP auth )
SYNTAX	"local-domain"[TAB]"local-account"[TAB]"external-domain"[TAB] "external-account"[TAB]"external-crypted-password"[TAB]"authtype"[NEWLINE]
Ex.	"home.bogus" "dlibenzi" "xmailserver.org" "dlibenzi" "XYZ..." "APOP"

SMTPGW.TAB
Description	Define a smtp gateway list for a domain where domain = a valid domain gateway as is defined in DNS MX RRs port= a valid integer that is the port where the gateway is listening (optional) Each gateway in the list must be separated with "," No spaces are allowed
SYNTAX	"domain"[TAB]"domaingateway:port(0),....,domaingateway:port(N)"[NEWLINE]
Ex.	"foo.example.com" "mail.xmailserver.org:7001,192.168.1.1:6123,mx.xmailserver.org" or "*.dummy.net" "mail.xmailserver.org,192.168.1.1,mx.xmailserver.org:6423"

SMTPFWD.TAB
Description	Define a smtp frwd mail exchanger list where domain = a valid domain gateway as is defined in DNS MX RRs port= a valid integer that is the port where the gateway is listening (optional) Each gateway in the list must be separated with "," No spaces are allowed
SYNTAX	"domain"[TAB]"domaingateway:port(0),....,domaingateway:port(N)"[NEWLINE]
Ex.	"foo.example.com" "mail.xmailserver.org:7001,192.168.1.1:6123,mx.xmailserver.org" will send 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" will send 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.

SMTPRELAY.TAB
Description	Define a range of hosts to use as a relay the xMail server
SYNTAX	"ipaddr"[TAB]"netmask"[NEWLINE]
Ex.	"212.131.173.0"[TAB]"255.255.255.0"[NEWLINE] allow all hosts of the class "C" network "212.131.173.XXX" to use the server as relay.

SMTPAUTH.TAB
Description	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 will test 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 : M = open mailing features R = open relay features ( bypass all other relay blocking traps ) V = VRFY command enabled ( bypass SERVER.TAB variable ) T = ETRN command enabled ( bypass SERVER.TAB variable ) Z = disable mail size checking ( bypass SERVER.TAB variable ) When PLAIN, LOGIN or CRAM-MD5 authentication mode are used a first lookup in MAILUSERS.TAB accounts is performed to avoid duplicating informations with SMTPAUTH.TAB. So using these authentication modes a user must use as username the full email address ( the : separator is permitted instead @ ) 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 will fail then SMTPAUTH.TAB lookup is done.
SYNTAX	"username"[TAB]"password"[TAB]"permissions"[NEWLINE]
Ex.

SMTPEXTAUTH.TAB
Description	Besides internal SMTP authentication methods a user ( XMail administrator ) can define custom authentication procedures by setting up properly this 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" will be listed during the EHLO command response. Where "arg-or-macro" can be : @@CHALL = server challenge given by base-challenge + ':' + server-timestamp @@DGEST = client response to server challenge ( @@CHALL ) @@FSECRT = a file containing all the lines ( username + ':' + password ) of SMTPAUTH.TAB
SYNTAX	"auth-name"[TAB]"base-challenge"[TAB]"program-path"[TAB]"arg-or-macro"...[NEWLINE]
Ex.	"RSA-AUTH" "foochallenge" "/usr/bin/myrsa-authenticate" "-c" "@@CHALL" "-f" "@@FSECRT" "-d" "@@DGEST"

SPAMMERS.TAB
Description	Set up a ban list for spammers based on ip address and a netmask
SYNTAX	"ipaddr"[TAB]"netmask"[NEWLINE]
Ex.	"212.131.173.0"[TAB]"255.255.255.0"[NEWLINE] register all hosts of the class "C" network "212.131.173.XXX" as spammers, and block them the use of XMail SMTP server.

SPAM-ADDRESS.TAB
Description	Set up a ban list for spammers based on email address
SYNTAX	"spam-address"[NEWLINE]
Ex.	"@rude.net"[NEWLINE] "-admin@even.more.rude.net"[NEWLINE] will block mails coming from the entire domain rude.net and comig from all addresses that end with -admin@even.more.rude.net.

POP3.IPMAP.TAB
Description	This file control the global IP access permission to POP3 server if located into MAIL_ROOT path, and user IP access to its POP3 mailbox if located inside the user directory.
SYNTAX	"ipaddr"[TAB]"netmask"[TAB]"permission"[TAB]"precedence"[NEWLINE]
Ex.	"0.0.0.0"[TAB]"0.0.0.0"[TAB]"DENY"[TAB]"1"[NEWLINE] "212.131.173.0"[TAB]"255.255.255.0"[TAB]"ALLOW"[TAB]"2"[NEWLINE] 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.

SMTP.IPMAP.TAB
Description	This file control IP access permission to SMTP server.
SYNTAX	"ipaddr"[TAB]"netmask"[TAB]"permission"[TAB]"precedence"[NEWLINE]
Ex.	"0.0.0.0"[TAB]"0.0.0.0"[TAB]"DENY"[TAB]"1"[NEWLINE] "212.131.173.0"[TAB]"255.255.255.0"[TAB]"ALLOW"[TAB]"2"[NEWLINE] 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.

FINGER.IPMAP.TAB
Description	This file control IP access permission to FINGER server.
SYNTAX	"ipaddr"[TAB]"netmask"[TAB]"permission"[TAB]"precedence"[NEWLINE]
Ex.	"0.0.0.0"[TAB]"0.0.0.0"[TAB]"DENY"[TAB]"1"[NEWLINE] "212.131.173.0"[TAB]"255.255.255.0"[TAB]"ALLOW"[TAB]"2"[NEWLINE] 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.

MAILPROC.TAB
Description	store commands ( internals or externals ) that has to be executed on message file. The presence of this file is optional an if it does not exist the default processing is to store the message in user mailbox. Each argument can be a macro also : @@FROM will be substituted with the sender of the message @@RCPT will be substituted with the recipient of the message @@RRCPT will be substituted with the real recipient ( @@RCPT could be an alias ) of the message @@FILE will be substituted with the message file path ( the external command _must_ only read the file ) @@MSGID will be substituted with the ( XMail unique ) message id @@MSGREF will be substituted with the reference SMTP message id @@TMPFILE will create a copy of the message file to a temporary one. It can be used with "external" command but in this case it's external program responsibility to delete the temporary file. Supported commands : [EXTERNAL] "external"[TAB]"priority"[TAB]"wait-timeout"[TAB]"command-path"[TAB]"arg-or-macro"[TAB]...[NEWLINE] where : external = command keyword priority = process priority - 0 = normal -1 = below normal +1 = above normal wait-timeout = wait timeout for process execution in seconds - 0 = nowait if wait-timeout = 0 You must add a "wait" command at the end of MAILPROC.TAB to give the executed external commands the time to read the message file. This is coz such file is a temporary one that will be deleted when XMail exit from MAILPROC.TAB file processing. [MAILBOX] "mailbox"[NEWLINE] With this command the message will be push into local user mailbox. [REDIRECT] "redirect"[TAB]"address"[TAB]...[NEWLINE] Redirect message to internal or external addresses. [LREDIRECT] "lredirect"[TAB]"address"[TAB]...[NEWLINE] Redirect message to internal or external addresses impersonating local domain during messages delivery. [WAIT] "wait"[TAB]"timeout"[NEWLINE] Wait "timeout" seconds. This command is used to give external commands the time to read the temporary message file when such commands are lounched with wait-timeout = 0.
SYNTAX	"command"[TAB]"arg-or-macro"[TAB]...[NEWLINE]
Ex.

Command Line Configuration

Command Line Administration

You can use CtrlClnt to send administration commands to XMail from your command line. CtrlClnt is an executable file that let you administrate your XMail with the same commands as they described in remote administration section.

CtrlClnt [-snuptf] ...
where

-s server = set server address
-n port = set server port [6017]
-u user = set username
-p pass = set password
-t timeout = set timeout [60]
-f filename = set dump filename [stdout]
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

CtrlClnt will return 0 if the command is successful and any other number if not.
If the command is a query one, then the result will be printed to the dump file.

Let's see an example

XMail LINUX HOW-TO

version 0.0.2
by CyberUX

Contents

Before reading this HOWTO

What is XMail?

Get XMail

Install XMail on LINUX

Make a test to see what you 've got

Start/Stop/Restart

Configure XMail

Basic configuration

Set up root accounts

Login as root with telnet

Administrative commands

Main Server Configuration

TAB Files

Command Line Configuration

Command Line Administration

Extrenal Authentication

SMTP Client Authentication

Domain Message Filters

Mail Routing

XMail as a local mailer

What commands can XMail understand?

Tutorial 1: Make your own local email system

Configure Kmail for XMail

XMal GUIs make work a game

XMail LINUX HOW-TO

version 0.0.2by CyberUX

Contents

Before reading this HOWTO

What is XMail?

Get XMail

Install XMail on LINUX

Make a test to see what you 've got

Start/Stop/Restart

Configure XMail

Basic configuration

Set up root accounts

Login as root with telnet

Administrative commands

Main Server Configuration

TAB Files

Command Line Configuration

Command Line Administration

Extrenal Authentication

SMTP Client Authentication

Domain Message Filters

Mail Routing

XMail as a local mailer

What commands can XMail understand?

Tutorial 1: Make your own local email system

Configure Kmail for XMail

XMal GUIs make work a game

version 0.0.2
by CyberUX