Mailismus - Admin Guide

2.1 - Unix Installation

Mailismus is open source and you can build it yourself, but it is also available as a binary package, and that is the subject of this section.
The Unix installation is based on a generic all-platforms ZIP, which you simply unpack.

2.1.1 - Prerequisites

The only external dependency is a Java JRE (full SDK not necessary).
If not already on your system, it can be downloaded from Oracle.

The JAVA_HOME environment variable should ideally be set, but if it isn't, then the java executable must at least be on your Path. This can be handled in the init script in step 2.1.2 below.

2.1.2 - Install Mailismus

The generic all-platforms ZIP archive is offered in two formats: as both an actual .zip file and a .tar.gz compressed tarfile.
Installing Mailismus consists of simply unzipping/untarring this archive in place, and running it from there. You may extract it to wherever you wish, but for our purposes let's assume it's unpacked into /opt/mailismus, which we shall refer to as MTAHOME for the remainder of this chapter.

Note that a copy of this admin guide can be found under MTAHOME/docs.

Mailismus can now be started as simply as this

sh /path/to/MTAHOME/bin/mta.sh start

And it can be halted with the corresponding stop command.

Note that you have to be root to start Mailismus, as it binds to privileged TCP ports to listen for SMTP, POP3 and IMAP connections.

In general you will want Mailismus to start automatically on system boot, so you will need to integrate it into the OS boot process.
That is described here, but before doing this you should work through section §2.1.3 to verify that Mailismus starts up ok manually.

First create the file /etc/init.d/mailismus by pasting in the content below.
You will have to edit the mta.sh line to specify the actual pathname of your Mailismus installation.
Depending on whether JAVA_HOME and/or path is already globally defined elsewhere, you should also comment out or edit the JAVA_HOME assignment as appropriate, to enable Mailismus to locate the java executable (typically at $JAVA_HOME/bin/java)

#!/bin/sh
### BEGIN INIT INFO
# Provides: mailismus
# Required-Start: $network $remote_fs $syslog
# Required-Stop: $network $remote_fs $syslog
# Default-Start: 3 5
# Default-Stop: 0 1 2 6
# Description: Mailismus mail server
### END INIT INFO

export JAVA_HOME=/path/to/JDK_or_JRE
sh /path/to/MTAHOME/bin/mta.sh $*

There are several ways to enable this init script, depending on your flavour of Unix/Linux.

If you are on a systemd-based Linux system, you can configure Mailismus into its boot sequence by running this from the Linux shell:
systemctl enable mailismus
You could choose to add a systemd config file instead of using the above init.d script before running systemctl, but that is beyond the scope of this guide. The above systemctl command will still work with an init.d script in a backwards-compatible mode, possibly with some harmless warnings that this is not a native service.
The older chkconfig mechanism is supported on an even larger range of Linux distros, and should still work in a compatible manner on systemd-based ones.
Run this from the Linux shell: chkconfig mailismus on
Finally, there is the old-school mechanism of rc.d symbolic links, which works on all Linux and non-Linux Unix systems.
This requires the creation of Start and Stop symbolic links to /etc/init.d/mailismus in the appropriate run-level scripts directory - typically rc3.d and rc5.d The symbolic links should be named so as to start Mailismus late in the bootup sequence, and stop it early during shutdown.
Eg. /etc/rc.d/rc3.d/S99mailismus (start) and /etc/rc.d/rc3.d/K01mailismus (stop)
Note that the exact rc3.d and rc5.d paths may differ between the various flavours of Unix.

NB: Whichever bootup mechanism you choose, do not simply make /etc/init.d/mailismus a symbolic link to MTAHOME/bin/mta.sh, as the latter processes its pathname to locate the Mailismus config and does not contain the LSB comment block that is required by many Linux init variants.

You can now start and stop Mailismus as follows:
/etc/init.d/mailismus stop
/etc/init.d/mailismus stop

Alternatively, on a systemd-based system you can also use the following:
systemctl start mailismus ... start Mailismus
systemctl stop mailismus ... stop Mailismus
systemctl -l status mailismus ... show Mailismus status

2.1.3 - Initial Setup

Unpacking the binary download into MTAHOME will have left you with a runnable bare-bones Mailismus configuration, and we recommend that you go through the initial steps below to verify that this works as expected, before delving into the reference documentation to configure extra functionality.

