2.1 - Windows Installation

2.1.1 - Prerequisites

While external Mailismus dependencies are limited, it does need some basic runtime components.
These need to be installed before you proceed further:


2.1.2 - Install Mailismus

There are ways to install Mailismus on Windows:

To summarise, the generic ZIP is the mail server and can stand on its own.
The MSI installer is basically a wrapper around the generic ZIP, providing a native Windows installer and a Windows Service to start and stop the mail server.

A copy of this admin guide can be found under MTAHOME\docs.


2.1.3 - Initial Setup

The installation should have left you with a runnable bare-bones Mailismus configuration, and we recommend that you run through the initial steps below to verify that this works as expected, before delving into the reference documentation to configure loads of extra functionality.
As we're not configuring a licence at this stage, Mailismus will run in trial mode. If you do already have a licence, you can of course configure it now, but these setup tests don't require it.

  1. Prepare Config
    Open MTAHOME\conf\mailismus.xml in an editor, and observe that it sets announcehost (see §4.1) to a place-holding dummy value in the leading mta/application block.
    This config item relates to the common situation where your mailserver has a private IP and communicates with the public Internet via a NAT firewall, in which case the hostname it needs to announce in various SMTP dialogues will not be its own (as that is a private local hostname).
    If this describes your situation, then edit the leading announcehost element to set it to your official external hostname.
    If not, then set it to your actual hostname, or to %SYSNAME% if you want the hostname to be obtained automatically.
    Either way, the dummy initial announcehost value clearly won't work, so it needs to be changed now.

    The MTAHOME\conf\naf.xml config file is ready to run as shipped, but one thing you may wish to note is that it will create all its data (queued messages, etc) under MTAHOME\var.
    If this initial setup does not suit you, then edit naf.xml to set the dirpaths/var path (see NAF Guide §3.2).
    For simplicity, we shall continue to refer to the var path as its default setting of MTAHOME\var, but bear in mind if you have modified this.
    Note that the var directory tree will be created automatically at runtime, so you don't need to create any folders in advance.

  2. Verify Java Process Runs OK
    Launch the DOS Command Prompt and go to the MTAHOME directory. Then enter this command:

    bin\mta.bat start

    Mailismus will start up and create the MTAHOME\mta-boot.log logfile, plus 3 more under MTAHOME\var\logs\trace (see the NAF Paths lines in mta-boot.log to verify where the other logfiles actually got put).

    The object of this step is to conduct a simple sanity test, ie. look for obvious errors that don't require any knowledge of Mailismus to spot.
    • The mta.bat script should not have produced any output to screen, particularly any obvious error messages. All output should have gone to the 5 logfiles mentioned above.
    • A cursory glance at those logfiles should also indicate whether Mailismus started and stopped smoothly, or whether there was a show-stopping problem.

    Having passed this cursory inspection, you can stop it by running

    bin\mta.bat stop

    from MTAHOME in another DOS console window.
    Verify that Mailismus stopped, and no obvious errors appeared on screen or in the log files.

    If you didn't download the native Windows MSI, you will routinely start and stop Mailismus as described here, from now on.
    This is also the way you would issue NAFMAN commands, even if you do have an MSI install. In fact, the STOP command is simply an ordinary NAFMAN command, and any command other than "start" will be interpreted as a NAFMAN command.

  3. Verify Actual Config
    We need to verify what various auto-calculated config settings actually got resolved as, and we shall use the logfiles under MTAHOME\var\logs\trace for this purpose.

    Verify DNS Servers:
    If you did not explicitly specify any DNS servers in MTAHOME\conf\naf.xml (see NAF Guide §6) then they will have automatically been obtained from the OS.
    The Submit task's logfile (it will be called something like mta-submit-YYYYMMDD.log) will contain the actual settings. Look for text like DNS-Resolver: Selected DNS servers.
    If the resulting servers are not appropriate, or Mailismus didn't even find any, then create/edit the dnsresolver config block in naf.xml to explicitly specify the ones you want.
    If you do explicitly specify DNS servers, there will still be a logfile entry showing what would have been automatically obtained. Look for text like DNS-Resolver: OS configured DNS servers.

    Verify %SYSNAME%:
    If you set the announcehost config item to the value %SYSNAME% anywhere in MTAHOME\conf\mailismus.xml (see §4.1, §4.4.4, §4.5.3 and §4.6.2) you need to check what hostname actually got configured.
    Look for the text announce= to see what it says. That will be what %SYSNAME% got resolved to, so if it is not appropriate, then edit MTAHOME\conf\mailismus.xml now to replace all its occurrences with the explicit hostname you want.
    This hostname occurs in various SMTP dialogues, and it need not reflect the official hostname in all of them, but it is critical that the SMTP client does use a valid hostname, ie. one which maps to the IP we're connecting from.

  4. Verify Windows Service (NAF-Launcher)
    Skip this section if you merely downloaded the generic ZIP.

    Our minimal initial config and Java setup should now have been verified as correct, so start Mailismus via the GreySoft NAF Launcher Windows Service.
    Chapter §5 explains how to start and stop this service (a standard Windows Service), and it should not need any configuration at this stage (or probably at any other stage).
    After starting the Service, check the logfiles again for any obvious error messages
    In the event of any problems, the NAF-Launcher logfile (MTAHOME\winservice.log) should indicate precisely what command-line it ran to invoke Java.

    Now stop the Windows Service, and verify that the Service and Java process have stopped, and there are no obvious errors in any of the logfiles.

    You will routinely start and stop Mailismus via this Service from now on.

  5. Send Email Message
    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 forwarding the messages, it can take several days of retries before it is declared a failure, so activity will continue in all the log files. Once again, it's the audit logs (see bounced.log) that will formally record the final status.

    While the logfiles give you an internal view of what's going on within Mailismus, the transcripts give a comprehensive functional picture of its external interactions, so you should be able to verify that the message has either been successfully delivered onwards, or else see a valid reason why it hasn't been.
    If the transcript logs do show a failure somewhere in the chain, you need to start working through the indicated internal reasons within the Mailismus config, or external reasons in your network's setup (firewalls, DNS, etc).
    The likeliest problem is relay-permission-denied, if your email client is not on the same class C IP space as Mailismus. See the relay_clients setting in §4.4.4.

    Beware that it takes the various Mailismus log files up to 30 seconds to flush their buffered output to disk (see the flush setting in NAF Guide §3).
    You should also give the Delivery task up to 2 minutes to pick up the message in the first place. This period is imposed by the initial lack of a licence file, and the free evaluation licence (see §8) enables much more frequent polling.

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