Welcome to the XMail Handbook. This handbook is a beginner's guide to help get you through the initial setup of an XMail mail server on Linux. Since XMail runs on multiple platforms, the examples in this handbook may or may not work on your platform but the concepts are the same. This handbook is task oriented and is intended as a supplement to the the official XMail Manual. I assume that you have some basic knowledge of Linux but not too much. In fact many of you may be experienced Windows postmasters who are making the jump to a Linux based server. I intend to expand and enhance this guide as time and knowledge permit and hopefully end up with a full featured document at some point.
Why use XMail?
The one weakness of XMail is it's relative lack of documentation. The official manual is a great resource tool which provides a comprehensive listing of features, and there are a few HOWTOs that deal with specific issues. This handbook attempts to fill in the holes with step by step instructions to get you up and running.
There is an active, knowledgeable mailing list for XMail. I strongly recommend that anyone using Xmail join it and listen in. To subscribe send an e-mail to xmail-request@xmailserver.org with a blank subject line and the word subscribe in the message body. There is also an archive of this mailing list where you can search for postings containing specific keywords: XMail Archive. The archive can be very helpful and I urge you to search it before posting questions to the mailing list.
I'm ready if you are. Let's get started . . .
- Back To Top -
Before we get into the actual setup there are a few conventions used in this document that you should be aware of:
Commands typed at the shell prompt and examples of code look like this.- Back To Top -
The following sections cover the basic setup of an XMail server. By the end of this section you should have a working XMail server with one usable domain. The basic setup is not particularly difficult but it's important to get this part working correctly before you do any advanced configuration.
- Back To Top -
You can download the package you need from: http://www.xmailserver.org. The recommended way to install XMail is to download the *tar.gz source file and build your own binary. If you are using a standard Redhat or SuSE distro you should also be able to use the RPM package which will be easier for someone starting out. I've successfully installed using both methods and I recommend start out with the RPM if you can, but when it comes time to put your mail server on line, you should build your own binaries and replace the ones that came in the RPM package to ensure library compatibility.
su to root and cd to the directory containing the RPM file. Make sure the file has the executable flag set then install it:rpm -ivh xmail-1.22-1.i368.rpm
This will install a startup script in /etc/rc.d/init.d, replace the original /usr/sbin/sendmail with an XMail script, and create the /var/MailRoot and /var/MailRoot.sample directory structures.
su to root and cd to the directory containing the SRPM file. Make sure the file has the executable flag set and then unpack it:rpm -ivh xmail-1.22-1.src.rpm
This will copy a tar.gz file into either the /usr/src/packages/SOURCES or the /usr/src/redhat directory depending on your distro. You can then follow the tarball instructions.
tar -vxzf xmail-1.22.tar.gz
The Readme file is also the XMail manual so I recommend you get familiar with it now. The RPM package installs the Readme in /var/MailRoot/docs/ and tar.gz users will find it in the xmail-1.22/docs directory. You will want to refer to this file during the configuration process so you need to have a working knowledge of where to find things in it. Those of you who installed the binary rpm package can skip down to Section 5 if you like, although there's lots of information in the next few sections you may want to know later.
- Back To Top -
Choose your Makefile depending on the architecture of your machine and run make to build the executables:
make -f Makefile.lnx # for x86
make -f Makefile.slx # for SPARC
make -f Makefile.plx # for PPC
This builds XMail and it's tool set and then strips the executables. It also creates the basic MailRoot directory structure.
- Back To Top -
Time to get to the real work. You should su to root if you are not already. First you need to copy the MailRoot directory to it's working location. If you choose a directory other than /var for your installation, make sure the partition has enough space to handle the expected mail volume. Use the -a switch to ensure that empty directories and files are also copied:
cp -a MailRoot /var
Most of XMail's files are held in /var/MailRoot, which should be only accessible by root:
chown root /var/MailRoot
chgrp root /var/MailRoot
chmod 700 /var/MailRoot
Copy the binaries into the $MailRoot/bin directory:
cp CtrlClnt MkUsers sendmail XMail XMCrypt /var/MailRoot/bin
The CtrlClnt binary needs to be accessible to whomever is going to administer the xmail system. If this is someone other than root you should copy this file to a directory this administrator has access to:
cp CtrlClnt /usr/sbin
Copy the Manual to an appropriate place:
mkdir /usr/share/doc/xmail
cp docs/Readme.txt /usr/share/doc/xmail/Manual.txt
cp docs/Readme.html /usr/share/doc/xmail/Manual.html
Copy the SysV init script into the appropriate directory:
cp xmail /etc/rc.d/init.d # Redhat / Mandriva
cp xmail /etc/init.d # SuSE
Then link the script into the rc.d directories:
cd /etc/rc.d # Redhat / Mandriva
ln -s init.d/xmail rc0.d/K27xmail
ln -s init.d/xmail rc1.d/K27xmail
ln -s init.d/xmail rc2.d/K27xmail
ln -s init.d/xmail rc6.d/K27xmail
ln -s init.d/xmail rc3.d/S43xmail
ln -s init.d/xmail rc4.d/S43xmail
ln -s init.d/xmail rc5.d/S43xmail
cd /etc/init.d # SuSE
ln -s xmail rc0.d/K27xmail
ln -s xmail rc1.d/K27xmail
ln -s xmail rc2.d/K27xmail
ln -s xmail rc6.d/K27xmail
ln -s xmail rc3.d/S43xmail
ln -s xmail rc4.d/S43xmail
ln -s xmail rc5.d/S43xmail
- Back To Top -
You need to replace the original sendmail executable with the XMail version. If you don't have sendmail installed at all you can skip this step, but if it's installed it should be replaced. First, shut down the sendmail daemon and save the old executables under a different name:
mv /usr/sbin/sendmail /usr/sbin/sendmail.orig
Copy Xmail's sendmail executable to an appropriate place, and set it's SETUID bit so that it runs as root.
cp bin/sendmail /usr/sbin/sendmail.xmail
chmod +s /usr/sbin/sendmail.xmail
Copy the script that sets the environment and calls the executable. Make sure the x bit is set:
cp sendmail.sh /usr/sbin/sendmail
chmod +x /usr/sbin/sendmail
If your MailRoot directory is not in the default /var directory you need to edit the new sendmail script to insert the correct path for the MAIL_ROOT environmental variable. You will find that there are processes that send mail to "root" without specifying a host or a domain (assuming the default localhost.localdomain). This mail will end up 'frozen' unless you change the configuration files to re-direct it to a valid XMail account. These processes vary by distro but one that you always need to change is cron. You should edit your crontab file and set the MAILTO parameter to a valid mail account.
OK, the file installation is complete. You can take 5 and catch your breath.
- Back To Top -
First a word on XMail's configuration files in general. All of XMail's configuration files use the 'tab' character as a separator character (don't use spaces or extra tabs), and every line in a file must have a terminating 'return'. EVEN THE LAST ONE. The number of parameters changes from file to file, but the file format is always the same:
"settingname" [Tab] "parameter" [Tab] "parameter"... "parameter" [Return]
Because the 'invisible' characters are so important in these settings files you should use the CtrlClnt utility to edit them whenever possible. Also note that any line which begins with the "#" character is a comment or a setting which has been 'commented out'.
Use a text editor to open $MailRoot/server.tab. As you can see this is XMail's primary configuration file. It comes with default settings that are fine for a test setup. But I promised you a working domain so we need to make a few changes. We will configure our mail server using the local network domain as our primary domain. This is generally the best configuration especially if this mail server will serve additional virtual domains. You could also use the primary mail domain if it's different from the local network domain. First change the RootDomain parameter to your primary domain name:
"RootDomain" [Tab] "mydomain.org" [Return]
Go ahead and replace every instance of "xmailserver.test" with "mydomain.org". You will now have a setting that looks like this:
"PostMaster" [Tab] "root@mydomain.org" [Return]
If you want your root account to get the postmaster's mail your server.tab setup is complete. I prefer sending postmaster mail to another account so you may want to replace "root" with a different account:
"PostMaster" [Tab] "postmaster@mydomain.org" [Return]
Once you have a working configuration you may want to come back and a few changes to suit your needs, but this is enough to get you started.
- Back To Top -
XMail uses control accounts as administrative accounts to manage the server and it's domains. We need to set up at least one account that will be used to finish our server configuration. We'll use "postmaster" for the account name in our example. Select a complicated password and find its encrypted form with XMCrypt. We'll use "ciao" in this example:
/var/MailRoot/bin/XMCrypt ciao
Now edit $MailRoot/ctrlaccounts.tab removing the sample entry and inserting your account name and the encrypted password you just created using XMCrypt:
"postmaster" [Tab] "060c040a" [Return]
Important! Make sure you delete the sample entries before saving these files.
- Back To Top -
Start XMail with the following commands using the $MailRoot path for your system:
export MAIL_ROOT=/var/MailRoot
/var/MailRoot/bin/XMail -Md -Pl -Sl -Fl -Cl -Ll
These commands set the path to MailRoot and start XMail in debug mode. There are other command line switches which are documented in the manual. It's hard to tell in some fonts, but the second character in the switches is a lowercase "L". You will see the various XMail threads start up, and if you don't cough up any errors you have a working XMail server. Note that the debug messages print to stdout only and not to any log file. Leave XMail running in debug for now while you set up your domain and do some testing. When you're finished you can hit Ctrl-C and watch XMail shut down it's threads gracefully.
This is a good time to configure your system to start XMail during boot. You've already copied the start up script into the /etc/$ directory and created the links for SysV to use. You should take a look at this script now. If your MailRoot directory is not in the default /var directory you need to insert the correct path for the XMAIL_ROOT environmental variable. Look at the description of the command line parameters in the XMail manual. Use the XMAIL_CMD_LINE parameter to add any of these switches to your script. For example if you wish to enable all the logging options you could use this:
XMAIL_CMD_LINE="-Pl -Sl -Ql -Yl -Fl -Cl -Ll"
Now use your SysV Init editor (YaST2 in SuSE) to configure your system to call the script in the proper run levels.
- Back To Top -
In XMail all mail domains are virtual domains. Even though we have designated the local network domain as our primary domain in the server.tab file, we still need to create a virtual XMail domain by that name. In this example:
"myserver.mydomain.org" - The host name of the mail server.
"postmaster" - The name of a control account.
"ciao" - The control account password.
"mydomain.org" - The name of your mail domain.
Create the domain substituting your values for the ones in the example:
/usr/bin/CtrlClnt -s myserver.mydomain.org -u postmaster -p ciao domainadd mydomain.org
Deleting a domain works the same way:
/usr/bin/CtrlClnt -s myserver.mydomain.org -u postmaster -p ciao domaindel mydomain.org
Pretty easy, isn't it? Well it can get even easier than that. Once you have a working configuration you may want to look at some of the graphical front ends that you'll find on the XMail home page, but for right now we'll stick with the manual commands.
- Back To Top -
Since a mail server isn't very useful without users, lets learn how to create one. In this example:
"myserver.mydomain.org" - The host name of the mail server.
"postmaster" - The name of a control account.
"ciao" - The control account password.
"mydomain.org" - The name of your mail domain.
"newuser" - The name of the user you wish to add.
"newpassword" - The password for the new user.
We will create a user for the domain we just created. Use CtrlClnt to create the user account substituting your values for the ones in the example:
/usr/bin/CtrlClnt -s myserver.mydomain.org -u postmaster -p ciao useradd mydomain.org newuser newpassword U
You should use the plain text password here since CtrlClnt will encrypt it before saving the new user account. Deleting a user works the same way:
/usr/bin/CtrlClnt -s myserver.mydomain.org -u postmaster -p ciao userdel mydomain.org newuser
Congratulations! You've made it through the basic setup.
- Back To Top -
Now it's time to look at how to configure a few of the many XMail features. The manual has a description of the specifications for each task and you should refer to it for additional details if needed. In addition there are a number of different graphic front ends you can use to perform these tasks. These commands all use CtrlClnt and follow a similar pattern so I won't spend a lot of time repeating the same instructions. In the example below be sure to replace these placeholders with your own values:
"myserver.maildomain.org" - The host name of your mail server.
"postmaster" - The name of a control account.
"ciao" - The control account password.
When using CtrlClnt the spaces between the parameters are real spaces and not tabs and the parameters do not need to be in double quotes.
- Back To Top -
There are times when you want to redirect mail from one user account to another. This is commonly used to send mail for 'system' users such as "root" or "postmaster" to the box of the administrator who handles that mail. In this example:
"maildomain.org" - The name of the domain the user alias will belong to.
"useralias" - The name of the user account you want to re-direct.
"aliastarget" - The name of the 'real' user who will receive the mail sent to the alias account.
Use CtrlClnt to create the alias account substituting your values for the ones in the example:
/usr/bin/CtrlClnt -s myserver.mydomain.org -u postmaster -p ciao aliasadd maildomain.org useralias aliastarget U
If "aliastarget"is a user in "maildomain" then it can be an unqualified user name like "joe". If it's in another domain you need to use the fully qualified address like "joe@myotherdomain.org". In all cases "aliastarget" must be a user in a domain handled by this XMail server. A cool feature of the aliases.tab file is that you are allowed to substitute the "*" character for the domain name of the alias account. Say for example you are managing multiple domains and you want to create a "webmaster" alias for each domain and have all of them forward to the same administrator. There's no need to create a new "webmaster" alias for each domain since you can use the "*" wildcard like this:
/usr/bin/CtrlClnt -s myserver.mydomain.org -u postmaster -p ciao aliasadd "*" webmaster aliastarget
Note that in this case you must include the double quotes around the wildcard.
- Back To Top -
Deleting an alias is accomplished using a similar command where:
"maildomain.org" - The name of the domain the user alias belongs to.
"useralias" - The name of the user alias you want to deleate.
Use CtrlClnt to delete an alias account substituting your values for the ones in the example:
/usr/bin/CtrlClnt -s myserver.mydomain.org -u postmaster -p ciao aliasdel maildomain.org useralias
- Back To Top -
Each custom domain has a tab file that contains one or more lines defining how this domain should be handled. List the contents of a custom domain files where:
"customdomain.org" - The name of the domain you wish to list.
Use CtrlClnt substituting your values for the ones in the example:
/usr/bin/CtrlClnt -s myserver.mydomain.org -u postmaster -p ciao custdomget customdomain.org
- Back To Top -
Custdomset is a very powerful tool which is used to customize the handling of a domain. It can call a number of different commands that have arguments which can also be macros. In general custom domain handling is an advanced topic outside the scope of this guide, but since configuring your server as a secondary mail server is a common task I'll cover it here. You should check the manual for details on the other commands and macros you can use with custdomset.
Every primary mail server should have a backup which makes setting up a secondary mail server is one of the most common tasks a postmaster performs. The first step is to see that the name servers, which have authority for this domain, list your mail server as a secondary server. Otherwise the rest of the Internet will have no idea your server is willing and able to accept mail for this remote domain. You will probably have to rely on another administrator to configure this on a remote name server, but if it's your responsibility to do this you will need to add a line to the zone file for this domain listing your mail server after the primary server:
MX 5 primarymailserver.otherdomain.org.
MX 10 myserver.mydomain.org.
Note that you may use different numbers to identify the priority level of your server (you could be a tertiary server) as long as the number for your server is higher than that of the primary server. Don't forget to restart the named daemon to reload the updated zone file. Also remember that name servers cache information and any changes to the zone file may take a couple days to propagate across the web.
Now you need to configure XMail to accept mail for this remote domain. You will use CtrlClnt for this, but unlike other tasks, adding a custom domain is a multi-step process. In this example:
"customdomain.org" - The name of the secondary domain you wish to add.
"smtp.customdomain.org" - The name of the smtp server for this secondary domain.
Create a custom domain:
/usr/bin/CtrlClnt -s myserver.mydomain.org -u postmaster -p ciao custdomset customdomain.org
CtrlClnt will now prompt you for the command line you wish to enter. Add a line that tells XMail to accept and relay messages for this domain:
"smtprelay" [Tab] "smtp.customdomain.org" [Return]
You can leave the CtrlClnt command prompt and return to the shell prompt:
[Ctrl][D]
CtrlClnt saves the command to the file: $MailRoot/custdomains/customdomain.org.tab. If the primary server is prone to lengthy outages you may want to consider using the command line switches -Qt and -Qr on the secondary server to increase the time between retries and increase the number of retries.
There is no command to delete a custom domain so you need to do it manually by deleting the .tab file in $MailRoot/custdomains and restarting XMail.
- Back To Top -
A pop3 drop is a way to automatically forward mail from a remote pop3 server to your local XMail domain. In this example:
"localdomain.org" - The domain of the local user account you're linking to.
"localuser" - The name of the local user account you're linking to.
"pop3.isp.com" - The name of the remote mail server.
"remoteruser" - The name of the remote user account.
"remotepassword" - The password for the remote user account.
Now we're going to use all the parameters in a single CtrlClnt command to create the link:
/usr/bin/CtrlClnt -s myserver.mydomain.org -u postmaster -p ciao poplnkadd localdomain.org localuser pop3.isp.com remoteuser remotepassword CLR
This will set up an automatic synchronization between the local XMail server and your pop3 account at pop3.isp.com, synchronizing every 2 minutes by default. If your ISP supports APOP authorization substitute APOP for CLR above.
- Back To Top -
Each user's mail can be processed according to a mailproc.tab file that contains one or more lines defining how this user's mail should be handled. List the contents of a mailproc.tab file where:
"maildomain.org" - The name of the domain the user belongs to.
"mailuser" - The name of the user.
Use CtrlClnt substituting your values for the ones in the example:
/usr/bin/CtrlClnt -s myserver.mydomain.org -u postmaster -p ciao usergetmproc maildomain.org mailuser
- Back To Top -
Change a user's password from the command line where:
"maildomain.org" - The name of the domain the user belongs to.
"mailuser" - The name of the user.
"mailuserpass" - The new user password.
Use CtrlClnt substituting your values for the ones in the example:
/usr/bin/CtrlClnt -s myserver.mydomain.org -u postmaster -p ciao userpasswd maildomain.org mailuser mailuserpass
- Back To Top -
Usersetmproc does for users what custdomset does for domains. It is a very powerful tool which is used to customize the handling of a user account (I can't explain the different naming convention). It can call a number of different commands that have arguments which can also be macros. As with custdomset, it is an advanced topic generally outside the scope of this guide, but forwarding mail to another account is a common use so I'll cover it here. You should check the manual for details on the other commands and macros you can use with usersetmproc. You will use CtrlClnt for this, but adding a custom domain is a multi-step process. In this example:
"maildomain.org" - The name of the domain the user belongs to.
"mailuser" - The name of the user.
"otheruser@otherdomain" - The mail account you wish to forward the mail to.
Create the mailproc.tab file for this user:
/usr/bin/CtrlClnt -s myserver.mydomain.org -u postmaster -p ciao usersetmproc maildomain.org mailuser
CtrlClnt will now prompt you for the command line you wish to enter. Add a line that tells XMail to redirect messages to another account:
"redirect" [Tab] "otheruser@otherdomain" [Return]
You can leave the CtrlClnt command prompt and return to the shell prompt:
[Ctrl][D]
CtrlClnt saves the command to the mailproc.tab file in the user's directory. There is no command to delete mailproc.tab files, so if you need to you will have to do it manually.
- Back To Top -
You can use XMail's "filters.in.tab" and "filters.out.tab" configuration files to run filters, anti-spam scripts, anti-virus programs, or just about anything else you can imagine. The "filters.in.tab" file calls scripts that are run on each incoming mail message and "filters.out.tab" calls scripts that run on outgoing mail. The XMail filter hooks are both it's strongest and weakest feature. While they allow you to use scripts to process mail virtually any way you like, individuals who don't write code must rely on the generosity of others to create and donate scripts for them to use. Fortunately a number of people have done this and in this section I'll show you how to install a few of the common ones.
- Back To Top -
The XM_Fprot_Filter uses a bash script to run XMail messages through the F-Prot anti-virus scanner. It is easy to install and works well on low and medium volume servers.
There are a couple of packages you need before installing the script:
F-Prot anti-virus package: http://www.f-prot.com/
XM_Fprot_Filter package: http://xmail.libre-essai.com/
You should now su to root and begin installation:
Download and install the F-Prot anti-virus package and test it. If you install the RPM package the installation directory will be /usr/local/f-prot. See the package documentation for installation and testing instructions.
Extract the XM_Fprot_Filter tar archive to the $MailRoot/filters directory:
tar -vxz -C /var/MailRoot/filters -f XM_Fprot_Filter.tar.gz
Next we need to configure the filter and create the connection to it from XMail.
Edit $MailRoot/filters/XM_Fprot_Filter/XM_Fprot_Filter.sh according to your preferences and needs:
You should review the $MailRoot/filters/XM_Fprot_Filter/MessageToRecipient.txt.* file and edit it according to your needs.
Create a file named XM_Fprot_Filter.tab in the $MailRoot/filters directory. Insert the following line using the correct path to MailRoot:
"/var/MailRoot/filters/XM_Fprot_Filter/XM_Fprot_Filter.sh" [Tab] "@@FILE" [Tab] "@@FROM" [Tab] "@@RCPT" [Return]
Edit the $MailRoot/filters.in.tab file. Add a line pointing to the tab file you just created. It's a good idea to put this line before any spam filter parameters:
"*" [Tab] "*" [Tab] "0.0.0.0/0" [Tab] "0.0.0.0/0" [Tab] "XM_Fprot_Filter.tab" [Return]
Save your changes and the filter should be working. No need to restart XMail.
Send a test virus file to see if the filter is working correctly. You can get test virus file at http://www.eicar.org
In case of problems, run Xmail in debug mode:
$MailRoot/bin/XMail --debug -Md
That wasn't too bad, was it? Once you've installed a couple different filters, you'll see that while there are many different ways to implement filters, they are all called by simple tab file entries making them easy to understand and troubleshoot.
- Back To Top -
In this section we we focus on a script written by Peter Lindeman which allows XMail to access a number of popular anti-virus programs. It requires more effort to set up than the XM_Fprot_Filter package but it can be used with more anti-virus packages and scales well even with thousands of accounts and tens of thousands of messages a day.
First there are a number of prerequisites for installing the script:
You need at least one of the following anti-virus packages:
Perl 5.8.0: http://www.perl.org/
Mail-Sendmail perl script: http://www.cpan.org/
Digest-Md5 perl script: http://www.cpan.org/. The version included in Perl 5.8.0 can be used as well.
Switch perl script: http://www.cpan.org/
Download the anti-virus script at http://www.lindeman.org/filters.html. You'll find the link to the script at the bottom of the page.
You should now su to root and begin installation:
Download and install at least one of the anti-virus packages and test it. See the documentation for the package to get installation and testing instructions.
If you don't already have Perl 5.8.0 or higher, you need to install it. You need to follow the installation instructions included with the package. Remember that all your perl scripts need to point to your new perl installation.
Install the Mail-Sendmail perl script:
perl -MCPAN -e 'install Mail::Sendmail'
Install the Digest-Md5 perl script:
perl -MCPAN -e 'install Digest::MD5'
Install the Switch perl script:
perl -MCPAN -e 'install Switch'
Extract the anti-virus script tar archive in the directory of your choice.
Filter install for XMail <= XMail 1.12
Filter install for XMail >= XMail 1.14
our $xmail_version = 116;
Otherwise un-comment:
our $xmail_version = 115;
Save your changes and the filter should be working. No need to restart XMail.
Send a test virus file to see if the filter is working. You can get test virus file at http://www.eicar.org
In case of problems, run Xmail in debug mode:
$MailRoot/bin/XMail --debug -Md
Lindeman's script is well written, well supported, and free, so once it's installed you can forget about it and move on to other projects.
- Back To Top -
SpamAssassin is a popular mail filter which uses a number of heuristic tests to identify unsolicited e-mail commonly know as spam. It is included with many distributions including Redhat and SuSE.
There are a couple of prerequisites:
If you don't have the RPM already, you need to download the SpamAssassin archive: http://spamassassin.org/
Download Don Drake's filter script: http://www.drakeconsult.com/xmail/
If your distro includes it you can install the RPM package. Otherwise you need to su to root and build the application:
Download the tarred archive and extract it in the directory of your choice:
tar -vxzf Mail-SpamAssassin-2.xx.tar.gz
cd Mail-SpamAssassin-2.xx
Take a look at the README and INSTALL files for any system specific instructions or options. Run the perl configuration script then make and install the package:
perl Makefile.PL
make
make install
Extract the filter script to a directory of your choice:
tar -vxzf sa_filter-1.x.tar.gz
Copy the script and the tab file to the appropriate directories in the XMail installation:
cp sa_filter.pl /var/MailRoot/bin
cp safilter.tab /var/MailRoot/filters
XMail requires the SpamAssassin daemon "spamd" to be running to use the filter, so this is a good time to configure your system to start spamd at boot using SysV init or the tools of your choice. Installation of the filter is pretty straightforward:
Take a look at sa_filter.pl to make sure the XMAIL_LOG_PATH variable is set to the correct path for your XMail installation.
Check the safilter.tab file to ensure that the path to MailRoot is correct.
Edit your filters.in.tab file by adding the following line:
"*" [Tab] "*" [Tab] "0.0.0.0/0" [Tab] "0.0.0.0/0" [Tab] "safilter.tab" [Return]
Save your files and you're finished. There's no need to restart XMail.
- Back To Top -
The Ecartis mail list manager is a full featured tool which shares the XMail philosophy of high performance binaries, modular design, and flexibility. It also shares the same weakness of limited documentation so I'll give a fairly detailed explanation here. While Ecartis is solid, it is no longer actively developed and is in "maintenance mode" according to it's maintainers.
There are some prerequisites for installation. It is important to note that some of these files have been modified to improve security and are different from previous versions you may find on other sites. Please use these modified files only:
The current Ecartis snapshot rpm or tar.gz file from: http://www.ecartis.org/
A small shell script: ecartis.sh
A source file to create a binary which converts XMail spool files to e-mail format: http://www.xmailserver.com/econv.c
A source file to create a trivial wrapper for Ecartis: swrap.c
A perl script which is a cmdalisases generator for Ecartis: lisset.pl
You should now su to root and begin installation:
You need to create a user and and a group named "ecartis" which will become the owner of the Ecartis files and directory tree. Ecartis is a little unusual in that the default installation directory is /home/ecartis. If you want to install to a different directory you should modify the "-d" parameter in the useradd command:
groupadd -r ecartis
useradd -g ecartis -d /home/ecartis -s /bin/false -r ecartis
Ecartis is available as either an RPM package or as a tarred archive.
Install using RPM to the default location the usual way:
rpm -ivh ecartis-1.0.0-snap20030814.i386.rpm
If you wish to install in a different directory use the "--prefix" switch:
rpm -ivh ecartis-1.0.0-snap20030814.i386.rpm --prefix /mydir/ecartis
If you want to build your own binary you can, but this might require some knowledge of C++ and configuring a make file. First extract the archived files:
tar -vxzf ecartis-1.0.0-snap20030814.tar.gz
cd ecartis-1.0.0
Rename Makefile.dist to Makefile and edit it if you wish. You should at least review it before executing make:
make
make install
This will make and install the Ecartis files in the ecartis-1.0.0 directory. If your build is successful you can run the list manager here or you can move the files and directories you just created to your preferred location.
Compile econv.c and swrap.c:
gcc -o econv econv.c
gcc -o swrap swrap.c
There is a security issue with Ecartis we need to address. While the installation is owned by Ecartis. it is called by XMail which is running as root. We need to provide some more security by placing the executables in a root owned directory and then wrap Ecartis with the swrap script so that Ecartis actually runs as user "ecartis". Make a directory named "bin" in the ecartis directory.
Copy ecartis, ecartis.cfg, ecartis.sh, econv, lisset.pl, and swrap to the directory you just created which is "/home/ecartis/bin" by default.
Now make sure the owner, group, and permissions are all correct:
chown -R root bin
chgrp -R root bin
chmod -R 0644 bin/ecartis.cfg
Now that you have all the files you need it's time to start configuration. In our examples:
"smtphostname" - The host name of your smtp server.
"maildomain.org" - The name of your mail domain.
"admin" - The user name of the list administrator.
"postmaster" - The user name of the list owner.
"mylistname" - The name of the mailing list you are creating.
Start by editing the ecartis.cfg file. There are lots of settings you can leave alone for now and come back to later, but there are a few required changes you need to make now:
Change "mailserver" to the name of the smtp host:
mailserver = smtphostname
Change "listserver-address" to the name of your domain:
listserver-address = ecartis@maildomain.org
Change "listserver-admin" to the list administrator's address:
listserver-admin = admin@maildomain.org
Change "list-owner" to a valid mail address:
list-owner = postmaster@maildomain.org
Edit the ecartis.sh script to use the uid and gid of ecartis on your system.
Create a new list:
/home/ecartis/bin/ecartis -newlist mylistname
You need to run the lisset.pl script to create the cmdaliases for the list. A cmdalias is a tab file that will be run when XMail receives mail with the command name in place of a user name. When XMail encounters mail addressed to one of these aliases it reads the associated tab file and forwards the mail to Ecartis and it's lists. You need to run the lisset.pl script every time you create a new list:
perl /home/ecartis/bin/lisset.pl --mail-root /var/MailRoot --ecartis /home/ecartis/bin/ecartis.sh --list-name mylistname --domain maildomain.org --admin admin@maildomain.org
Finally you need to create a new text file named ecartis.tab in your /var/MailRoot/cmdaliases/maildomain.org directory. Insert a single line of text:
"external" [Tab] "0" [Tab] "0" [Tab] "/home/ecartis/bin/ecartis.sh" [Tab] "@@TMPFILE" [Return]
Go into the /home/ecartis/lists/mylistname directory and edit the config file as needed.
Test your configuration by sending a test message to ecartis@maildomain with the subject "help".
You should now have a functioning Ecartis mailing list manager. I need to thank Davide Libenzi and Sasa Stupar for writing the scripts referenced here and posting instructions on how to set this up. They did all the hard work and get all the credit. You, on the other hand, still have much of your work ahead of you configuring Ecartis and setting up your lists, but at least your interface with XMail is complete.
- Back To Top -
The Mailman mail list manager is a Python based list manager that supports web management by both users and administrators. The web administration features requires integration with a web server so Mailman is a bit more complicated to set up than Ecartis and requires access to a web server. This package is probably not a good choice for those of you who are new to both XMail and Linux.
As always there are some prerequisites for installation:
The current Mailman stable release tarball from: http://www.gnu.org/software/mailman/mailman.html
A web server that supports the CGI/1.1 API such as Apache.
Python 2.2.1 or higher. If you installed Python by RPM you must install the Python-devel package also.
Two small python scripts: mailman and update-mailman-lists
One small .tab file: mailman-template.tab
A source file to create a binary which converts XMail spool files to e-mail format: http://www.xmailserver.com/econv.c
You should now su to root and begin installation:
You need to create a user and and a group named "mailman" which will become the owner of the Mailman files and directory tree:
groupadd -r mailman
useradd -g mailman -s /bin/false -r mailman
Create the Mailman directory tree. The default location is "/usr/local/mailman". Change the group name to "mailman" and make sure the permissions are set correctly:
chgrp mailman /usr/local/mailman
chmod 2775 /usr/local/mailman
You don't need to be root any longer so su to mailman or another user in group mailman.
The Mailman package is currently included in most Linux distributions but I strongly recommend against trying to use these packages. I've spent many hours trying to get the packages from Redhat, SuSE, and Mandriva to work with XMail and I've never been successful. If you already have Mailman installed you should remove it and start from scratch. So, download the archive and extract it in a directory to which this user has write permissions:
tar -vxzf mailman-2.1.x.tgz
cd mailman-2.1.x
The INSTALL file in this directory has detailed instructions on how to configure and install Mailman. You should read it and 'configure' Mailman with the following options plus any others you may need. If you are not going to install Mailman in the default directory, you need to use the --prefix option. The '--with-cgi-gid' value should be the group under which Apache runs:
./configure --prefix=/mydirectory/mailman --with-mail-gid=root --with-cgi-gid=apache
Now you can build the app. If you have problems here, look at the configuration options in the INSTALL file:
make
make install
Run a quick test to see if the file permissions are correct. If check_perms finds errors run it again (as root or mailman) until no error are reported:
cd /usr/local/mailman
bin/check_perms -f
Copy the Mailman graphic files to an appropriate directory on your webserver, usually "icons":
cp /usr/local/mailman/icons/*.{jpg,png} /path/to/icons/directory
Compile econv.c:
gcc -o econv econv.c
Copy econv, and the two python scripts mailman and update-mailman-lists, to your $MailRoot/bin directory which is "/var/MailRoot/bin" by default. Make sure the x bit is set, and edit the python scripts to make sure that the XMAIL_HOME and MAILMAN_HOME variables point to the correct locations.
Copy the mailman-template-tab file to the $MailRoot/bin directory, and edit this file as well to reflect the correct location of the mailman python script you just copied and edited.
Installation is complete. Let's start the configuration phase by setting up the webserver. These commands are for Apache users but you'll need to perform a similar configuration for any server. You need to be a privileged user to edit httpd.conf. Add the following lines:
Configure the webserver to give $/mailman/cgi-bin permission to run CGI scripts:
ScriptAlias /mailman/ "/usr/local/mailman/cgi-bin/"
Set the webserver to point to the Pipermail public mailing list archives:
Alias /pipermail/ /usr/local/mailman/archives/public/
In order for the archives to display correctly, you need to set a couple of options for this directory:
<Directory /usr/local/mailman/archives/public/>
Options FollowSymLinks Indexes
AllowOverride None
Re-start Apache to load the new options.
Now it's time to configure Mailman, so cd to the Mailman 'home' directory and let's change some settings:
The main configuration file for Mailman is Defaults.py in the Mailman subsudirectory. Look through this file for any settings that are incorrect. Most of these settings aren't important to us now, but there are a few you may need to change. Do not make changes directly to the Defaults.py file. Instead add entries to the bottom of the mm_cfg.py file which overrides the default settings:
If you placed the graphic files in a location other than "icons" you need to tell Mailman where they are:
IMAGE_LOGOS = '/icondirectory/'
If the default host isn't correct you need to change it. Make sure to use quotes:
DEFAULT_EMAIL_HOST = "mydomain.org"
DEFAULT_URL_HOST = "www.mydomain.org"
add_virtualhost(DEFAULT_URL_HOST, DEFAULT_EMAIL_HOST)
Create the 'site-wide' mailing list. Enter the e-mail address and the password but don't worry about setting up the aliases right now. We'll get to that shortly:
bin/newlist mailman
Review the site list template data/sitelist.cfg then configure your site list:
bin/config_list -i data/sitelist.cfg mailman
Create a 'site-wide' master password:
bin/mmsitepass -c mypassword
Mailman uses cron for some of it's basic functionality so you need to create the Mailman entries in crontab:
crontab -u root cron/crontab.in
You need to configure Mailman to start at boot. With a SysV system you should copy the Mailman boot script to the "/etc/rc.d/init.d" or "/etc/init.d" directory then use your SysV init program to create the links to enable it at startup:
cp scripts/mailman /etc/init.d/mailman
You can now start mailman:
/etc/init.d/mailman start
We're in the home stretch! Now we'll configure the interface between XMail and Mailman.
The update-mailman-lists script will maintain the correct set of cmdaliases for us. First su to root, then simply run the command:
/var/MailRoot/bin/update-mailman-lists
The update-mailman-lists script will create symlinks to the mailman-template.tab file for all aliases required for mailman. The mailman-template.tab file causes XMail to use the /var/MailRoot/bin/mailman script to handle all mailman email. This script in turn uses the econv program to pass email to mailman in the correct format.
You can verify that the correct symlinks have been created in your cmdalias subdirectories. You'll need to run the update-mailman-lists command whenever you add or remove mailman lists, or you can run the command automatically in a cronjob. If you know a bit of Python code, you could even write a Mailman MTA plugin to do it automatically whenever you add or remove a list.
That's it, you made it! You should now have a functioning Mailman mailing list manager. I need to thank Sasa Stupar and Toby Reiter for posting instructions on how to set this up. I'd also like to thank Martijn Pieters who wrote the perl scripts I used here. I would have never figured this out myself. You still have to do all your mailing list setup, but the worst is over! Good luck, and if you have time let me know any tips I can pass on to future users.
- Back To Top -