emailrelay/doc/reference.txt

E-MailRelay Reference
=====================

Introduction
------------
This is the E-MailRelay reference guide. It contains material which is
supplementary to the user guide.

Command line usage
------------------
The "emailrelay" program supports the following command-line usage:

	emailrelay [<switch> [<switch> ...]]

where <switch> is:
# --admin (-a)
  Enables the administration interface and specifies its listening port number.

# --admin-terminate (-Q)
  Enables the terminate command on the admin interface.

# --anonymous (-A)
  Disables the smtp vrfy command and sends less verbose smtp responses.

# --as-client (-q)
  Runs as a client, forwarding spooled mail to <host>: equivalent to "--log --no-syslog --no-daemon --dont-serve --forward --forward-to".

# --as-proxy (-y)
  Runs as a proxy: equivalent to "--log --close-stderr --immediate --forward-to".

# --as-server (-d)
  Runs as a server: equivalent to "--log --close-stderr --postmaster".

# --client-auth (-C)
  Enables smtp authentication with remote server, using the given secrets file.

# --client-filter (-Y)
  Specifies an external program to process messages when they are forwarded.

# --close-stderr (-e)
  Closes the standard error stream after start-up.

# --connection-timeout (-U)
  Sets the timeout (in seconds) when connecting to a remote server (default is 40).

# --debug (-g)
  Generates debug-level logging if compiled-in.

# --domain (-D)
  Sets an override for the host's fully qualified domain name.

# --dont-serve (-x)
  Disables acting as a server on any port (part of --as-client and usually used with --forward).

# --filter (-z)
  Specifies an external program to process messages as they are stored.

# --forward (-f)
  Forwards stored mail on startup (requires --forward-to).

# --forward-to (-o)
  Specifies the remote smtp server (required by --forward, --poll, --immediate and --admin).

# --help (-h)
  Displays help text and exits.

# --immediate (-m)
  Enables immediating forwarding of messages as soon as they are received (requires --forward-to).

# --interface (-I)
  Defines the listening interface for new connections.

# --log (-l)
  Writes log information on standard error and syslog.

# --log-time (-L)
  Adds a timestamp to the logging output.

# --no-daemon (-t)
  Does not detach from the terminal.

# --no-smtp (-X)
  Disables listening for smtp connections (usually used with --admin or --pop).

# --no-syslog (-n)
  Disables syslog output.

# --pid-file (-i)
  Defines a file for storing the daemon process-id.

# --poll (-O)
  Enables polling with the specified period (requires --forward-to).

# --pop (-B)
  Enables the pop server if compiled-in.

# --pop-auth (-F)
  Defines the pop server secrets file (default is "/etc/emailrelay.auth").

# --pop-by-name (-J)
  Modifies the pop spool directory according to the user name (requires --pop).

# --pop-no-delete (-G)
  Disables message deletion via pop (requires --pop).

# --pop-port (-E)
  Specifies the pop listening port number (requires --pop).

# --port (-p)
  Specifies the smtp listening port number.

# --postmaster (-P)
  Allows delivery to the postmaster but rejects all other local mailbox addresses.

# --remote-clients (-r)
  Allows remote clients to connect.

# --response-timeout (-T)
  Sets the response timeout (in seconds) when talking to a remote server (default is 1800).

# --scanner (-R)
  Specifies an external network server to process messages when they are stored.

# --server-auth (-S)
  Enables authentication of remote clients, using the given secrets file.

# --spool-dir (-s)
  Specifies the spool directory (default is "/var/spool/emailrelay").

# --user (-u)
  Names the effective user to switch to when started as root (default is "daemon").

# --verbose (-v)
  Generates more verbose output (works with --help and --log).

# --verifier (-Z)
  Specifies an external program for address verification.

# --version (-V)
  Displays version information and exits.

Under Windows there are a few differences. Use "--help --verbose"
to see the complete list.

