tmda-ofmipd

What is it?

tmda-ofmipd is an authenticated SMTP proxy for TMDA. tmda-ofmipd allows users of any mail client capable of SMTP Authentication (e.g, Outlook, Eudora, Mozilla) to "tag" their outgoing mail as described in the ClientConfiguration section.

In this document, mail clients are referred to as an MUA, which stands for "Mail User Agent". The name ofmip stands for "Old Fashioned Mail Injection Protocol"

tmda-ofmipd can either accept SMTP connections directly on an available port (e.g, 8025), or can be triggered by another server such as xinetd or tcpserver. When a connection is received, tmda-ofmipd authenticates the user, and looks up the user's TMDA configuration. For each message that is received, the message is processed according to the user's outgoing filter.

Once the message has been processed, tmda-ofmipd simply forwards it to some existing SMTP server. This is why it's known as a "proxy" - tmda-ofmipd does not replace the real SMTP server; rather it accepts the message from the client, transforms the headers etc., and then sends the message by handing it off to the real SMTP server.

There are several reasons why you may want to (or have to) use tmda-ofmipd to take advantage of TMDA's client features:

Your MUA doesn't support a /usr/sbin/sendmail interface, but rather uses direct SMTP to send mail. This includes practically all non-Unix mail clients, and even some Unix clients such as Thunderbird or Mozilla.
You want to maintain your TMDA configuration in one central location instead of on each individual machine that you use. Unless all your machines share a home directory via NFS or somesuch, this isn't trivial. tmda-ofmipd allows you to maintain only one set of files - on the server on which tmda-ofmipd runs.

Requirements

An MUA that supports RFC 2554 SMTP Authentication (i.e, username/password). TMDA FAQ 5.6 contains a preliminary list of MUAs known to work with tmda-ofmipd.

NOTE: If your MUA only supports a sendmail command-line interface, but you still want to use tmda-ofmipd, see below for some options.

Authentication

tmda-ofmipd implements the minimal SMTP protocol as defined in RFC 2821, the ESMTP EHLO command defined in RFC 1869, and SMTP Authentication (PLAIN, LOGIN, CRAM-MD5 methods) as defined in RFC 2554. The proxy cannot be used by an unauthenticated user.

Authentication Sources

tmda-ofmipd can get its authentication information from several different sources.

From a "password" file that you create. The format of this file is simple. Each line of the file should contain a username and password separated by a colon; one entry per line. e.g,
```
bobby:FooBar
chloe:baz_bap
johndoe:8i9/hjuy+33
```
The username fields should match the usernames of the TMDA users on your mail server. The passwords need not be the same as any other passwords on the system. In fact, for security reasons, they should remain distinct! The default location for the authentication file /etc/tofmipd if running in global mode (see below), otherwise ~user/.tmda/tofmipd. These defaults can be overridden using tmda-ofmipd's '-a' flag. The authentication file must be chmod 600 or 400, and be owned by the user running the daemon. tmda-ofmipd will fail to start otherwise.
A checkpassword compatible programs such as checkpassword-pam. This would allow you to utilize your existing password database. Use tmda-ofmipd's '-A' flag to specify the program and arguments. The help output contains such an example.
Against a remote resource such as POP3, IMAP, or LDAP server. Use tmda-ofmipd's '-R' flag to specify the protocol, and optionally the hostname and port of the server. See the help output for supported protocols and example usage.

Running

Familiarize yourself with tmda-ofmipd's command-line options by reading the output of:

tmda-ofmipd --help

Modes

tmda-ofmipd can be run in two modes. "Personal" by your non-privileged TMDA user account for your own personal use, or "Global" by your system administrator to serve multiple TMDA users on the system with once instance of the daemon.

Personal mode

Choose one of the authentication mechanisms above. If you chose to use a password file, you will need to create this.
Run tmda-ofmipd under your regular Unix user account.

Global mode

