MailWasher Server Solaris Installation Guide

Table of Contents

This document describes how to install MailWasher Server on Solaris systems. For more information on MailWasher Server, or for installation guides for Linux or Windows, please refer to http://www.firetrust.com/.

1. Supported platforms
2. Installation overview
3. Running the MailWasher Server installer
3.1 Setting up the startup and shutdown scripts
4. Configuring MailWasher Server using the web interface
5. Installing the mail conduit
5.1 Sendmail
5.2 qmail
6. Uninstalling MailWasher Server
7. Upgrading from a previous version of MailWasher Server
8. Firetrust product support

1. Supported platforms

MailWasher Server supports Solaris 8 and Solaris 9. On Solaris, MailWasher Server supports Sparc-compatible architectures only.

MailWasher Server integrates into your existing mail server using a program called a mail conduit, which is specific to the mail server software. MailWasher Server supports the following mail servers on Solaris:

Versions other than the above may work, but are not officially supported by Firetrust and have not been tested. To inquire about support for other platforms, please contact Firetrust.

Note that Sendmail support requires a version of Sendmail that supports Milters. The sendmail binary supplied with Solaris does not support Milters, and so cannot be used with MailWasher Server; it is necessary to upgrade to Sendmail.org's Sendmail distribution first (see see the instructions on compiling and installing Sendmail on the sendmail.org website if required).

The remainder of this document assumes that one of the above operating systems is installed and configured, and that Sendmail or qmail is installed and configured to receive mail.

2. Installation overview

MailWasher Server consists of three programs:

  1. Mail Processing Daemon (MPD). A daemon that provides the core junk mail filtering for MailWasher Server.

  2. MailWasher Server Web Interface (MWI). A daemon with a built-in HTTP server that provides the web interface used by administrators to configure and maintain the system, and by end users to access their quarantined email.

  3. The mail conduit for your mail server, which checks each incoming message against the Mail Processing Daemon, and then accepts, blocks, or bounces the message.

To help protect your system's security, the two MailWasher Server daemons run under an unpriviledged mwserver user and group, which will be created if necessary during the installation process. Both mail conduits are also normal unpriviledged, non-setuid binaries, but are run in different ways (see Installing the mail conduit below).

On Solaris, MailWasher Server stores files in five locations, following the normal conventions for optional third-party Solaris software:

  1. The executables and supporting files are installed in a configurable location, by default /opt/mwserver. These files total around 10MB, and do not change once the product has been installed. This directory should be writeable only by system administrators.

  2. The runtime databases are stored in a configurable location, by default /var/mwserver. These files are initially less than a megabyte, however they will expand as the amount of quarantined email stored by the system increases. The space required depends on the volume of mail processed by your system and the MailWasher Server configuration options set, but as a guide we recommend that the partition hosting this directory have at least 100MB available. The unpriviledged mwserver user and group own this directory, so that they may write to it.

  3. The temporary runtime files are stored in /var/run/mwserver. This location is fixed, but the files (daemon PID files and domain sockets) in it total less than 1KB. The unpriviledged mwserver user and group own this directory, so that they may write to it. The daemon startup scripts will recreate this directory if it does not exist.

  4. The daemon log files and HTTP access logs are stored in /var/log/mwserver. The unpriviledged mwserver user and group own this directory, so that they may write to it.

  5. Finally, there is a small configuration file, /etc/mwserver.conf. This configuration file is created by the MailWasher Server installer and should not normally be edited manually. It contains only the settings necessary to get the MailWasher Server daemons started; all other options are configured using the web interface and stored in the database. This file should be writeable only by system administrators.

The MailWasher Server installation process has three stages:

  1. Installing the program files, setting up the runtime directories and users, and starting the MailWasher Server daemons, using the installation script (see Running the MailWasher Server installer below)

  2. Configuring MailWasher Server using the web interface, and

  3. Installing the mail conduit for your mail server.

3. Running the MailWasher Server installer

MailWasher Server is distributed as an executable installer. The installer must be run as root, so that it can set up the MailWasher Server directories and priviledges.

Download the Solaris installer from the Firetrust website. Run it, as root, by changing into the directory it was saved in, marking it executable using chmod +x mwserver-installer.bin, and running ./mwserver-installer.bin.