If no command-line switches are supplied at all then the default
behaviour is:
* to run as a daemon, detached from the terminal
* listen on the standard SMTP port (25)
* store e-mail messages in "/usr/local/var/spool/emailrelay" or "/var/spool/emailrelay"
* reject connections from remote clients
* disable the administration interface
* generate no logging or diagnostic messages

Adding the "--as-server" switch makes sure that logging is enabled and that the
standard error stream is closed.

To forward spooled messages the "--as-client" switch is provided to run the
program
* in foreground, exiting when all spooled mail has been processed
* taking spooled mail from "/usr/local/var/spool/emailrelay" or "/var/spool/emailrelay"
* without listening on any port
* with error, warning and information messages sent to stderr
* without using syslog

Message store
-------------
Mail messages are stored as text files in the configured spool directory. Each
message is represented as an envelope file and a content file. The envelope
file contains parameters relevant to the SMTP dialogue, and the content file
contains the RFC822 headers and body text.

The filenames used in the message store have a prefix of "emailrelay", followed
by a process-id, timestamp and sequence number, followed by "envelope" or
"content". The envelope files then have an additional suffix to implement a
simple locking scheme.

The envelope suffixes are:
* ".new" -- while the envelope is first being written
* <none> -- while the message is spooled
* ".busy" -- while the message is being forwarded
* ".bad" -- if the message cannot be forwarded
* ".local" -- for copies of the envelope file for delivery to local recipients

Copies of the content file for delivery to local recipients will also have
a "local" suffix.

If a message cannot be forwarded the envelope file is given a "bad" suffix,
and the failure reason is written into the file.

SMTP issues
-----------
# Authentication:

  The AUTH extension is supported, providing the CRAM-MD5 and LOGIN mechanisms.

