Index About us
Index Setup & configLogs & bandwidth usage SPAMDownloadDevelopers  

Setup and Configuration

Configuring your MTA

If you already have a mail server running on the host that will be running Moxy, you'll probably need to configure it to listen on some port other than 25 (in the case that Moxy will be listening on 25). The exact procedure depends on the MTA you are using but is usually easy. For example, with Postfix you need to change the

smtp    inet  n   -   n   -   -   smtpd

line in to something like:

10025   inet  n   -   n   -   -   smtpd

in order to get Postfix to listen on port 10025 (or whatever you choose). For Sendmail, I think you change the

O DaemonPortOptions=Port=esmtp

line in to something resembling:

O DaemonPortOptions=Port=10025

to obtain the same result. The important thing is to remember to include a line in your lookup db to redirect mail addressed to the Moxy host to the correct port. So if the machine is called, then you would modify the MTA config as above and add a entry to the Moxy lookup database (see below):

Configuring Moxy

Configuration of the Moxy mail proxy involves editing the /usr/local/moxy/moxy.conf file and is rather straightforward. The conf file is fully documented so you shouldn't have a problem.

The moxy.conf file controls all aspects of Moxy's operation, from the banner to display on connection to the methods to use for domain lookups and logging. A few options worth noting are:


The port option allows you to specify which port Moxy should listen on. Normally this will be port 25 but it may be appropriate to set it to something else, for example while testing. Ex:
port 25


If you intend to set Moxy to listen on port 25 (or any port below 1024 for that matter), it will need to be started as root in order to bind to the low port. Because of security concerns, Moxy refuses to run as the root user, so you need to set a user to run as in the config. Select a user with minimal priveledges, such as the 'nobody' user under which webservers often run. You may create a user specifically for this purpose - set the shell as /bin/false or something to ensure that it is impossible to login as this user (on many systems, you can do 'useradd -s /bin/false moxy' to create the user 'moxy'). Ex:
runas nobody

AllowRelayFrom and SendRelayTo

Moxy will refuse to relay mail to hosts that cannot be found within the lookup database. In instances where the Moxy host will be used as an outgoing mail server for certain users, you must specify a list of IPs from which mail can be sent to arbitrary destinations.

The allowRelayFrom parameter may be set to a comma seperated list of IP addresses that may use the Moxy host as an outgoing mail server. IPs in this list may include the * wildcard in cases where a range of IPs are valid (for instance, to allow all users on the LAN to send mail through moxy). Ex:
Will allow mail to be relayed for anyone connecting from, anywhere on the subnet or anywhere on the subnet (ie any 127.0.X.Y address).

Connections from these locations with mail for destinations not found in the user database need to go to a Mail Transfer Agent that will accept the mail and handle the routing. This MTA is set using the sendRelayTo configuration parameter. Enter one (or many comma seperated) domain or IP, followed by the colon, followed by the port to connect to. Ex:


When mail comes in for, Moxy translate into a list of host/port destinations. This translation is done by performing a lookup in a database of users. The dbtype parameter configures the type of database to use. At this time, the possibilities include:

  • nodb
  • file
  • dbm


The nodb database is primarily used when mail masquerading is unimportant but Moxy is used for its mail bandwidth logging capabilities. nodb always returns the same list of destinations for all messages, which is set with the nodb_dest parameter.


The file database reads a simple text file containing lines of the form

For example:


The dbm database works essentially the same way as file. The main difference is that file reads the db file into memory and dbm opens a gdbm database file. This has two advantages: the db may be updated on the fly without affecting Moxy and the dbm db keeps the list on disk instead of RAM which may be an advantage for extremely large lists of domains.

other databases

It should be pretty simple to support other types of lookups, eg from a MySQL db or LDAP directory. See the developper page for details.


Moxy can log mail bandwidth usage on a per domain as well as on a per email basis, in real time. Depending on your needs, you may configure various types of logging. These are:

  • nolog
  • filelog
  • syslog
  • gdbmlog
  • sys_and_gdbmlog

Data is extracted from these logs using the moxystats and moxylogalyze utilities (go to the Logs and bandwidth section for details).


nolog, obviously enough, does not log at all. Not recommended, at least while testing the system, but saves space...


