EMAILRELAY

NAME

SYNOPSIS

emailrelay --as-server

emailrelay --as-client server-address

emailrelay --as-proxy server-address  

DESCRIPTION

It runs in two main modes: a storage daemon (--as-server) and a forwarding agent (--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.

It can also run in a third mode, as a proxy server (--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.  

OPTIONS

Basic options

-q, --as-client <host:port>

This is equivalent to --log, --no-syslog, --no-daemon, --dont-serve, --forward and --forward-to. It is a convenient way of running a forwarding agent that forwards spooled mail messages and then terminates.

-y, --as-proxy <host:port>

This is equivalent to --log, --close-stderr, --forward-on-disconnect and --forward-to. It is a convenient way of running a store-and-forward daemon. Use --log, --forward-on-disconnect and --forward-to instead of --as-proxy to keep the standard error stream open.

-d, --as-server

This is equivalent to --log and --close-stderr. It is a convenient way of running a background storage daemon that accepts mail messages and spools them. Use --log instead of --as-server to keep standard error stream open.

-s, --spool-dir <dir>

Specifies the directory used for holding mail messages that have been received but not yet forwarded.

-h, --help

Displays help text and then exits. Use with --verbose for more complete output.

-V, --version

Displays version information and then exits.

SMTP client options

-f, --forward

Causes spooled mail messages to be forwarded when the program first starts.

-1, --forward-on-disconnect

Causes spooled mail messages to be forwarded whenever a SMTP client connection disconnects.

-o, --forward-to <host:port>

Specifies the transport address of the remote SMTP server that spooled mail messages are forwarded to.

-O, --poll <period>

Causes forwarding of spooled mail messages to happen at regular intervals (with the time given in seconds).

-Y, --client-filter <program>

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 net:<tcp-address> and prefixes of spam:, spam-edit: and exit: are also allowed. The spam: and spam-edit: prefixes require a SpamAssassin daemon to be running. For store-and-forward applications the --filter option is normally more useful than --client-filter.

-6, --client-interface <ip-address>

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 0.0.0.0 to use only IPv4 addresses returned from DNS lookups of the --forward-to address, or :: for IPv6.

-U, --connection-timeout <time>

Specifies a timeout (in seconds) for establishing a TCP connection to remote SMTP servers. The default is 40 seconds.

--idle-timeout <time>

Specifies a timeout (in seconds) for receiving network traffic from remote SMTP and POP clients. The default is 60 seconds.

-T, --response-timeout <time>

Specifies a timeout (in seconds) for getting responses from remote SMTP servers. The default is 60 seconds.

--forward-to-some

Allow forwarding to continue even if some recipient addresses on an e-mail envelope are rejected by the remote server.

-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.

SMTP server options

-p, --port <port>

Sets the port number used for listening for incoming SMTP connections.

-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.

--address-verifier <program>

Runs the specified external program to verify a message recipent's e-mail address. A network verifier can be specified as net:<tcp-address>.

-A, --anonymous, --anonymous=<scope>

Disables the server's SMTP VRFY command, sends less verbose SMTP greeting and responses, stops Received lines being added to mail message content files, and stops the SMTP client protocol adding AUTH= to the MAIL command. For finer control use a comma-separated list of things to anonymise: vrfy, server, content and/or client, eg. --anonymous=server,content.

--dnsbl <config>

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.

-D, --domain <fqdn>

Specifies the network name that is used in SMTP EHLO commands, Received lines, and for generating authentication challenges. The default is derived from a DNS lookup of the local hostname.

-z, --filter <program>

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 net:<tcp-address> to communicate with a filter daemon over the network, or spam:<tcp-address> for a spamassassin spamd daemon to accept or reject mail messages, or spam-edit:<tcp-address> to have spamassassin edit the message content without rejecting it, or exit:<number> to emulate a filter program that just exits.

-W, --filter-timeout <time>

Specifies a timeout (in seconds) for running a --filter program. The default is 60 seconds.

-I, --interface <ip-address-list>

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. 0.0.0.0 and ::. Multiple addresses can be specified by using the option more than once or by using a comma-separated list. Use a prefix of smtp=, pop= or admin= 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 -ipv4 or -ipv6 suffix only their IPv4 or IPv6 addresses will be used (eg. ppp0-ipv4). To inherit listening file descriptors from the parent process on unix use a syntax like this: --interface=smtp=fd#3,smtp=fd#4,pop=fd#5.

-w, --prompt-timeout <time>

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.

-M, --size <bytes>

Limits the size of mail messages that can be submitted over SMTP.

POP server options

-B, --pop

Enables the POP server, listening by default on port 110, providing access to spooled mail messages. Negotiated TLS using the POP STLS command will be enabled if the --server-tls option is also given.

-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 --pop-no-delete. Content files can stay in the main spool directory with only the envelope files copied into user-specific sub-directories. The emailrelay-filter-copy program is a convenient way of doing this when run via --filter.

-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.

-E, --pop-port <port>

Sets the POP server's listening port number.

Admin server options

-a, --admin <port>

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 --forward-to option is used.

-Q, --admin-terminate

Enables the terminate command in the administration interface.

Authentication options

-C, --client-auth <file>

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 client and that line should have between four and five space-separated fields; the second field is the password encoding (plain or md5), 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 emailrelay-passwd. If the remote server does not support SMTP authentication then the SMTP connection will fail.

--client-auth-config <config>

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.

-S, --server-auth <file>

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 server in the first field; the second field is the password encoding (plain or md5), 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 emailrelay-passwd. A special value of /pam can be used for authentication using linux PAM.

--server-auth-config <config>

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, m:;a:plain.

-F, --pop-auth <file>

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 server, with user-id and password in the third and fourth fields. A special value of /pam can be used for authentication using linux PAM.

TLS options

-j, --client-tls

Enables negotiated TLS for outgoing SMTP connections; the SMTP STARTTLS command will be issued if the remote server supports it.

--client-tls-certificate <pem-file>

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.

-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.

--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.

--client-tls-server-name <hostname>

Defines the target server hostname in the TLS handshake. With --client-tls-connection this can be used for SNI, allowing the remote server to adopt an appropriate identity.

--client-tls-verify <ca-list>

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 <default> for the TLS library's default set of trusted CAs.

--client-tls-verify-name <cname>

Enables verification of the CNAME within the remote SMTP server's certificate.

-K, --server-tls

Enables TLS for incoming SMTP and POP connections. SMTP clients can then request TLS encryption by issuing the STARTTLS command. The --server-tls-certificate option must be used to define the server certificate.

--server-tls-certificate <pem-file>

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.

--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.

--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.

--server-tls-verify <ca-list>

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 <default> for the TLS library's default set of trusted CAs.

-9, --tls-config <options>

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 openssl and mbedtls will select one or the other. Keywords like tlsv1.0 can be used to set a minimum TLS protocol version, or -tlsv1.2 to set a maximum version.

Process options

-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.

-H, --hidden

Windows only. Hides the application window and disables all message boxes, overriding any --show option. This is useful when running as a windows service.

--localedir <dir>

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.

-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.

-X, --no-smtp

Disables listening for incoming SMTP connections.

-i, --pid-file <path>

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.

-u, --user <username>

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 root to disable all user-id switching. Ignored on Windows.

Logging options

-v, --verbose

Enables more verbose logging when used with --log, and more verbose help when used with --help.

-l, --log

Enables logging to the standard error stream and to the syslog. The --close-stderr and --no-syslog options can be used to disable output to standard error stream and the syslog separately. Note that --as-server, --as-client and --as-proxy imply --log, and --as-server and --as-proxy also imply --close-stderr.

-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.

--log-address

Adds the network address of remote clients to the logging output.

-N, --log-file <file>

Redirects standard-error logging to the specified file. Logging to the log file is not affected by --close-stderr. The filename can include %d to get daily log files; the %d is replaced by the current date in the local timezone using a YYYYMMDD format.

-L, --log-time

Adds a timestamp to the logging output using the local timezone.

-n, --no-syslog

Disables logging to the syslog. Note that --as-client implies --no-syslog.

-k, --syslog, --syslog=<facility>

When used with --log this option enables logging to the syslog even if the --no-syslog option is also used. This is typically used as a convenient override when using --as-client.

-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 --as-server and --as-proxy.

SEE ALSO

AUTHOR

Index

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

Basic options

SMTP client options

SMTP server options

POP server options

Admin server options

Authentication options

TLS options

Process options

Logging options

SEE ALSO

AUTHOR