# Local delivery:

  In server mode (ie. with "--postmaster") recipient addresses like
  "postmaster", "postmaster@localhost" and "postmaster@fqdn" (where "fqdn" is
  the host's fully qualified domain name) are treated as the local postmaster,
  resulting in local delivery rather than mail forwarding. Recipient addresses
  other than "postmaster" addresses with no "at" sign (@) or ending in
  "@localhost" will be rejected at the time the message is submitted by the
  client.

  Delivery of mail to a local "postmaster" is a feature of E-MailRelay which is
  provided for completeness and for comformance to the SMTP specification. But
  note that the E-MailRelay daemon does not actually deliver mail to the
  postmaster mailbox.  All it does is create an envelope and content file in
  the spool directory with a ".local" suffix. Some external system, such as a
  shell script run from cron calling "procmail", should be used to process the
  ".local" files. An example script is provided.

# Timeouts:

  A simple client-side timeout is implemented which will abort the transaction
  if the server fails to respond to any of the client's SMTP commands within
  the given time period.

# Message loops:

  Message loops are not detected.

# Eight bit messages:

  The 8BITMIME SMTP extension is supported, however no attempt is made to
  re-encode 8-bit messages into 7-bit messages if the next-hop server
  does not.

Administration interface
------------------------
If enabled with the "--admin" command line switch, the E-MailRelay server will
provide a network interface for performing administration tasks. This is a
simple command-line interface which is compatible with "telnet":

	$ emailrelay --as-server --port 125 --forward-to localhost:25 --admin 10026
	$ telnet localhost 10026
	E-MailRelay> help
	E-MailRelay> quit

The "flush" command is used to get the E-MailRelay server to forward spooled
mail to the next SMTP server, as an alternative to running
"emailrelay --as-client" as a separate process. In proxy mode it is a way of
getting the proxy server to scan the spool-directory for new messages.

The utility program "emailrelay-poke" can be used to issue the "flush"
command to an E-MailRelay server. For example:

	$ emailrelay --as-server --port 125 --forward-to localhost:25 --admin 10026
	$ emailrelay-poke 10026
	$ echo $?

To use the "flush" command the next SMTP server address must have been defined
on the "emailrelay" command line at start-up using the "--forward-to" switch.

Also, the "list" command lists the messages in the spool directory, "info"
provides network status information and activity statistics, and "notify"
enables asynchronous event notification.

Mail processing
---------------
The "--filter" command-line switch allows you to specify a mail pre-processor
program which operates on mail messages as they pass through the E-MailRelay
system. The mail pre-processor program is run as soon as the mail message has
been stored in the spool directory, with the full path of the content file
added onto the end of the given command line.

For example, the following command will start a proxy server on port 10025
which processes mail using the specified filter program, and then forwards the
mail on to the system's default MTA (on port 25):

	emailrelay --as-proxy localhost:smtp --port 10025 --no-syslog \
	  --filter $HOME/.emailrelay/filter \
	  --spool-dir $HOME/.emailrelay/spool

The pre-processor program should terminate with an exit code of zero to
indicate success, or a value between 1 and 99 to indicate failure. Exit codes
between 100 and 107 are reserved for special processing: 100 is used to cancel
all further processing of the message, and 103 has the effect of immediately
expiring any "--poll" timer.

If the pre-processor program terminates with a non-zero exit code then the
first few thousand characters of the standard output stream are searched for a
line starting with "<<" followed by ">>". The text inbetween is taken as a
failure reason, and passed back to the SMTP client.

The pre-processor program can edit any part of the message's envelope file or
content file: E-MailRelay remembers nothing about the message while the
pre-processor is running, except the filename. But if the message is deleted
by the pre-processor then E-MailRelay will be upset, so to avoid the
error message use an exit code of 100.

If the pre-processor program creates completely new messages in the spool
directory then they may not be processed immediately, or they may be completely
ignored. To get E-MailRelay to pick up new messages in the spool directory use
the "--poll" switch, or run "emailrelay --as-client" from within the
pre-processor program.

As an example of a simple pre-processor this shell script examines the sending
client's IP address and conditionally passes the message into "sendmail" (using
the sendmail command-line interface rather than SMTP):

	#!/bin/sh
	# filter.sh
	content="${1}"
	envelope="`echo \"${content}\" | sed 's/content/envelope.new/'`"
	ip="`awk '/MailRelay-Client:/ {print $2;exit}' \"${envelope}\"`"
	if test "${ip}" = "192.168.0.2"
	then
		cat "${content}" | /usr/sbin/sendmail -t
		rm -f "${envelope}" "${content}"
		exit 100 # <= cancel further processing by emailrelay
	fi
	exit 0

The first thing this script does is convert the path of the content file which
it is given, into the corresponding envelope file. It then extracts the
client's IP address out of the envelope file using "awk". If this matches the
fixed address then it pipes the message content into sendmail, deletes the
message and exits with a value of 100. The exit value of 100 tells E-MailRelay
to forget the message, and not to complain about the files disappearing.

For Windows this example can be rewritten in JavaScript:

	// filter.js
	var content = WScript.Arguments(0) ;
	var envelope = content.substr(0,content.length-7) + "envelope.new" ;
	var fs = WScript.CreateObject( "Scripting.FileSystemObject" ) ;
	var ts = fs.OpenTextFile( envelope , 1 , false ) ;
	var e = ts.ReadAll() ;
	ts.Close() ;
	var re = new RegExp( "MailRelay-Client: \(.*\)" ) ;
	var ip = e.match(re)[1] ;
	if( ip == "192.168.0.2" )
	{
		var sh = WScript.CreateObject( "Wscript.Shell" ) ;
		sh.Run( "sendmail " + content ) ; // bogus
		fs.DeleteFile( content ) ;
		fs.DeleteFile( envelope ) ;
		WScript.Quit( 100 )
	}
	WScript.Quit( 0 ) ;

Windows pre-processor programs written in JavaScript can be run using
"cscript", with an E-MailRelay "--filter" switch something like this:

	--filter "c:/winnt/system32/cscript.exe //nologo c:/program\ files/emailrelay/filter.js"

Note how the space character in the path is escaped with a backslash.

