.\" Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
.\" 
.\" This program is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
.\" 
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\" 
.\" You should have received a copy of the GNU General Public License
.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
.TH EMAILRELAY 1 local
.SH NAME
emailrelay \- e-mail transfer agent and proxy
.SH SYNOPSIS
.B emailrelay
[OPTIONS]
.LP
.B emailrelay
--as-server
.LP
.B emailrelay
--as-client
.I server-address
.LP
.B emailrelay
--as-proxy
.I server-address
.SH DESCRIPTION
.I emailrelay
is a simple SMTP proxy and store-and-forward message transfer agent.
It does store-and-forward mail relay to a fixed next-hop server, without
any routing.
.LP
It runs in two main modes: a storage daemon
.RI ( --as-server )
and a forwarding
agent
.RI ( --as-client ).
The storage daemon is an SMTP server which stores e-mail
messages in a local spool directory. The forwarding agent acts as an
SMTP client sending the spooled e-mail messages on to the next
SMTP server in the chain.
.LP
It can also run in a third mode, as a proxy server
.RI ( --as-proxy ).
In this mode all e-mail messages are spooled temporarily while the
client is connected and forwarded as soon as the client
disconnects.
.SH OPTIONS
.SS Basic options
.TP
.B \-q, --as-client \fI<host:port>\fR
This is equivalent to \fI--log\fR, \fI--no-syslog\fR, \fI--no-daemon\fR, \fI--dont-serve\fR, \fI--forward\fR and \fI--forward-to\fR. It is a convenient way of running a forwarding agent that forwards spooled mail messages and then terminates.
.TP
.B \-y, --as-proxy \fI<host:port>\fR
This is equivalent to \fI--log\fR, \fI--close-stderr\fR, \fI--forward-on-disconnect\fR and \fI--forward-to\fR. It is a convenient way of running a store-and-forward daemon. Use \fI--log\fR, \fI--forward-on-disconnect\fR and \fI--forward-to\fR instead of \fI--as-proxy\fR to keep the standard error stream open.
.TP
.B \-d, --as-server
This is equivalent to \fI--log\fR and \fI--close-stderr\fR. It is a convenient way of running a background storage daemon that accepts mail messages and spools them. Use \fI--log\fR instead of \fI--as-server\fR to keep standard error stream open.
.TP
.B \-s, --spool-dir \fI<dir>\fR
Specifies the directory used for holding mail messages that have been received but not yet forwarded.
.TP
.B \-h, --help
Displays help text and then exits. Use with \fI--verbose\fR for more complete output.
.TP
.B \-V, --version
Displays version information and then exits.
.SS SMTP client options
.TP
.B \-f, --forward
Causes spooled mail messages to be forwarded when the program first starts.
.TP
.B \-1, --forward-on-disconnect
Causes spooled mail messages to be forwarded whenever a SMTP client connection disconnects.
.TP
.B \-o, --forward-to \fI<host:port>\fR
Specifies the transport address of the remote SMTP server that spooled mail messages are forwarded to.
.TP
.B \-O, --poll \fI<period>\fR
Causes forwarding of spooled mail messages to happen at regular intervals (with the time given in seconds).
.TP
.B \-Y, --client-filter \fI<program>\fR
Runs the specified external filter program whenever a mail message is forwarded. The filter is passed the name of the message file in the spool directory so that it can edit it as required. A network filter can be specified as \fInet:<tcp-address>\fR and prefixes of \fIspam:\fR, \fIspam-edit:\fR and \fIexit:\fR are also allowed. The \fIspam:\fR and \fIspam-edit:\fR prefixes require a SpamAssassin daemon to be running. For store-and-forward applications the \fI--filter\fR option is normally more useful than \fI--client-filter\fR.
.TP
.B \-6, --client-interface \fI<ip-address>\fR
Specifies the IP network address to be used to bind the local end of outgoing SMTP connections. By default the address will depend on the routing tables in the normal way. Use \fI0.0.0.0\fR to use only IPv4 addresses returned from DNS lookups of the \fI--forward-to\fR address, or \fI::\fR for IPv6.
.TP
.B \-U, --connection-timeout \fI<time>\fR
Specifies a timeout (in seconds) for establishing a TCP connection to remote SMTP servers. The default is 40 seconds.
.TP
.B --idle-timeout \fI<time>\fR
Specifies a timeout (in seconds) for receiving network traffic from remote SMTP and POP clients. The default is 60 seconds.
.TP
.B \-T, --response-timeout \fI<time>\fR
Specifies a timeout (in seconds) for getting responses from remote SMTP servers. The default is 60 seconds.
.TP
.B --forward-to-some
Allow forwarding to continue even if some recipient addresses on an e-mail envelope are rejected by the remote server.
.TP
.B \-m, --immediate
Causes mail messages to be forwarded as they are received, even before they have been accepted. This can be used to do proxying without store-and-forward, but in practice clients tend to to time out while waiting for their mail message to be accepted.
.SS SMTP server options
.TP
.B \-p, --port \fI<port>\fR
Sets the port number used for listening for incoming SMTP connections.
.TP
.B \-r, --remote-clients
Allows incoming connections from addresses that are not local. The default behaviour is to reject connections that are not local in order to prevent accidental exposure to the public internet, although a firewall should also be used. Local address ranges are defined in RFC-1918, RFC-6890 etc.
.TP
.B --address-verifier \fI<program>\fR
Runs the specified external program to verify a message recipent's e-mail address. A network verifier can be specified as \fInet:<tcp-address>\fR.
.TP
.B \-A, --anonymous, --anonymous=\fI<scope>\fR
Disables the server's SMTP VRFY command, sends less verbose SMTP greeting and responses, stops \fIReceived\fR lines being added to mail message content files, and stops the SMTP client protocol adding \fIAUTH=\fR to the \fIMAIL\fR command. For finer control use a comma-separated list of things to anonymise: \fIvrfy\fR, \fIserver\fR, \fIcontent\fR and/or \fIclient\fR, eg. \fI--anonymous\fR=server,content.
.TP
.B --dnsbl \fI<config>\fR
Specifies a list of DNSBL servers that are used to reject SMTP connections from blocked addresses. The configuration string is made up of comma-separated fields: the DNS server's transport address, a timeout in milliseconds, a rejection threshold, and then the list of DNSBL servers.
.TP
.B \-D, --domain \fI<fqdn>\fR
Specifies the network name that is used in SMTP EHLO commands, \fIReceived\fR lines, and for generating authentication challenges. The default is derived from a DNS lookup of the local hostname.
.TP
.B \-z, --filter \fI<program>\fR
Runs the specified external filter program whenever a mail message is stored. The filter is passed the name of the message file in the spool directory so that it can edit it as required. The mail message is rejected if the filter program terminates with an exit code between 1 and 99. Use \fInet:<tcp-address>\fR to communicate with a filter daemon over the network, or \fIspam:<tcp-address>\fR for a spamassassin spamd daemon to accept or reject mail messages, or \fIspam-edit:<tcp-address>\fR to have spamassassin edit the message content without rejecting it, or \fIexit:<number>\fR to emulate a filter program that just exits.
.TP
.B \-W, --filter-timeout \fI<time>\fR
Specifies a timeout (in seconds) for running a \fI--filter\fR program. The default is 60 seconds.
.TP
.B \-I, --interface \fI<ip-address-list>\fR
Specifies the IP network addresses or interface names used to bind listening ports. By default listening ports for incoming SMTP, POP and administration connections will bind the 'any' address for IPv4 and for IPv6, ie. \fI0.0.0.0\fR and \fI::\fR. Multiple addresses can be specified by using the option more than once or by using a comma-separated list. Use a prefix of \fIsmtp=\fR, \fIpop=\fR or \fIadmin=\fR on addresses that should apply only to those types of listening port. Any link-local IPv6 addresses must include a zone name or scope id.  Interface names can be used instead of addresses, in which case all the addresses associated with that interface at startup will used for listening. When an interface name is decorated with a \fI-ipv4\fR or \fI-ipv6\fR suffix only their IPv4 or IPv6 addresses will be used (eg. \fIppp0-ipv4\fR).  To inherit listening file descriptors from the parent process on unix use a syntax like this: \fI--interface\fR=smtp=fd#3,smtp=fd#4,pop=fd#5.
.TP
.B \-w, --prompt-timeout \fI<time>\fR
Specifies a timeout (in seconds) for getting the initial prompt from a remote SMTP server. If no prompt is received after this time then the SMTP dialog goes ahead without it.
.TP
.B \-M, --size \fI<bytes>\fR
Limits the size of mail messages that can be submitted over SMTP.
.SS POP server options
.TP
.B \-B, --pop
Enables the POP server, listening by default on port 110, providing access to spooled mail messages. Negotiated TLS using the POP \fISTLS\fR command will be enabled if the \fI--server-tls\fR option is also given.
.TP
.B \-J, --pop-by-name
Modifies the spool directory used by the POP server to be a sub-directory with the same name as the POP authentication user-id. This allows multiple POP clients to read the spooled mail messages without interfering with each other, particularly when also using \fI--pop-no-delete\fR. Content files can stay in the main spool directory with only the envelope files copied into user-specific sub-directories. The \fIemailrelay-filter-copy\fR program is a convenient way of doing this when run via \fI--filter\fR.
.TP
.B \-G, --pop-no-delete
Disables the POP DELE command so that the command appears to succeed but mail messages are not deleted from the spool directory.
.TP
.B \-E, --pop-port \fI<port>\fR
Sets the POP server's listening port number.
.SS Admin server options
.TP
.B \-a, --admin \fI<port>\fR
Enables an administration interface on the specified listening port number. Use telnet or something similar to connect. The administration interface can be used to trigger forwarding of spooled mail messages if the \fI--forward-to\fR option is used.
.TP
.B \-Q, --admin-terminate
Enables the \fIterminate\fR command in the administration interface.
.SS Authentication options
.TP
.B \-C, --client-auth \fI<file>\fR
Enables SMTP client authentication with the remote server, using the client account details taken from the specified secrets file. The secrets file should normally contain one line that starts with \fIclient\fR and that line should have between four and five space-separated fields; the second field is the password encoding (\fIplain\fR or \fImd5\fR), the third is the user-id and the fourth is the password. The user-id is RFC-1891 xtext encoded, and the password is either xtext encoded or generated by \fIemailrelay-passwd\fR. If the remote server does not support SMTP authentication then the SMTP connection will fail.
.TP
.B --client-auth-config \fI<config>\fR
Configures the SMTP client authentication module using a semicolon-separated list of configuration items. Each item is a single-character key, followed by a colon and then a comma-separated list. A 'm' character introduces an ordered list of preferred authentication mechanisms and an 'x' introduces a list of mechanisms to avoid. An 'a' list and a 'd' list can be used similarly to prefer and avoid certain mechanisms once the session is encrypted with TLS.
.TP
.B \-S, --server-auth \fI<file>\fR
Enables SMTP server authentication of remote SMTP clients. Account names and passwords are taken from the specified secrets file. The secrets file should contain lines that have four space-separated fields, starting with \fIserver\fR in the first field; the second field is the password encoding (\fIplain\fR or \fImd5\fR), the third is the client user-id and the fourth is the password. The user-id is RFC-1891 xtext encoded, and the password is either xtext encoded or generated by \fIemailrelay-passwd\fR. A special value of \fI/pam\fR can be used for authentication using linux PAM.
.TP
.B --server-auth-config \fI<config>\fR
Configures the SMTP server authentication module using a semicolon-separated list of configuration items. Each item is a single-character key, followed by a colon and then a comma-separated list. A 'm' character introduces an ordered list of allowed authentication mechanisms and an 'x' introduces a list of mechanisms to deny. An 'a' list and a 'd' list can be used similarly to allow and deny mechanisms once the session is encrypted with TLS. In typical usage you might have an empty allow list for an unencrypted session and a single preferred mechanism once encrypted, \fIm:;a:plain\fR.
.TP
.B \-F, --pop-auth \fI<file>\fR
Specifies a file containing valid POP account details. The file format is the same as for the SMTP server secrets file, ie. lines starting with \fIserver\fR, with user-id and password in the third and fourth fields. A special value of \fI/pam\fR can be used for authentication using linux PAM.
.SS TLS options
.TP
.B \-j, --client-tls
Enables negotiated TLS for outgoing SMTP connections; the SMTP STARTTLS command will be issued if the remote server supports it.
.TP
.B --client-tls-certificate \fI<pem-file>\fR
Defines the TLS certificate file when acting as a SMTP client. This file must contain the client's private key and certificate chain using the PEM file format. Alternatively, use this option twice with the first one specifying the key file and the second the certificate file. Keep the file permissions tight to avoid accidental exposure of the private key.
.TP
.B \-b, --client-tls-connection
Enables the use of a TLS tunnel for outgoing SMTP connections. This is for SMTP over TLS (SMTPS), not TLS negotiated within SMTP using STARTTLS.
.TP
.B --client-tls-required
Makes the use of TLS mandatory for outgoing SMTP connections. The SMTP STARTTLS command will be used before mail messages are sent out. If the remote server does not allow STARTTLS then the SMTP connection will fail.
.TP
.B --client-tls-server-name \fI<hostname>\fR
Defines the target server hostname in the TLS handshake. With \fI--client-tls-connection\fR this can be used for SNI, allowing the remote server to adopt an appropriate identity.
.TP
.B --client-tls-verify \fI<ca-list>\fR
Enables verification of the remote SMTP server's certificate against any of the trusted CA certificates in the specified file or directory. In many use cases this should be a file containing just your self-signed root certificate. Specify \fI<default>\fR for the TLS library's default set of trusted CAs.
.TP
.B --client-tls-verify-name \fI<cname>\fR
Enables verification of the CNAME within the remote SMTP server's certificate.
.TP
.B \-K, --server-tls
Enables TLS for incoming SMTP and POP connections. SMTP clients can then request TLS encryption by issuing the STARTTLS command. The \fI--server-tls-certificate\fR option must be used to define the server certificate.
.TP
.B --server-tls-certificate \fI<pem-file>\fR
Defines the TLS certificate file when acting as a SMTP or POP server. This file must contain the server's private key and certificate chain using the PEM file format. Alternatively, use this option twice with the first one specifying the key file and the second the certificate file. Keep the file permissions tight to avoid accidental exposure of the private key.
.TP
.B --server-tls-connection
Enables SMTP over TLS when acting as an SMTP server. This is for SMTP over TLS (SMTPS), not TLS negotiated within SMTP using STARTTLS.
.TP
.B --server-tls-required
Makes the use of TLS mandatory for any incoming SMTP and POP connections. SMTP clients must use the STARTTLS command to establish a TLS session before they can issue SMTP AUTH or SMTP MAIL-TO commands.
.TP
.B --server-tls-verify \fI<ca-list>\fR
Enables verification of remote SMTP and POP clients' certificates against any of the trusted CA certificates in the specified file or directory. In many use cases this should be a file containing just your self-signed root certificate. Specify \fI<default>\fR for the TLS library's default set of trusted CAs.
.TP
.B \-9, --tls-config \fI<options>\fR
Selects and configures the low-level TLS library, using a comma-separated list of keywords. If OpenSSL and mbedTLS are both built in then keywords of \fIopenssl\fR and \fImbedtls\fR will select one or the other. Keywords like \fItlsv1.0\fR can be used to set a minimum TLS protocol version, or \fI-tlsv1.2\fR to set a maximum version.
.SS Process options
.TP
.B \-x, --dont-serve
Disables all network serving, including SMTP, POP and administration interfaces. The program will terminate as soon as any initial forwarding is complete.
.TP
.B \-H, --hidden
Windows only. Hides the application window and disables all message boxes, overriding any \fI--show\fR option. This is useful when running as a windows service.
.TP
.B --localedir \fI<dir>\fR
Enables localisation and specifies the locale base directory where message catalogues can be found. An empty directory can be used for the built-in default.
.TP
.B \-t, --no-daemon
Disables the normal backgrounding at startup so that the program runs in the foreground, without forking or detaching from the terminal.  On Windows this disables the system tray icon so the program uses a normal window; when the window is closed the program terminates.
.TP
.B \-X, --no-smtp
Disables listening for incoming SMTP connections.
.TP
.B \-i, --pid-file \fI<path>\fR
Causes the process-id to be written into the specified file when the program starts up, typically after it has become a background daemon. The immediate parent directory is created if necessary.
.TP
.B \-u, --user \fI<username>\fR
When started as root the program switches to a non-privileged effective user-id when idle. This option can be used to define the idle user-id and also the group ownership of new files and sockets. Specify \fIroot\fR to disable all user-id switching. Ignored on Windows.
.SS Logging options
.TP
.B \-v, --verbose
Enables more verbose logging when used with \fI--log\fR, and more verbose help when used with \fI--help\fR.
.TP
.B \-l, --log
Enables logging to the standard error stream and to the syslog. The \fI--close-stderr\fR and \fI--no-syslog\fR options can be used to disable output to standard error stream and the syslog separately. Note that \fI--as-server\fR, \fI--as-client\fR and \fI--as-proxy\fR imply \fI--log\fR, and \fI--as-server\fR and \fI--as-proxy\fR also imply \fI--close-stderr\fR.
.TP
.B \-g, --debug
Enables debug level logging, if built in. Debug messages are usually only useful when cross-referenced with the source code and they may expose plaintext passwords and mail message content.
.TP
.B --log-address
Adds the network address of remote clients to the logging output.
.TP
.B \-N, --log-file \fI<file>\fR
Redirects standard-error logging to the specified file. Logging to the log file is not affected by \fI--close-stderr\fR. The filename can include \fI%d\fR to get daily log files; the \fI%d\fR is replaced by the current date in the local timezone using a \fIYYYYMMDD\fR format.
.TP
.B \-L, --log-time
Adds a timestamp to the logging output using the local timezone.
.TP
.B \-n, --no-syslog
Disables logging to the syslog. Note that \fI--as-client\fR implies \fI--no-syslog\fR.
.TP
.B \-k, --syslog, --syslog=\fI<facility>\fR
When used with \fI--log\fR this option enables logging to the syslog even if the \fI--no-syslog\fR option is also used. This is typically used as a convenient override when using \fI--as-client\fR.
.TP
.B \-e, --close-stderr
Causes the standard error stream to be closed soon after start-up. This is useful when operating as a background daemon and it is therefore implied by \fI--as-server\fR and \fI--as-proxy\fR.
.SH SEE ALSO
.BR emailrelay-submit (1),
.BR emailrelay-passwd (1),
.SH AUTHOR
Graeme Walker, mailto:graeme_walker@users.sourceforge.net