The installer runs through the following steps:

  1. Creating the MailWasher Server user and group. The installer first checks to see if the mwserver user and group exist. If the user and group do not already exist, you will be asked if the installer should create them. If you would prefer to create the user and group manually, do so with the commands groupadd mwserver to create the group, and useradd -g mwserver mwserver, and answer No. Otherwise, answer Yes.

  2. Selecting the program files directory. You will be prompted to enter the location to which to install the executables and supporting files. The default is /opt/mwserver. There should be at least 10Mb available on this partition for installation. MailWasher Server should always be installed in its own directory, preferrably in the location on the filesystem usually reserved for third-party software (typically /opt).

  3. Selecting the database directory. Next, the installer will prompt for the location in which the database files should be stored. The default is /var/mwserver.

  4. Configuring the MailWasher Server Web Interface. The network address and port that the web interface binds to are configurable. By default, the web interface binds to all network interfaces, on port 4044, but both settings can be changed if desired.

    For example, if the users of the web interface will always access it from an internal LAN, you may prefer to have the web interface bind only to the LAN address, so that it cannot be accessed from the Internet.

    To have the web interface bind to all interfaces, accept the default by pressing return; to have it bind to any other interface, enter the IP address of that interface, and press return.

    To have the web interface bind to port 4044, accept the default by pressing return; to have it bind to a different port, enter the port number and press return. Note that since the Web Interface daemon runs as an unpriviledged user account, it cannot bind to ports lower than 1024.

  5. Installing the startup/shutdown scripts. The installer will then create two scripts, /etc/init.d/mwserver-mpd.sh and /etc/init.d/mwserver-mwi.sh, which you can run to start and stop MailWasher Server. However, the installation script does not create the runlevel symlinks necessary to have the daemons start and shutdown automatically; see Setting up the startup and shutdown scripts below.

  6. Starting the daemons. The installer then asks if the daemons should be started so that you can configure MailWasher Server (remember that the mail conduit has not yet been installed, so MailWasher Server is not yet filtering your email). To have the daemons started now, answer Yes. Otherwise, answer No, and see the instructions below to start the daemons manually. In either case, you must set up the runlevel symlinks to have MailWasher Server automatically start and stop with your system; see Setting up the startup and shutdown scripts.

3.1 Setting up the startup and shutdown scripts

The MailWasher Server installer creates two scripts in /etc/init.d that you can use to start and stop the MailWasher Server daemons. To start MailWasher Server manually, run the following:

To stop MailWasher Server manually, run the following:

However, while the installer creates these scripts, it does not link these scripts into your operating system boot sequence. To have these scripts run automatically when the system starts up or shuts down, you must set up the runlevel symlinks in the /etc/rcX.d directories.

These links are named the same as the script, but with a three-character prefix, 'S' or 'K' followed by a two-digit number. 'S' means to start the service in this runlevel, 'K' means stop it. The number denotes the order in which the services start, lowest first.

It is important that MailWasher Server start before the MTA (ie. Sendmail or qmail), so that it is ready to process the mail as soon as the MTA starts receiving it. The defaults given below should accomplish this for default installations on the given operating systems, but it is recommended that you check that the ordering is correct.

To check the ordering, look in the /etc/rcX.d directories after following the directions below for your operating system. If the Sxxmwserver links have a lower number than the links for the MTA, and the Kxxmwserver ones a higher number, then everything is correct. Otherwise, adjust the links by manually renaming them.

3.1.1 Solaris 8 and Solaris 9

On Solaris, links must be created manually between the various /etc/rcX.d directories and /etc/init.d. To have MailWasher Server started automatically on boot and stopped on system shutdown, run the following (as root):

To stop the services from being automatically started and stopped, run the following (as root):

4. Configuring MailWasher Server using the web interface

The MailWasher Server daemons have now been started, and the product can now be configured using the web interface. Open your web browser and go to the address and port you specified during the installer - for example http://your server's name:4044/.

The setup wizard will help you create an administrator account, configure MailWasher Server, and test that it can successfully connect to the FirstAlert! service (unless FirstAlert! access is disabled). For help at any time, see the MailWasher Server online help.