As an example of more complex processing there is a "--filter" script included
in the distribution ("emailrelay-process.sh") that does rot-13 masking of
messages.  This script also does some simple MIME encoding, so that the masked
message appears as an attachment within a plaintext bearer message.

E-MailRelay also has a "--client-filter" switch that enables pre-processing of
messages just before they are forwarded, rather then after they are stored. The
problem is that by then it is too late to notify the SMTP client of any
processing failures, so in many applications using "--filter" is more useful.

Bear in mind the following points when writing "--filter" programs:
* The standard input and output are not used; the content filename is passed on the command line.
* Programs run with a reduced set of environment variables.
* The E-MailRelay process is completely blocked while the "--filter" program runs.
* E-MailRelay files use CR-LF line terminators, as required by the RFCs.
* Envelope files will have a file extension of ".new" or ".busy" when the program runs.
* Windows JScript and VBScript programs must be run using "cscript".
* Windows Perl programs must be run from a batch file, or from a JScript/VBScript wrapper.

It is also possible to run a separate server process to pre-process messages by
using the "--scanner" switch, which has the advantage of not blocking the main
E-MailRelay process during message pre-processing. The "--scanner" switch is
used to specify the IP address and port that the scanner server is listening
on. E-MailRelay connects to this address and then uses a simple line-based
dialog as each e-mail message is received. E-MailRelay sends the full path of
the message content file, and the scanner is expected to respond with "ok" if
the message is to be accepted, or an error message. No source code is provided
for a scanner process in this release, but *Python's* [http://python.org]
support for threads and sockets would make it a good choice of language.

Address verification
--------------------
In server mode (or more accurately when "--postmater" is in effect) addresses
for incoming e-mails received in "RCPT" or "VRFY" commands are accepted as valid
if they contain an at sign ("@") or if they are some sort of local "postmaster"
address: "postmaster", "postmaster@localhost" or "postmaster@<fqdn>". Other
addresses without an at sign are rejected.

In proxy mode (more accurately without "--postmaster") all addresses are
accepted as valid, whatever they look like.

This is normally what you want for a proxy or store-and-forward MTA because the
delivery address can only be fully verified once the message gets to the last
machine in the chain and the message is finally delivered into a mailbox.

However, the default behaviour can be modified by using an external verifier
program, specified with the "--verifier" command-line switch, so that you get
to choose which addresses are accepted as valid and which are rejected.

The external verifier program is passed a command-line containing: (1) the full
address, (2) the user-name part of the address in upper-case, (3) the host-name
part in upper-case, (4) the local host's fully qualified domain name in
upper-case, (5) the current "MAIL" command's "FROM:" address or the empty string
for the "VRFY" command, (6) the IP address of the client connection, (7) the
authentication mechanism used by the client ("NONE" if trusted), and (8) either
the authentication name or the fourth field from authentication secrets file if
a trusted IP address:

	myverifier me@myhost.mydomain ME MYHOST.MYDOMAIN MYHOST.MYDOMAIN bob@other.net 192.168.0.1 LOGIN bob

For valid non-local addresses the first line of output is ignored, the second
line should be copied from the first command-line argument, and the exit
value should be one.

	#!/bin/sh
	# address verifier -- accept all (252)
	echo ""
	echo $1
	exit 1

For valid local addresses, where messages are to be delivered to a local
mailbox, the verifier is expected to write two lines to the standard output --
the full name associated with the mailbox, and the canonical mailbox name -- and
then exit with a value of zero.

	#!/bin/sh
	# address verifier -- accept as local (250)
	echo Local Postmaster '<postmaster@localhost>'
	echo postmaster
	exit 0

For invalid addresses the exit value should be greater than one, and anything
written to the standard output is taken as the failure reason. (Only the few
few thousand characters are read from the verifier's standard output stream; any
more is thrown away.)

	#!/bin/sh
	# address verifier -- reject as invalid (550)
	echo invalid address: $1
	exit 2

To indicate a temporary failure this can be changed to an exit code of 3.

	#!/bin/sh
	# address verifier -- reject as temporarily invalid (450)
	echo address unavailable: $1
	exit 3

