251 lines
17 KiB
Groff
251 lines
17 KiB
Groff
.\" Copyright (C) 2001-2019 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
|
|
.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:<transport-address>\fR.
|
|
.TP
|
|
.B \-a, --admin \fI<admin-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.
|
|
.TP
|
|
.B \-A, --anonymous
|
|
Disables the server's SMTP VRFY command, sends less verbose SMTP responses and SMTP greeting, and stops \fIReceived\fR lines being added to mail message content files.
|
|
.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 \-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 authentication mechanisms, and an 'x' is used for blocklisted mechanisms.
|
|
.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:<transport-address>\fR and prefixes of \fIspam:\fR, \fIspam-edit:\fR and \fIexit:\fR are also allowed. 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 \-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. 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.
|
|
.TP
|
|
.B --client-tls-verify-name \fI<cname>\fR
|
|
Enables verification of the CNAME within the remote SMTP server's certificate.
|
|
.TP
|
|
.B \-e, --close-stderr
|
|
Causes the standard error stream to be closed soon after start-up. This is useful when operating as a backgroud daemon and it is therefore implied by \fI--as-server\fR and \fI--as-proxy\fR.
|
|
.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 \-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 --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 \-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 \-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:<transport-address>\fR to communicate with a filter daemon over the network, or \fIspam:<transport-address>\fR for a spamassassin spamd daemon to accept or reject mail messages, or \fIspam-edit:<transport-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 300 seconds.
|
|
.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 is use for mail message forwarding.
|
|
.TP
|
|
.B \-h, --help
|
|
Displays help text and then exits. Use with \fI--verbose\fR for more complete output.
|
|
.TP
|
|
.B \-H, --hidden
|
|
Windows only. Hides the application window and disables all message boxes. This is useful when running as a windows service.
|
|
.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 1800 seconds.
|
|
.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.
|
|
.TP
|
|
.B \-I, --interface \fI<ip-address-list>\fR
|
|
Specifies the IP network addresses 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. Use this option to limit listening to particular addresses (and by implication to particular network interfaces). 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.
|
|
.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 \-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 \-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 \-n, --no-syslog
|
|
Disables logging to the syslog. Note that \fI--as-client\fR implies \fI--no-syslog\fR.
|
|
.TP
|
|
.B \-i, --pid-file \fI<pid-file>\fR
|
|
Causes the process-id to be written into the specified file when the program starts up, typically after it has become a backgroud daemon.
|
|
.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 \-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 \-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.
|
|
.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 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.
|
|
.TP
|
|
.B \-p, --port \fI<port>\fR
|
|
Sets the port number used for listening for incoming SMTP connections.
|
|
.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 \-r, --remote-clients
|
|
Allows incoming connections from addresses that are not local. The default behaviour is to ignore connections that are not local in order to prevent accidental exposure to the public internet, but a firewall should also be used. The definition of 'local' is different for IPv4 and IPv6.
|
|
.TP
|
|
.B \-T, --response-timeout \fI<time>\fR
|
|
Specifies a timeout (in seconds) for getting responses from remote SMTP servers. The default is 1800 seconds.
|
|
.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 a preferred sub-set of the built-in authentication mechanisms, and an 'x' is used for blocklisted mechanisms.
|
|
.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. Keep the file permissions tight to avoid accidental exposure of the private key.
|
|
.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.
|
|
.TP
|
|
.B \-M, --size \fI<bytes>\fR
|
|
Limits the size of mail messages that can be submitted over SMTP.
|
|
.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 \-k, --syslog
|
|
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 \-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.
|
|
.TP
|
|
.B \-u, --user \fI<username>\fR
|
|
When started as root the program switches to an non-privileged effective user-id when idle. This option can be used to define which user-id is used. Specify \fIroot\fR to disable all user-id switching. Ignored on Windows.
|
|
.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 \-V, --version
|
|
Displays version information and then exits.
|
|
.SH SEE ALSO
|
|
.BR emailrelay-submit (1),
|
|
.BR emailrelay-passwd (1),
|
|
.SH AUTHOR
|
|
Graeme Walker, mailto:graeme_walker@users.sourceforge.net
|