sendooway.conf(5): the configuration file for the Sendooway SMTP proxy

NAME

sendooway.conf − the configuration file for the Sendooway SMTP proxy

SYNOPSIS

sendooway.conf is the central configuration file for sendooway(1). It is also used as per-user includes allowing users to define their own mail transfer settings.

FILE FORMAT

Every line consists of a keyword/value-pair which is separated by an equality sign (’=’). All characters that follow a hash (’#’) and completely empty lines are ignored. Both spaces (’ ’) and tab spaces (’\t’) can be used as separators around the equality sign or at the beginning of a line. But their use is not required.

Keywords and most values are not case-sensitive. Exceptions (e.g. passwords) will be described in the following sections. Values can be numbers, strings, booleans or part of an enumeration. Strings are not enclosed by inverted commas. Boolean values must be given as yes or no.

SECURITY CONSIDERATIONS

A sendooway.conf file might contain passwords in plain text. If that is true for you, this file should be owned by root with mode 0600. In all other cases it should not be writable by normal users.

EXPLANATION OF EACH KEYWORD

localname [string]

This should be set to the fully-qualified host name of your system. It is used to identify Sendooway to mail clients and external mail transfer agents using the SMTP EHLO command.

If no value is given (or this option is missing) Sendooway will use the return value of gethostname(). However it is strongly recommend specifying the host name by yourself.

cloneEhlo [boolean]

Every mail client has to identify itself before it is allowed to authenticate. Say yes here if you want Sendooway to clone this string when it connects to the remote server. You might want to set this option to hide the existence of Sendooway to remote systems. For this purpose see also addReceivedField below.

If no is specified (or this option is missing) Sendooway will use the value of localname instead.

addReceivedField [boolean]

Normally each SMTP server adds a Received line inside the mail header. If you want to hide the existence of Sendooway (e.g. use Sendooway as fully transparent proxy) you should set this option to no.

If yes is specified (or this option is missing) Sendooway will add a line inside the mail header.

timeout [number]

This is the maximum time in seconds Sendooway will wait when reading data from TCP connections (with a mail client or a remote server). When no data is received within this timeout the connection will be terminated. This value defaults to 300 seconds (5 minutes).

sslCA [string]

This file holds known certificate authorities. It defaults to /etc/ssl/certs/ca-certificates.crt but some distributions might use different file locations.

Users can redefine this value to use include their own CAs. This is especially reasonable when users trust certificates the system administrator does not want to trust -- or the other way around.

sslCert
sslKey [string]

These files contain the certificate/key when Sendooway acts as secure mail server. If Sendooway only serves local connections (or you are ssh tunneling) then you probably do not want to use encryption. In all other cases you really should generate a certificate to offer secured connections.

mailerEncryption [tristate]

This option controls how Sendooway handles secured connections. It knows about the following values:
allowed (default)

Connections may be secured by using the STARTTLS extension or the --ssl command line switch; however, a mail client is also allowed to send plain passwords over an unsecure channel.

required

Connections must be secured in order to authenticate.

forbidden

Entirely disables encryption support and allows unsecured authentication. This is only useful for connections that are known to be secure.

ext8BitMime [tristate]

Every modern MTA should support 8-bit encodings. Sendooway can handle this but it is unable to re-encode messages if the remote server relies on 7-bit data. Strictly speaking we must not accept 8-bit messages for backwards compatibility. The following values are accepted:
force (default)

Propagate 8-bit-mime support and fail if the remote host does not do the same. This would disable some very old SMTP servers.

disable

Do not propagate 8-bit-mime but support it anyway. You should only use this option when you 1) depend on very old servers and 2) use mail clients that fall back on 7-bit-encodings. Personally we would try to avoid this setting.

extMessageSize [multi]

This is the maximum message size in bytes a client is elated to submit. Be aware that this is only a very soft limit because clients might simply ignore this limitation. This option also breaks the standards since Sendooway might advertise a message limit which is higher than the maximum message size of the relevant server. Possible values are:
disable

Entirely disable the size extension. If set, Sendooway will not inform the client about message limits and might consume lots of useless traffic.

0 (default)

Advertise the size extension but do not inform the client about actual message length limitations. However the client is encourage to tell the actual message size before sending the message data. Sendooway can than relay this information to the remote server. This option is the recommend default.

smarthostPlain
smarthostLogin
smarthostCramMD5 [tristate]

Tells Sendooway which mechanisms should be used to authenticate at remote servers. Each of these three options can have one of the following values:
ifAdvertised (default)

Use this mechanism only if the remote server has advertised it. This is the default.

alwaysTry

Always try to use this mechanism no matter whether the remote server has advertised it. This is especially interesting for CRAM-MD5 because it tries to avoid sending a plain text password. This breaks standards and might corrupt the connection to some remote servers.

authBackend [tristate]

Sendooway can authenticate users against PAM or LDAP. Both modules might have been disabled at compile time. The following values are valid:
PAM (default)

Users are authenticated against PAM with the realm sendooway. Sendooway sends the password as response to the first PAM request. If you heavily modified your PAM configuration be sure to provide a simple backup for Sendooway. However, the default setup will work fine on most systems.

Sendooway uses NSS to request additional user attributes.

Sendooway uses LDAP to request additional user attributes.

Sendooway uses NSS to request additional user attributes.

ldapAuthDN [string]

If using the LDAP backend, Sendooway will validate users by authenticating them on the LDAP server. This value describes how usernames are mapped to DNs. The placeholder %u is replaced by the username. The corresponding entry must implement the posixaccount objectclass because Sendooway will work with the uidNumber, gidNumber and homedirectory attributes.

ldapUri [string]

If using the LDAP backend, this value must contain one or more LDAP servers. A server must be named in URI style which looks like ldap://example/, ldaps://example/ or ldap://example:port/. Several URIs can be seperated by spaces.

ldapSSLca [string]

This file holds known certificate authorities for the LDAP client. It defaults to be the same value as sslCA if not otherwise specified.

validUser [string]

This keyword is special. If there is no such keyword inside your configuration file every user is allowed to use Sendooway (as long as (s)he is able to authenticate against PAM/LDAP). This is, of course, the default behavior.

If Sendooway should only be available for selected users those have to be listed here. Note that this keyword has to be repeated for every single user. You can also enable an entire user group by specifying the group name prefixed with a percentage sign (’%’).

NOTE: The validUser keyword is currently not supported by the LDAP backend and will be ignored silently.

smarthostMapping [string]

This keyword can be given multiple times. It tells Sendooway where remote authentication information can be looked up. Surely this is the most important setting. Every mapping is prefixed with the adequate file type, followed by a colon (’:’) and the name of the file. Finally there are three supported file types:
getmail [filename]

Parse an adapted getmailrc-like file. Like above %h and %u are replaced with proper values. Mostly this option is specified in user configuration files. For more information see section USING GETMAILRC below.

fetchmail [filename]

Parse an adapted .fetchmailrc-like file. The strings %h and %u are replaced by the home path resp. the name of the authenticated user. See section USING FETCHMAILRC below.

direct [address] [server] [port] [username] [password] [options]

This format can be used if neither fetchmail nor getmail are used. Use it to connect users that send as [address] directly to the SMTP server on host [server] and listening on [port]; authenticate as [username] with the password [password]. [option] is a comma separated list of zero or more of the following keywords:

noCertCheck

If tls or ssl are defined, then errors on certificate validation are ignored. Nevertheless validation errors are always logged.

If the smarthostMapping keyword is neither given inside your global nor user configuration file, then the following default is used:

smarthostMapping = getmail:%h/.getmail/getmailrc
smarthostMapping = fetchmail:%h/.fetchmailrc

userInclude [string]

Some values should be defined on a per-user basis. As soon as a user is successfully authenticated agains PAM Sendooway will try use load the file specified here (%h and %u are replaced by the home dir resp. the name of according user). User settings are always preferred against global ones but Sendooway will fall back to global smarthostMappings if no per-user mapping fits. Since this file is loaded after user authentication some settings are useless (e.g. ext8BitMime and such).

All other keywords are rejected.

USING GETMAILRC

Each getmailrc-like defines exactly one mail account. If more than one account is used, multiple files have to be parsed. Unfortunately, there is no standard on where to save those files and you have to specify the location for each file. This is usually done with several smarthostMapping=getmail: entries inside your Sendooway configuration.

We assume that you are familiar with getmail(1) and its configuration files. Sendooway defines a new section named [sender]. Inside this section the following keyword-value-pairs are valid:

SimpleSMTPSender

Mails are sent over an unencrypted connection. You hopefully do not need this.

SimpleSMTPSSLSender

The SMTP connection is encrypted using the secured socket layer (SSL).

SimpleSMTPTLSSender

This is the most modern way of using the SMTP protocol. Sendooway will secure the connection using the transport layer security protocol (TLS).

no_certificate_check

If SimpleSMTPTLSSender or SimpleSMTPSSLSender are used above and this option is set to true, then errors on certificate validation are ignored. Nevertheless validation errors are always logged.

username

This is the username for the remote SMTP server. If this keyword is not given Sendooway will use the same username as getmail uses for mail retrieval. If you do not want to use remote side authentication, define an empty username here.

password

Like above but for your account password.

address

This keyword is mandatory. It defines the mail address which is used for outgoing mails. If the address matches the address a mail client uses as sender address, then (and only then) Sendooway connects to the server specified above. The address value can be defined multiple times if more than one mail address belongs to this account.

Below is an example. It asks getmail to retrieve mails for user alice and password secret from mailbox.moon.net. Sendooway will send outgoing mails over mx.moon.net with TLS encryption and the same account data as long as the sender address matches alice@moon.net or bobs_angel@moon.net.

[destination]
type = Maildir
path = ~/Maildir/

[retriever]
type = SimplePOP3SSLRetriever
server = mailbox.moon.net
username = alice
password = secret

[sender]
type = SimpleSMTPTLSSender
server = mx.moon.net
address = alice@moon.net
address = bobs_angel@moon.net

USING FETCHMAILRC

You can define several mail accounts inside a single fetchmailrc-like file. Normally you should only want to use those files if you are using fetchmail(1) and already know how it has to be configured to retrieve mails.

At the moment fetchmail does not allow additional information inside its configuration file. For that reason Sendooway’s keywords are prefixed with a hash (’#’) and thus be considered as comments. Foreach definied account Sendooway recognizes the following keywords:
#sendooway:server [smtp server]

This is mandatory and defines the SMTP server which has to be used for outgoing mails.

#sendooway:port [smtp port]

Per default Sendooway will try to contact the remote server on TCP port 587 (or port 465 for SSL connections). Port 25 is only used for unencrypted connections (but this might change in future). If you want to connect to another port it can be specified here. [smtp port] can be a numeric value between 1 and 65535 or the corresponding service name.

#sendooway:user [username]

This is the username for the outgoing SMTP connection. If this keyword is not given Sendooway will use the same username as fetchmail uses for mail retrieval.

#sendooway:pass [password]

Like above but for your account password.

#sendooway:tls

Connect to the SMTP server using the transport layer security protocol (TLS).

#sendooway:ssl

Connect to the SMTP server using the secured socket layer (SSL).

#sendooway:noCertCheck

If #sendooway:tls or #sendooway:ssl are defined, then errors on certificate validation are ignored. Nevertheless validation errors are always logged.

#sendooway:noAuth

Do not try to authenticate on remote side.

#sendooway:address [mail address]

This keyword is mandatory and must be the last option of any account. It defines the mail address which is used for outgoing mails. If this address matches the address a mail client uses as sender address then (and only then) Sendooway connects to the server specified above.

Below is an example. It asks fetchmail to retrieve mails for user alice and password secret from mailbox.moon.net. Sendooway will send outgoing mails over mx.moon.net with TLS encryption and the same account data as long as the sender address matches alice@moon.net.

server "mailbox.moon.net"
protocol pop3
user "alice"
pass "secret"
#sendooway:server "mx.moon.net"
#sendooway:tls
#sendooway:address "alice@moon.net"

AUTHOR

Michael Kammer

SEE ALSO

sendooway(1), fetchmail(1), getmail(1)

For the feature list and some default configuration files have a look at Sendooway’s beautiful homepage at http://www.kuspbv.de/sendooway/