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 master.cf 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
line in sendmail.cf to something resembling:
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 myhost.com, then you would modify
the MTA config as above and add a entry to the Moxy lookup
database (see below):
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
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
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:
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:
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 126.96.36.199,
anywhere on the 192.168.10.0/24 subnet or anywhere on the
127.0.0.0/16 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 firstname.lastname@example.org, Moxy translate domain.com
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:
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
The file database reads a simple text file containing
lines of the form
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.
It should be pretty simple to support other types of lookups,
eg from a MySQL db or LDAP directory. See the developper page
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:
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
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 <email@example.com> [188.8.131.52] to
[rusthq.com:10025] for 'firstname.lastname@example.org'
You may include any of these in you format string, at any
- %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
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 email@example.com and firstname.lastname@example.org
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
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
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.
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.
(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:
You may also start it manually with
chkconfig --level 3 moxy on
will start Moxy upon entering runlevel 3.
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.