5. Installing the mail conduit

The mail conduits are software components which check each incoming message against the Mail Processing Daemon, and then accepts, blocks, or bounces the message. Each mail conduit is specific to a particular MTA.

5.1 Sendmail

To use MailWasher Server with Sendmail, a version of Sendmail supporting the Milter interface is needed. The sendmail binary supplied with Solaris does not support Milters, and so cannot be used with MailWasher Server; it is necessary to upgrade to Sendmail.org's Sendmail distribution first (see see the instructions on compiling and installing Sendmail on the sendmail.org website if required).

To reconfigure Sendmail, the Sendmail configuration macros are needed. These are included with the source distribution of Sendmail. Before continuing, ensure that the sendmail.mc file matches your current configuration.

Complete the following steps to install the Sendmail mail conduit:

Step Action
1 Change into the cf subdirectory of the Sendmail configuration directory.
2

Edit the sendmail.mc configuration file, and add the following lines at the end of the file:

INPUT_MAIL_FILTER(`mailwasher_server', 
	`S=unix:/var/run/mwserver/mpd.sock, F=T, T=S:60s;R:60s')
define(`confINPUT_MAIL_FILTERS', `mailwasher_server')
(Note that each quoted string in the text above starts with the backquote, `, but ends with a normal single quote, '.)
3 Run the m4 macro processor to generate the new sendmail.cf file using m4 sendmail.mc >sendmail.cf.new.
4

Copy sendmail.cf.new to the appropriate location for your system (usually /etc/sendmail.cf or /etc/mail/sendmail.cf).

5 Restart sendmail using /etc/init.d/sendmail stop and /etc/init.d/sendmail start.

5.1.1 Uninstallation

Complete the following steps to uninstall the Sendmail mail conduit:

Step Action
1 Change into the cf subdirectory of the Sendmail configuration directory.
2 Remove the sendmail.mc lines added in step 2 above.
3 Run the m4 macro processor to generate the new sendmail.cf file using m4 sendmail.mc >sendmail.cf.new.
4

Copy sendmail.cf.new to the appropriate location for your system (usually /etc/sendmail.cf or /etc/mail/sendmail.cf).

5 Restart sendmail using /etc/init.d/sendmail stop and /etc/init.d/sendmail start.

5.1.2 Upgrading from a previous version

Version 1 of MailWasher Server required that a seperate Sendmail conduit daemon be set up and run to connect Sendmail to MailWasher Server. Version 2 adds direct support for Sendmail's Milter protocol to the Mail Processing Daemon, so the seperate Sendmail conduit is no longer required.

Complete the following steps to remove the old Sendmail mail conduit daemon and update Sendmail's configuration to connect to the MPD directly.

Step Action
1 Change into the cf subdirectory of the Sendmail configuration directory.
2 Edit sendmail.mc and replace /var/run/mwserver/sendmailconduit.sock with /var/run/mwserver/mpd.sock.
3 Run the m4 macro processor to generate the new sendmail.cf file using m4 sendmail.mc >sendmail.cf.new.
4

Copy sendmail.cf.new to the appropriate location for your system (usually /etc/sendmail.cf or /etc/mail/sendmail.cf).

5 Restart sendmail using /etc/init.d/sendmail stop and /etc/init.d/sendmail start.
6 Run /etc/init.d/mwserver-sendmail-conduit.sh stop to stop the old Sendmail mail conduit daemon.
7 Remove /etc/init.d/mwserver-sendmail-conduit.sh and any runlevel symlinks you set up to point to it.

5.2 qmail

To install the qmail conduit, run the install-qmail-conduit.sh script in the other subdirectory of the MailWasher Server product directory you selected during installation (usually /opt).

If you would prefer to install the qmail conduit manually, complete the following steps:

Step Action
1 Stop qmail.
2 Change into the qmail binaries directory, usually /var/qmail/bin/.
3 Rename the qmail-queue binary to qmail-queue-mws-orig (mv qmail-queue qmail-queue-mws-orig).
4

Copy the MailWasher Server qmail-conduit binary, found in the bin subdirectory of the MailWasher server product directory you selected during installation (usually /opt/mwserver), to qmail-queue (note the filename change!) in the current directory (for example, cp /opt/mwserver/qmail-conduit qmail-queue).

5 Restart qmail.

Some user-run qmail sites on the web suggest running the qmail daemons under a resource limit (rlimit), such as set by the softlimit utility or the ulimit shell builtin. This resource limit may need to be increased when you install the qmail conduit (whether you install it using automated or manual installation) as it may not allow enough memory space for the system libraries required by the conduit to be mapped in.

If you see errors such as "error while loading shared libraries: [library name]: failed to map segment from shared object: Cannot allocate memory" or "ld.so.1: bin/qmail-queue: fatal: [library name]: mmap failed: Not enough space" appearing in your mail logs, check your qmail-smtpd configuration (usually in /service/qmail-smtpd/run) for softlimit or ulimit commands and increase the limits, then restart the service using svc (or the appropriate control script, if using a packaged version of qmail); note that just killing the daemon and allowing tcpserver to respawn it is not sufficient as that will not re-run the script with the higher limit.

5.2.1 Uninstallation

To uninstall the qmail conduit, run the uninstall-qmail-conduit.sh script in the other subdirectory of the MailWasher Server product directory you selected during installation (usually /opt).

If you would prefer to install the qmail conduit manually, complete the following steps:

Step Action
1 Stop qmail.
2 Change into the qmail binaries directory, usually /var/qmail/bin/.
3 Remove the MailWasher Server qmail conduit binary (rm qmail-queue).
4

Rename the qmail-queue-mws-orig binary to qmail-queue (mv qmail-queue-mws-orig qmail-queue).

5 Restart qmail.

6. Uninstalling MailWasher Server

Complete the following steps to uninstall MailWasher Server:

Step Action
1

If the mail conduit for your mail system is currently installed, uninstall it by following the instructions for qmail or Sendmail above.

2 Stop the two MailWasher Server daemons by running /etc/init.d/mwserver-mpd.sh stop and /etc/init.d/mwserver-mwi.sh stop.
3 Remove the MailWasher Server program files directory you selected during installation. For example, if you installed MailWasher Server to the default directory (/opt/mwserver), run rm -rf /opt/mwserver.
4 Remove the MailWasher Server runtime directory by running rm -rf /var/run/mwserver.
5 Remove the MailWasher Server configuration file by running rm /etc/mwserver.conf.
6 If you want to delete the MailWasher Server accounts, quarantined messages, address list entries, and configuration settings, Remove the MailWasher Server database directory you selected during installation. For example, if you accepted the default directory (/var/mwserver), run rm -rf /var/mwserver. This task is now complete.

7. Upgrading from a previous version of MailWasher Server

Before upgrading an existing MailWasher Server installation, you must first stop your mail server (or, if you prefer, temporarily uninstall the mail conduit as described in the qmail and Sendmail sections above) and stop the two MailWasher Server services (by running /etc/init.d/mwserver-mpd.sh stop and /etc/init.d/mwserver-mwi.sh stop).

Note that you must install MailWasher Server to the same product directory as it is currently installed and select the same database directory as selected during the previous installation to ensure that your configuration settings, address list entries, and quarantined messages are retained.

Version 1 of MailWasher Server required that a seperate Sendmail conduit daemon be set up and run to connect Sendmail to MailWasher Server. Version 2 adds direct support for Sendmail's Milter protocol to the Mail Processing Daemon, so the seperate Sendmail conduit is no longer required. Follow the instructions given in the Sendmail conduit upgrade section to upgrade your installation. Note that the domain socket has changed, so the lines in sendmail.cf need to be updated.

Finally, note that when upgrading a qmail installation, if you choose to leave the mail conduit installed and instead stop your mail server while upgrading, you must both replace the old qmail-queue conduit binary with the new version of the qmail-conduit program (the product installer does not automatically replace the qmail-queue file itself), and make the qmail-queue conduit binary setuid mwserver. The easiest way to do this is simply to run uninstall-qmail-conduit.sh and then run install-qmail-conduit.sh again. See the qmail conduit section for more information on installing and uninstalling the qmail conduit.

8. Firetrust product support

For MailWasher Server technical support, please go to the Support section of the Firetrust website.