The filelog logs transactions to a text file (set using the logfile_name config parameter). This file is very easy to parse because you choose what is logged and how. The log_format allows you to specify the format of the strings output to the log file. For example

log_format   "%date: %msize bytes from <%sender> [%shost] to [%dhost] for '%rcpts'"

Each of the %VAL in the string is replaced in the log output with appropriate values. A line found in your logs would look like:

04/12/01 23:43:08 -0800: 26138 bytes from <> [] to 
[] for ''

You may include any of these in you format string, at any location:

  • %shost - sender Host
  • %sender - sender email
  • %dhost - destination Host:port
  • %rcpts - list of comma delimited recipient email addresses
  • %msize - message size in bytes
  • %date - local time (see below for formatting)

The date's format itself can also be configured, using the log_dateformat parameter and the standard strftime (see the strftime manpage) values, in the example above it was:
log_dateformat   "%d/%m/%y %T %z"


The syslog logtype uses the system's existing syslog facilities to log bandwidth. It works exactly like the filelog except that:
- it ignores the logfile_name config parameter and lets syslog determine where to log.
- the %date log_format value may be redundant because syslog takes care of adding a timestamp to the log entries (but these may be more dificult to parse).


Using gdbmlog allows you to track bandwidth usage on a per domain basis in realtime. The total number of bytes transfered to each destination is tabulated for each email sent (note that an email sent to and is only sent once and is thus only tabulated once). The gdbm log may be queried at any time to get up to date bandwidth usage stats.

gdbmlog uses the logfile_name file as a gdbm database, creating it if necessary.


If you wish to keep track of bandwidth usage for each domain but also want to have an idea of what's happening on a per session basis, the sys_and_gdbmlog combines the best of both the syslog and gdbmlog worlds.

Using this option, sent emails are logged using the syslog and gdbmlog as described above.

other log types

It should be pretty simple to support other types of logging, eg to a relational database. See the developper page for details.

Head to the Logs and bandwidth section for a few more helpful hints on selecting and using the various log types.

Setting up domains

Now that Moxy is configured, we need to set up a few domains to proxy mail for. This is straightforward if you are using a flat file database: simply edit the /usr/local/moxy/moxy.db file - inserting domain destination host:port pairs as described in the file's comments.

If you've selected to use a dbm user database, follow the same procedure as for flat files and then run moxymakedbm. Using moxymakedbm is easy, as demonstrated by the output of moxymakedbm --help:

Usage: moxymakedbm [OPTIONS] INFILE
		Create a gdbm file based on flat file INFILE
			INFILE is the flat text file to use as input.
			-o,--output OFILE	Create file named OFILE. If ommited, creates INFILE.db
			-v,--version		Output version info.
			-h, --help		This message.

So all you need to do to create a gdbm file called /etc/moxy.gdbm based on the contents of /usr/local/moxy/moxy.db is run
moxymakedbm -o /etc/moxy.gdbm /usr/local/moxy/moxy.db

Remember that in order to use this gdbm database, you must configure dbtype to dbm and dbname to /etc/moxy.gdbmin the configuration file.

Starting Moxy

After you have configured Moxy and created the appropriate lookup database, it's finally time to start it! If you want Moxy to listen on a port below 1024 you will probably need to be root to start it.

/etc/rc.d/init.d/moxy start
(if the file is not present, make a soft link to the /usr/local/moxy/moxy file) will start the daemon.

You can use chkconfig to get moxy to start automatically after entering a given runlevel, for example:
chkconfig --level 3 moxy on
will start Moxy upon entering runlevel 3.

You may also start it manually with
/usr/local/bin/moxy -d

The output of moxy --help is:

Usage: moxy [OPTIONS]
   Listen for connections and proxy mail to multiple hosts/ports on a per domain basis.
   -c,--config FILE    Configuration FILE to use.
   -d,--daemon         Detach from terminal and operate in background.
   -p,--port PORTNUM   PORTNUM to listen on.
   -v,--version        Program version info.
   -h, --help          This message.

When first testing your installation, you might want to try starting moxy in a terminal without the -d option so you will see it log any errors. If you really need to debug moxy get the source code and define DEBUG (-DDEBUG) while compiling -- you will get lotsa output. You might want to check the defaults.hh file if you are debugging something specific and only want that module to be verbose.

© 2001-2002 Psychogenic inc.
SourceForge Logo