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 SMTP proxy and store-and-forward message transfer agent. It normally does simple store-and-forward mail relay to a fixed next-hop server, but it can be configured to do its own routing of outbound mail and also deliver inbound mail to local mailboxes.

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

-c, --client-smtp-config <config>
    Configures the SMTP client protocol using a comma-separated list of optional features, including 'pipelining', 'smtputf8strict', 'eightbitstrict' and 'binarymimestrict'.

-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-all
    Requires all recipient addresses to be accepted by the remote server before forwarding. This is currently the default behaviour so this option is for forwards compatibility only.

--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 recipient's e-mail address. A network verifier can be specified as net:<tcp-address>. The account: built-in address verifier can be used to check recipient addresses against the list of local system account names.

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

-s, --delivery-dir <dir>
    Specifies the base directory for mailboxes when delivering messages that have local recipients. This defaults to the main spool directory.

--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 list of DNSBL servers, an optional rejection threshold, an optional timeout in milliseconds, and optionally the transport address of the DNS server.

-D, --domain <fqdn>
    Specifies the domain name that is used in SMTP client EHLO commands, server EHLO responses, Received lines, and for generating authentication challenges. The SMTP client will use an IP address in the EHLO command if the given domain is not a dotted FQDN. If this option is not used at all then the default value is the canonical name returned from a DNS query of the local hostname, or the system's FQDN on Windows.

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

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

-Z, --server-smtp-config <config>
    Configures the SMTP server protocol using a comma-separated list of optional features, including 'pipelining', 'chunking', 'smtputf8', 'smtputf8strict', 'nostrictparsing' and 'noalabels'.

-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 POP server's spool directory to be the sub-directory with the same name as the user-id used for POP authentication. This allows POP clients to see only their own messages after they have been moved into separate sub-directories, typically by the built-in deliver: or copy: filters. Content files can remain in the main spool directory to save disk space; they will be deleted by the POP server when it deletes the last matching envelope file.

-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 account details taken from the specified secrets file. The secrets file should normally contain one line having between four and five space-separated fields. The first field must be client, the second field is the password type (plain or md5), the third is the xtext-encoded user-id and the fourth is the xtext-encoded password. Alternatively, the user-id and password fields can be Base64 encoded if the second field is plain:b. It is also possible to do without a secrets file and give the Base64 encoded user-id and password directly on the command-line or in the configuration file formatted as plain:<base64-user-id>:<base64-password>. Note that putting these account details on the command-line is not recommended because it will make the password easily visible to all users on the local machine.

--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. Alternatively, the username and password can be Base64 encoded if the second field is plain:b. 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> (including the angle brackets) 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 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> (including the angle brackets) 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.

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

-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 or when running external filter scripts and address verifiers. This option can be used to define the non-privileged user-id. It also determines the group ownership of new files and sockets if the directory owner is not 'sticky'. Specify root to disable all user-id switching.

  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 system log. The --close-stderr and --no-syslog options can be used to disable output to standard error stream and the system log 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 plain-text passwords and mail message content.

--log-address
    Adds the network address of remote clients to the logging output. Equivalent to --log-format=address.

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

--log-format
    Adds one or more fields to the logging output. The field names can include time, unit, address, port, msgid. The ordering is not significant.

-L, --log-time
    Adds a timestamp to the logging output using the local timezone. Equivalent to --log-format=time.

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

-k, --syslog, --syslog=<facility>
    When used with --log this option enables logging to the system log, 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
emailrelay-submit(1), emailrelay-passwd(1),

AUTHOR
Graeme Walker <graeme_walker@users.sourceforge.net>