If the exit code is 100 then the connection is aborted immediately.

	#!/bin/sh
	# address verifier -- abort
	exit 100

In this more complete example all addresses are accepted as long as they contain
an at sign:

	#!/bin/sh
	# address verifier -- accept only if containing an at sign
	address="$1"
	expr "${address}" : ".*@" > /dev/null || exit 2
	echo ""
	echo "${address}"
	exit 1 # accept

As another example, this verifier script accepts all recipient addresses by
default, but rejects remote addresses if the client has bypassed authentication
by connecting on a trusted IP address:

	#!/bin/sh
	# address verifier
	address="$1"
	host="$3"
	local_domain="$4"
	auth_mechanism="$7"
	if test -z "${auth_mechanism}" ; then auth_mechanism="NONE" ; fi
	if test "${auth_mechanism}" = "NONE" -a "${host}" != "${local_domain}"
	then
		echo "cannot relay without authentication"
		exit 2 # reject the recipient address
	fi
	echo "${address}"
	echo "${address}" # again
	exit 1 # accept the recipient address

or in JavaScript:

	// verifier.js
	var address = WScript.Arguments(0) ;
	var host = WScript.Arguments(2) ;
	var local_domain = WScript.Arguments(3) ;
	var auth_mechanism = WScript.Arguments(6) ;
	if( ( auth_mechanism == "NONE" || auth_mechanism == "" ) && host != local_domain )
	{
		WScript.Echo( "cannot relay without authentication" ) ;
		WScript.Quit( 2 ) ;
	}
	WScript.Echo( address ) ;
	WScript.Echo( address ) ;
	WScript.Quit( 1 ) ;

If this verifier script is used with a suitable "--server-auth" file then it can
be used to prevent open relay without restricting authenticated clients.

Security issues
---------------
A significant security concern is the use of external mail pre-processors and
address verifiers (using the "--filter" and "--verifier" switches), and so the
following precautions are taken:

# effective userid

  Suid privileges are revoked at start-up, switching the effective
  userid/groupid to be the real userid/groupid values. If started as "root"
  then the effective userid/groupid are switched at start-up to those of user
  "daemon". Special privileges are only reclaimed when needed to bind sockets
  and do file i/o. Normally this means temporarily switching the userid and
  groupid back to what they were at start-up. However, when writing spool files
  after being started as "root" only the effective userid is changed, not the
  groupid, so that new files have group ownership corresponding to the
  "daemon" user.

# execution environment

  The mail pre-processor runs with an almost empty set of environment variables
  ("PATH" and "IFS"), and with no open file descriptors other than "stdin" and
  "stderr" open onto "/dev/null", and "stdout" open onto a pipe.

# configuration

  The mail pre-processor filename has to be configured using a full path, so
  there is no dependence on the current working directory or the PATH
  environment variable.

Some other points are:
# umask

  The program runs for most of the time with a "umask" of 177, switching to 117
  when creating spool files.

# buffer overflow

  Strings are dynamically allocated, so buffer overflow/truncation issues are
  avoided.

# remote clients

  By default connections to the SMTP and administrative ports will be rejected
  if they come from remote machines.

# remote configuration

  No configuration parameters can be changed through the administrative
  interface.

# use of exec() and system()

  No exec(), system() or popen() calls are used other than execve() to spawn the
  mail pre-processor and/or address verifier.

# file permissions

  After a normal installation the spool directory is has ownership of
  "root.daemon" with permissions of "-rwxrwxr-x". Messages files are created
  with permissions of "-rw-rw----". This allows normal users to list messages
  files but not read them.

  The "emailrelay-submit" program is given group ownership of "daemon" with its
  group set-user-id flag set. This allows it to create message files in the
  spool directory, and the files created end up owned by the submitter but with
  group ownership of "daemon".

