EMAILRELAY(1)

NAME
emailrelay - e-mail transfer agent and proxy

SYNOPSIS
emailrelay [OPTIONS]

emailrelay --as-server

emailrelay --as-client server-address

emailrelay --as-proxy server-address

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

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

--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:<transport-address>.

-a, --admin <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.

-A, --anonymous
    Disables the server's SMTP VRFY command, sends less verbose SMTP responses and SMTP greeting, and stops Received lines being added to mail message content files.

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

-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 authentication mechanisms, and an 'x' is used for blocklisted mechanisms.

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

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

--client-tls-verify-name <cname>
    Enables verification of the CNAME within the remote SMTP server's certificate.

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

-U, --connection-timeout <time>
    Specifies a timeout (in seconds) for establishing a TCP connection to remote SMTP servers. The default is 40 seconds.

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

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

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

-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:<transport-address> to communicate with a filter daemon over the network, or spam:<transport-address> for a spamassassin spamd daemon to accept or reject mail messages, or spam-edit:<transport-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 300 seconds.

-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 is use for mail message forwarding.

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

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

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

--idle-timeout <time>
    Specifies a timeout (in seconds) for receiving network traffic from remote SMTP and POP clients. The default is 1800 seconds.

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

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

--localedir <dir>
    Specifies a locale base directory where localisation message catalogues can be found. An empty directory can be used for the built-in default.

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

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

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

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

-i, --pid-file <pid-file>
    Causes the process-id to be written into the specified file when the program starts up, typically after it has become a backgroud daemon.

-O, --poll <period>
    Causes forwarding of spooled mail messages to happen at regular intervals (with the time given in seconds).

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

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

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

-p, --port <port>
    Sets the port number used for listening for incoming SMTP connections.

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

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

-T, --response-timeout <time>
    Specifies a timeout (in seconds) for getting responses from remote SMTP servers. The default is 1800 seconds.

-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 a preferred sub-set of the built-in authentication mechanisms, and an 'x' is used for blocklisted mechanisms.

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

-M, --size <bytes>
    Limits the size of mail messages that can be submitted over SMTP.

-s, --spool-dir <dir>
    Specifies the directory used for holding mail messages that have been received but not yet forwarded.

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

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

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

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

-V, --version
    Displays version information and then exits.

SEE ALSO
emailrelay-submit(1), emailrelay-passwd(1),

AUTHOR
Graeme Walker, mailto:graeme_walker@users.sourceforge.net