Choose one of the authentication mechanisms above. If you chose to use a password file, you will need to create this.
Create a non-priveleged user account for tmda-ofmipd to run under. The following creates an account for user 'tofmipd', group 'tofmipd' under FreeBSD:
```
 # pw groupadd tofmipd
 # pw useradd tofmipd -g tofmipd -s /nonexistent
```
The following does the same for Linux:
```
 # groupadd tofmipd
 # useradd -g tofmipd -s /nonexistent tofmipd
```
If you choose a name other than 'tofmipd', make sure to start tmda-ofmipd with the '-u' option.
Invoke tmda-ofmipd under the root account. tmda-ofmipd will internally switch privileges to the tofmipd user, and the user ID of the client connection, as appropriate.

Starting tmda-ofmipd

tmda-ofmipd can run either as a standalone daemon, or run in "one-session" mode.

When run as a standalone daemon, tmda-ofmipd will listen for connections on the port you specify, accept those connections directly, and handle those connections as described in the introduction.

In "one-session" mode, a separate application, such as xinetd or tcpserver, is expected to listen for, and accept, incoming socket connections, and then spawn tmda-ofmipd to handle the connection.

Some advantages of "one-session" mode are:

You can run tmda-ofmipd the same way as other network applications, for more consistent management (e.g. re-using xinetd's connection rate control features, or any tcpwrappers configuration, etc.)
tmda-ofmipd doesn't currently handle SSL directly. To use SSL, you need to use another application such as stunnel. Typically, stunnel will accept the network connection, and make a "loopback" connection to tmda-ofmipd. In this scenario, tmda-ofmipd cannot know the client's IP address, and does not place useful information into the "Received" header it adds to messages. In "one-session" mode, tmda-ofmipd can pick up and use environment variables set by xinetd/tcpserver for this information.

Note that becaue "one-session" mode requires configuring an application such as xinetd to spawn tmda-ofmipd, and (typically) xinetd can only be configured by a system administrator, "one-session" mode will typically be used only in "global mode" as described above. However, a combination of a user-controlled "socket server" application such as stunnel running on a non-privileged port, and tmda-ofmipd in "personal" mode should work, but has not been tested.

Daemon

$ tmda-ofmipd -d -f
tmda-ofmipd started at Sun, 29 Oct 2006 17:50:25 -0700
        Listening on localhost:8025

tmda-ofmipd is now listening in the foreground for connections on port 8025 of your server.

The host:port combination can be changed using the '-p' option. The '-d' option prints debugging information to stderr which might be useful until you get tmda-ofmipd working as you want it to. Leave off the '-f' option, and tmda-ofmipd will detach and run in the background.

xinetd/tcpserver

Configure xinetd to run tmda-ofmipd just like any other program. A simple example configuration file for xinetd is shown below:

# default: on
# description: TMDA SMTP proxy daemon
service tmda-ofmipd
{
        socket_type     = stream
        wait            = no
        user            = root
        server          = /usr/local/tmda/bin/tmda-ofmipd -1
        log_on_failure  += USERID
}

Note: Your /etc/services file will need a "tmda-ofmipd" entry to define the port that xinetd will listen on.

Also, note the use of the "-1" option to place tmda-ofmipd into "one-session" mode.

The contrib/ofmipd-stunnel-xinetd contains a more complete example, including the use of stunnel for SMTP/TLS.

tmda-ofmipd uses the environment variable TCPREMOTEIP, or REMOTE_HOST, to determine the client's IP address. tcpserver and xinetd respectively set those variables. If you use another socket server application, you should arrange for one of those variables to be set.

Testing

$ telnet localhost 8025 
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
220 localhost ESMTP tmda-ofmipd
quit
221 Bye
Connection closed by foreign host.

MUA Configuration

You must now configure your MUA to use a port other than 25 to send outgoing mail (by default, tmda-ofmipd runs on port 8025 in daemon mode). Configuring your mail client to use an alternate SMTP port to send outgoing mail differs for every client, and is beyond to scope of this document. However, see the following link for examples of how to do this for some of the more popular clients.

http://www.itap.purdue.edu/email/mailhub/clientsetup.cfm

If your MUA only supports a sendmail interface for sending mail, see TMDA FAQ 5.7 for some options.

TmdaOfmipdHowto