Prepare Config
Open MTAHOME/conf/mailismus.xml in a text editor, and observe the announcehost setting in the leading mta/application config block (see §4.1).
This is the hostname which Mailismus will announce in its SMTP HELO dialogue when it connects to other mail servers, and you should note that they may well validate it, and reject your connections if this name doesn't match your IP.
It is initially set to %SYSNAME% which means Mailismus will obtain it automatically from the underlying OS, but you should beware that if your mailserver is sitting on a private IP subnet behind a NAT firewall, the local hostname is not what external mailservers will see. If so, then edit the announcehost value to set it to your official external hostname.

Mailismus itself can also be configured to validate the announced hostname in incoming connections, with varying degrees of rigour, although by default it won't validate it.
See the validate_helo setting in section §4.4.4 for the possibilities and this will also give you a flavour of the level of validation that other servers could apply to your announced hostname.

The MTAHOME/conf/naf.xml config file is ready to run as shipped, and will create all its data (queued messages, etc) under MTAHOME/var.
The var directory tree will be created automatically at runtime, so you don't need to create any folders in advance.
Verify Java Process Runs OK
Run the Mailismus startup script: sh /path/to/MTAHOME/bin/mta.sh start
Mailismus should start up and create the MTAHOME/mta-boot.log logfile, plus several more under MTAHOME/var/logs/trace (one per Dispatcher).
See the NAF Paths lines in mta-boot.log (which is basically a stdout capture) to verify where the other logfiles actually got put.

As a quick sanity test, look for obvious errors that don't require any knowledge of Mailismus to spot, for example:
• The Mailismus startup script should not have produced any output to screen, particularly any obvious error messages. All output should have gone to the logfiles mentioned above.
• A quick glance at those logfiles should also indicate whether Mailismus started smoothly, or whether there was a show-stopping problem.

Having passed this cursory inspection, you can stop Mailismus from the Unix command line: sh /path/to/MTAHOME/bin/mta.sh stop
Verify that Mailismus has stopped, and no obvious errors appeared on screen or in the log files.
Send Email Message
NB: This step tests the outbound SMTP-relay functionality. If you are using Mailismus purely as a mailbox access server (ie. IMAP or POP3 server), then it is not applicable.

Configure your email client (ie. Outlook, Thunderbird, or whatever) to point at the Mailismus host as the outgoing SMTP server and send an email.

Transcripts are enabled in the initial MTAHOME/conf/mailismus.xml config file, so assuming you followed the instructions above and haven't altered that, you should be able to follow your email's progress through the MTA by viewing them.
They will be in MTAHOME/var/logs/transcripts and the Submit one will show your message being accepted into Mailismus, while the Delivery one will show it being forwarded on to its final destination (or not).

Once Mailismus has delivered the message onwards, the audit logs under MTAHOME/var/logs/audit will formally record its final status (see delivered.log)

If there was a problem, the regular application logs under MTAHOME/var/logs/trace should have all the details.
Verify NAFMAN
The final check is to point your browser at the web-based management app on port 13000 of the Mailismus machine (eg. http://localhost:13000).
Verify that the NAFMAN management page appears. It displays real-time monitoring info that you can explore later.

In the unlikely event you want to change the default port of 13000, the NAFMAN baseport config setting (see section §5 of the NAF Guide) provides the means to do so.
See section §5 of the NAF Guide for more info on NAFMAN.

2.1.4 - Next Steps

You now have a functioning mail server, with working defaults that enable the sending and receiving of messages.

If you want to provide mailboxes for local users as well, the next step is to configure the Message Store (see section §4.2) followed by enabling the IMAP server (section §4.7) and/or the POP server (section §4.8).
It is likely you would only want one or the other in regards to the IMAP and POP servers, but they are not mutually exclusive and you could have both, to support the preferences of all your users.
Whichever of them you choose, the POP Downloader (see section §4.9) may be used with either, to consolidate messages held at either mailservers into your Mailismus mailboxes.

Once Mailismus is bedded in, you will probably want to turn off transcript logging, which comes enabled by default.
This is simply a matter of setting enabled="N" in the transcript elements of MTAHOME\conf\mailismus.xml.

You may also want to vary the logging levels configured in MTAHOME\conf\logging.xml.
INFO is the neutral level, while TRC, TRC2 and TRC3 show progressively more detail.