Security issues which relate to the SMTP protocol itself are beyond the scope of
this document, but RFC2821 makes the following observation: "SMTP mail is
inherently insecure in that it is feasible for even [..] casual users to [..]
create messages that will trick a [..] recipient into believing that they came
from somewhere else. [..] Real [..] security lies [..] in end-to-end methods
[..] such as those which use digital signatures."

The "Authentication" section below also relates to security.

Authentication
--------------
E-MailRelay supports the ESMTP "AUTH" extension, as defined in RFC2554, on both
the server-side and client-side.

The authentication mechanisms currently supported are:
# "LOGIN"

  Passwords are stored in clear-text, sent over the network in clear-text, and
  are replayable. This is a widely used mechanism, but officially obsolete.

# "CRAM-MD5" mechanism

  Passwords are not stored in clear-text, not sent over the network, and are
  not replayable. Defined in RFC2195.

Authentication is enabled with the "--client-auth" and "--server-auth"
command-line switches. The switch parameter is the name of a "secrets" file,
containing usernames and passwords:

	emailrelay --as-server --server-auth /etc/client-secrets.txt
	emailrelay --as-client myisp.net:smtp --client-auth /etc/myisp-secret.txt

The secrets file has a line-based format: blank lines are ignored and the hash
character (#) is used for comments.

Lines have four white-space delimited fields:
* "mechanism"
* "client-or-server"
* "userid"
* "secret"

The "mechanism" field must be "LOGIN", "APOP" or "CRAM-MD5" (case-insensitive);
the "client-or-server" field must be "client" or "server"; the "userid" field is
xtext-encoded user identifier; and the "secret" field is the xtext-encoded
"LOGIN" password, or the "CRAM-MD5" key.

The "xtext" encoding scheme is defined properly in RFC1891, but basically it
says that non alphanumeric characters should be represented in hexadecimal as
"+XX".

The client-side secrets file specified with "--client-auth" is used when
E-MailRelay talks to a remove server. The file should contain at least one
"LOGIN client" or "CRAM-MD5 client" entry.

A server-side secrets file specified with "--server-auth" is used when a remote
client tries to authenticate with E-MailRelay. The file should normally contain
several "LOGIN server" or "CRAM-MD5 server" entries.

The same secrets file may be specified for both "--client-auth" and
"--server-auth" switches.

The "CRAM-MD5" keys can be generated using the "emailrelay-passwd" utility.

As an example, the following secrets file defines "jsmith" as the username to be
used when E-MailRelay authenticates with a remote SMTP server, and defines two
usernames ("user1" and "user2") which can be used by clients when they
authenticate with the E-MailRelay server:

	#
	# emailrelay secrets file
	#
	LOGIN client jsmith my+20password
	LOGIN server user1 secret
	LOGIN server user2 e+3Dmc2

A "CRAM-MD5" version would look like this:

	#
	# emailrelay secrets file
	#
	CRAM-MD5 client jsmith 688498119.2977922305.1278051807.3015243256.2216875978.2833592318.2902375592.3156808220
	CRAM-MD5 server user1 4059553961.2316091643.3282746241.1444639637.3735501773.3404060330.2760590371.1201092398
	CRAM-MD5 server user2 2798539199.3144534242.3784876256.2879973305.2327113479.216533878.2436460291.2361831919

When using the "LOGIN" you have to store plaintext passwords in a file. This is
a bad thing. You should at least make sure that the secrets file has tight
permissions, and that the passwords in it are not also used for anything
important.

On the server side authentication is advertised by E-MailRealy in the response
to the SMTP "EHLO" command if the "--server-auth" command-line switch is used.
Authentication by the client is mandatory unless the client's IP address is
configured as a trusted address. If the client does authenticate then the
authenticated user-id is stored with the message and then passed on to the next
SMTP server using an "AUTH=userid" parameter on the SMTP "MAIL FROM" command.

Trusted IP addresses are configured with lines in the secrets file having "NONE"
in the first field, "server" in the second field, a wildcarded IP address in
the third field, and an arbitrary keyword in the fourth field. The keyword
is passed to any external address verifier program specified by the "--verifier"
command-line switch.

For example this secrets file allows any client connecting from the
192.168.0.0/24 domain to connect without authentication desipte the
"--server-auth" switch:

	#
	# emailrelay secrets file
	#
	NONE server 192.168.0.* localdomain
	LOGIN server user1 secret
	LOGIN server user2 e+3Dmc2

On the client side authentication is performed when E-MailRelay has connected to
a server which implements the AUTH extension with one of the supported
mechanisms. If client authentication is enabled (with the "--client-auth"
switch) but the server does not support the AUTH extension, or does not support
the LOGIN or CRAM-MD5 mechanism, then E-MailRelay will fail the first message
and terminate with an error message.

Note that some ISPs require separate POP/IMAP authentication before SMTP access
from a particular IP address is allowed. This type of POP-before-SMTP
authentication can be done outside the E-MailRelay system by POP/IMAP utilities
such as "fetchmail".

Pop server
----------
If E-MailRelay has been built with POP3 support then the "--help --verbose"
output will show several new command-line switches:
# --pop

  Enables the POP3 server.

# --pop-port <port>

  Changes the POP3 listening port from its default of 110.

# --pop-auth <path>

  Changes the authentication secrets file. The default is typically
  "/etc/emailrelay.auth".

  The format of the authentication secrets file is the same as for
  "--server-auth" and the same file can be used for both SMTP and POP3
  authentication.

  "APOP server" entries are used for "APOP" authentication, "LOGIN server"
  entries are used for "USER/PASS" authentication, and "CRAM-MD5" entries are
  used for "AUTH" authentication.

  Note that the basic POP3 protocol defines only "APOP" and "USER/PASS"
  authentication, so some POP3 client programs may not be able to cope with
  CRAM-MD5 authentication using the POP3 "AUTH" extension.

# --pop-by-name

  Modifies the spool directory according to the client authentication name.
  The client name is used as a sub-directory off the standard spool directory.
  So, for example, if a client authenticates as "bob" then the POP3 server
  will serve messages from the "/var/spool/emailrelay/bob" directory.

# --pop-no-delete

  Disables message deletion. The POP3 DELE command will appear to succeed, but
  no files will be deleted from the spool directory.

Files and directories
---------------------
Following a normal build from source, a "make install" puts files in the
following locations:
* /usr/local/etc/emailrelay.conf
* /usr/local/etc/emailrelay.conf.template
* /usr/local/libexec/emailrelay
* /usr/local/libexec/emailrelay-deliver.sh
* /usr/local/libexec/emailrelay-notify.sh
* /usr/local/libexec/emailrelay-poke
* /usr/local/libexec/emailrelay-process.sh
* /usr/local/libexec/emailrelay-resubmit.js
* /usr/local/libexec/emailrelay-resubmit.sh
* /usr/local/libexec/emailrelay-runperl.js
* /usr/local/libexec/emailrelay-submit.sh
* /usr/local/man/man1/emailrelay.1.gz
* /usr/local/man/man1/emailrelay-passwd.1.gz
* /usr/local/man/man1/emailrelay-poke.1.gz
* /usr/local/man/man1/emailrelay-submit.1.gz
* /usr/local/sbin/emailrelay
* /usr/local/sbin/emailrelay-passwd
* /usr/local/sbin/emailrelay-submit
* /usr/local/share/emailrelay/doc/changelog.gz
* /usr/local/share/emailrelay/doc/changelog.html
* /usr/local/share/emailrelay/doc/developer.html
* /usr/local/share/emailrelay/doc/developer.txt
* /usr/local/share/emailrelay/doc/emailrelay.css
* /usr/local/share/emailrelay/doc/emailrelay-man.html
* /usr/local/share/emailrelay/doc/index.html
* /usr/local/share/emailrelay/doc/NEWS
* /usr/local/share/emailrelay/doc/*.png
* /usr/local/share/emailrelay/doc/README
* /usr/local/share/emailrelay/doc/readme.html
* /usr/local/share/emailrelay/doc/reference.html
* /usr/local/share/emailrelay/doc/reference.txt
* /usr/local/share/emailrelay/doc/userguide.html
* /usr/local/share/emailrelay/doc/userguide.txt
* /usr/local/share/emailrelay/doc/windows.html
* /usr/local/share/emailrelay/doc/windows.txt
* /usr/local/var/spool/emailrelay/emailrelay.*.content
* /usr/local/var/spool/emailrelay/emailrelay.*.envelope

This directory structure is constrained by the GNU/"autoconf" conventions rather
than the Filesystem Hierarchy Standard (FHS).

To force FHS compliance you can use the "--enable-fhs" switch when running
"configure", as is done for the RPMs. This results in the following file
locations:
* /etc/emailrelay.conf
* /etc/emailrelay.conf.template
* /etc/init.d/emailrelay
* /usr/lib/emailrelay-poke
* /usr/sbin/emailrelay
* /usr/sbin/emailrelay-passwd
* /usr/sbin/emailrelay-submit
* /usr/share/doc/emailrelay/changelog.gz
* /usr/share/doc/emailrelay/changelog.html
* /usr/share/doc/emailrelay/developer.html
* /usr/share/doc/emailrelay/developer.txt
* /usr/share/doc/emailrelay/emailrelay.css
* /usr/share/doc/emailrelay/emailrelay-man.html
* /usr/share/doc/emailrelay/examples/emailrelay-deliver.sh
* /usr/share/doc/emailrelay/examples/emailrelay-notify.sh
* /usr/share/doc/emailrelay/examples/emailrelay-process.sh
* /usr/share/doc/emailrelay/examples/emailrelay-resubmit.sh
* /usr/share/doc/emailrelay/examples/emailrelay-submit.sh
* /usr/share/doc/emailrelay/index.html
* /usr/share/doc/emailrelay/NEWS
* /usr/share/doc/emailrelay/*.png
* /usr/share/doc/emailrelay/README
* /usr/share/doc/emailrelay/readme.html
* /usr/share/doc/emailrelay/reference.html
* /usr/share/doc/emailrelay/reference.txt
* /usr/share/doc/emailrelay/userguide.html
* /usr/share/doc/emailrelay/userguide.txt
* /usr/share/doc/emailrelay/windows.html
* /usr/share/doc/emailrelay/windows.txt
* /usr/share/man/man1/emailrelay.1.gz
* /usr/share/man/man1/emailrelay-passwd.1.gz
* /usr/share/man/man1/emailrelay-poke.1.gz
* /usr/share/man/man1/emailrelay-submit.1.gz
* /var/spool/emailrelay/emailrelay.*.content
* /var/spool/emailrelay/emailrelay.*.envelope

For finer control of the directory structure the following can be specified on
the "configure" command-line (but note that the "--enable-fhs" will override
them):
* --libexecdir=<dir>
* --mandir=<dir>
* --sbindir=<dir>
* --sysconfdir=<dir>
* e_docdir=<dir>
* e_examplesdir=<dir>
* e_initdir=<dir>
* e_spooldir=<dir>

For example, running "./configure --prefix=/usr e_spooldir=/tmp/spool" will
create the GNU-style directory structure under "/usr" rather than "/usr/local",
and create the E-MailRelay spool directory as "/tmp/spool" rather than
"/usr/local/var/spool/emailrelay".

The default spool directory path which is built into the executables and scripts
comes from "configure", via the makefiles. So after running "configure" with a
different spool directory do a "make clean" in at least "src/main" and "bin".

Even though the "--enable-fhs" switch overrides all other directory specifiers
during the build process, it is still possible to change the installation root
directory using "make install DESTDIR=<root>" or "DESTDIR=<root> make -e install".
However, this will not affect the default directory paths built into the scripts
and executables, so they will have to be explicitly defined at run-time.

The "emailrelay" start/stop script in "init.d" creates a pid file in "/var/run"
if the directory exists, or in "/tmp" otherwise.




Copyright (C) 2001-2006 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved.