2.1 - Windows Installation
|
While external Mailismus dependencies are limited, it does need some basic runtime components.
These need to be installed before you proceed further:
- A Java VM:
See
here
for instructions.
- The .NET Framework:
The MSI installer and its native Windows Service for launching Mailismus require this, but if you have merely downloaded the generic all-platforms ZIP rather than the Windows MSI installer, then you will have no need of it (ee §2.1.2 below).
The Windows Service requires version 3.0 (or later), which is probably already on your system (see Control Panel for installed programs), but if not, you can obtain it (for free) from Microsoft Downloads.
There are ways to install Mailismus on Windows:
- MSI Installer:
This is a standard
.msi
file for the native Windows Installer.
Simply click on it as usual to execute it, and follow its on-screen instructions.
Assuming you accept the defaults, you will end up with an installation under
C:\Program Files\Grey Software\Mailismus.
For the remainder of this chapter, we shall refer to this directory as
MHOME.
The Windows Service
(GreySoft NAF Launcher
- see §5)
resides at this level, and the mailserver proper is underneath it, in the
MHOME/MTA
directory.
For the remainder of this chapter, we shall refer to that directory as
MTAHOME.
- Generic all-platforms ZIP:
Simply extract it and it's ready to run.
The top-level directory of the extracted contents is
MTAHOME,
in the above terminology.
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.
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.
- 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.
- 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.
- 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.
- 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.
- 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.