MeTA1 README

Claus Aßmann

Contents

Chapter 1
Introduction to MeTA1

1.1  MeTA1 is a Message Transfer Agent

1.1.1  Main Components of MeTA1

1.2  Documentation

1.2.1  Typographical Conventions

$ command

# command

1.3  Version

1.3.1  Providing Feedback

< MeTA1 + feedback (at) MeTA1 . org >

1.4  For the Impatient

Chapter 2
Building, Testing, and Installing MeTA1

2.1  Verifying the Source Code Distribution

2.2  Building MeTA1

$ mkdir obj.$OS && cd obj.$OS && $PATHTO/meta1-$VERSION/configure $OPTIONS \
  && make && make check

$ ./configure && make && make check

2.2.1  Compile-Time Configuration Options

--enable-TLS Enable check for STARTTLS support. The default is yes, i.e., configure tries to determine whether OpenSSL is available on the machine. Requires OpenSSL 0.9.8 or newer [Ope]. Note: check the OpenSSL website [Ope] for security announcement and be aware that due to the complexity of the software it may cause (security) problems.

--enable-SASL Enable check for AUTH support. The default is yes, i.e., configure tries to determine whether Cyrus SASL v2 is available on the machine. Requires Cyrus SASL version 2.1.18 or newer [Cyr]. Notes:

1. check http://asg.web.cmu.edu/cyrus/ and http://asg.web.cmu.edu/sasl/ for security announcement and be aware that due to the complexity of the software it may cause (security) problems.
2. If Cyrus SASL uses Berkeley DB then it is necessary that the version which has been used during compilation matches the version that it is linked against.

--with-sasl-libdir=path Path to directory containing Cyrus SASL v2 library.

--with-sasl-incdir=path Path to directory containing Cyrus SASL v2 include files.

--disable-included-bdb MeTA1 ships with a modified version of Berkeley DB 4.3.28 which is built and used by default. To use a different version of Berkeley DB (it must be 4.3, 4.2, or 4.1), e.g., one that is part of the host OS, specify --disable-included-bdb.

Notes:

1. If you do not use the Berkeley DB version that comes with MeTA1, make sure you run all the tests. For example, with Berkeley DB 4.2.50 on OpenBSD 3.2/i386 at least one of the test programs fails and hence this combination must not be used. Moreover, if you encounter a problem using some other BDB version then you must try to reproduce the problem with the shipped version before reporting a possible bug.
2. Do not use Berkeley DB 4.3.27/28 in 64 bit mode on Solaris 5.8/9 as it crashes at least in those configurations⁴. This bug is fixed in the version that is distributed with MeTA1.

--with-bdb-libdir=path Path to directory containing Berkeley DB library. This option is only needed if --disable-included-bdb is used and Berkeley DB is not installed in a location that the compiler or linker use by default. Note: configure currently checks only for a static library.

--with-bdb-incdir=path Path to directory containing Berkeley DB include files. This option is only needed if --disable-included-bdb is used and Berkeley DB is not installed in a location that the compiler uses by default. Example:

$ B=/usr/local/BerkeleyDB.4.3
$ $PATHTO/meta1-$VERSION/configure --with-bdb-libdir=$B/lib \
  --with-bdb-incdir=$B/include --disable-included-bdb

--enable-pmilter Enable policy milter protocol, see Chapter 5.

--enable-msp Enable a simple mail submission program (MSP) that is currently not supported (located in contrib/). This is just a helper program for those who do not want to install a different MSP but need only some basic functionality (which does not include a queueing mechanism). Note: this will install the MSP as sendmail thus overriding any existing program of that name (as well as a man page).

--enable-DKIM Enable DKIM [DKI] signing support in the SMTP server.

--enable-tinycdb Enable support for cdb map type, based on tinycdb 0.75 [Tok].

2.3  Test Programs

$ make check

$ make -i check >check.out 2>&1

2.3.1  Environment Variables used by Test Programs

• MTA_NO_DNS_TEST : if not set to false then most tests which perform DNS lookups are disabled to avoid misleading failures. These lookups may use domains that are under control of the MeTA1 author.
• MTA_DNS_TIMEOUT : can be used to set a different timeout than the default, however, it may not be obeyed by all DNS test programs.
• MTA_TEST_DNS_TIMING : run DNS tests that are timing dependent and may fail under certain conditions (e.g., network too slow).
• MTA_TIMING : run MTA tests that are timing dependent and may fail under certain conditions.
• MTA_STOPONERROR : causes most test scripts that perform multiple checks to stop on the first error that occurs instead of performing all checks.
• MTA_NO_LOG_TEST : disables some tests that use syslog(3).
• MTA_NO_SLOW_TEST : disables some tests that take a very long time.

$ MTA_DNS_TIMEOUT=60
$ MTA_NO_SLOW_TEST=1
$ export MTA_DNS_TIMEOUT MTA_NO_SLOW_TEST
$ make -i check

2.3.2  Known Test Program Problems

• connctl.sh will fail on systems that have neither inet_pton(3) nor inet_aton(3). Fix: upgrade your OS or write a replacement function and put it into librepl/.
• t-evthr-slp can fail in some circumstances if the OS is busy with other tasks as it depends on the OS scheduler. Fix: just rerun the test.
• t-evthr-sig.sh fails on Linux systems that use a thread implementation that is not POSIX compliant. The test is currently disabled on all Linux versions. Note: if you know a simple way to figure out whether the OS actually provides POSIX compliant pthreads, please let me know.
• t-hostname fails on systems where gethostname() does not return any FQHN at all (e.g., default SunOS 4/5 installations). Add the FQHN as alias to /etc/hosts (see hosts(5) to solve this problem, e.g.,

  	10.1.2.3    myname myname.my.domain
  
  

  or

  	10.1.2.3    myname.my.domain myname
  
  
• t-parsesockstr fails on systems like AIX which treat an empty string as a valid IP address in inet_addr(3).
• t-mts-icr.sh and t-mts-ocr-?.sh try to test incoming/outgoing rate control. They rely on the time it takes to send/receive mails which may not work on machines that are significantly slower or faster than the machines available to the author.
• t-smar-0.sh, t-smar-3.sh, and t-dns-1.sh may fail sometimes due to DNS timeouts. Run the tests again or increase the DNS timeout, see Section 2.3.1.

2.4  Installing MeTA1

meta1s:*:260:260:meta1 SMTPS:/nonexistent:/sbin/nologin
meta1q:*:261:261:meta1 QMGR:/nonexistent:/sbin/nologin
meta1c:*:262:262:meta1 SMTPC:/nonexistent:/sbin/nologin
meta1m:*:263:263:meta1 misc:/nonexistent:/sbin/nologin
meta1:*:264:264:meta1 other:/nonexistent:/sbin/nologin

meta1s:*:260:
meta1q:*:261:
meta1c:*:262:meta1s
meta1m:*:263:meta1s,meta1q
meta1:*:264:

$ ./misc/sm.check.sh -p

• MTACONFDIR : [/etc/meta1] configuration directory.
• MTAQDIR : [/var/spool/meta1] queue directory; communication sockets are created in this directory by default too.
• MTALOGDIR : [.] logging directory (relative to MTAQDIR). If logging is done via syslog(3) then this directory is not used.
• MTAS [meta1s] SMTP Server user and group.
• MTAC [meta1c] SMTP Client user and group.
• MTAQ [meta1q] QMGR user and group.
• MTAM [meta1m] address resolver (misc) user and group.
• MTA [meta1] generic (configuration etc) user and group.
• MTALG group for logfiles; the install program tries operator, sysadmin, and root.

1. The users and groups must be created before make install is invoked.
2. misc/sm.setup.sh will not overwrite existing files or directories, hence it does not work for upgrading a system if configuration files or directory/file owners need to changed.

2.4.1  Directories, Files, and Permissions

drwxrwx--x  2 meta1s  meta1q        0/

-rw-r-----  1 meta1s  meta1c  1993 Jul  9 21:19 2/S000000000006B1D200

drwx------  2 meta1q  meta1q        defedb/
drwx------  2 meta1q  meta1q        ibdb/
drwx------  2 meta1q  meta1q        ibdb/ibdb/

-rw-r--r--  1 meta1m  meta1m         mt
-rw-r--r--  1 meta1m  meta1m         aliases.db

-rw-r--r--  1 meta1   meta1          meta1.conf

drwxrws---  2 meta1q  meta1m        qmsmar/
drwxrws---  2 meta1q  meta1c        qmsmtpc/
drwxrws---  2 meta1q  meta1s        qmsmtps/

drwxr-x---  2 meta1s  meta1s        smtps/

-rw-r-----  1 meta1q  operator   qmgr.log
-rw-r-----  1 meta1m  operator   smar.log
-rw-r-----  1 meta1c  operator   smtpc.log
-rw-r-----  1 meta1s  operator   smtps.log

# ./misc/sm.check.sh -P

2.4.2  Upgrading from earlier MeTA1 Versions

• To check whether an installation was successful, run

  # ./misc/sm.check.sh -P
  
  
• To check whether the configuration file needs changes, run

  $ ./misc/smconf /etc/meta1/meta1.conf
  
  

  If the file is syntactically invalid for this version of MeTA1 the program will show those errors. Use -h as argument to see the available option, e.g., -u might be useful.

Chapter 3
Run-Time Configuration of MeTA1

3.1  Overview

3.2  Configuration File Syntax

3.2.1  Configuration File Values

  somemessage = "this is a very long string which is spread "
     "out over several lines because otherwise it is too "
     "hard too read.";

3.3  Example Configuration File

CDB_base_directory = "/var/spool/meta1/";

qmgr {
  AQ_entries_max = 8192;
  smtpc { initial_connections = 19; connections_max = 101; }
  smtps { connections_max = 5; connection_rate_max=160; }
  errors_per_DSN_max=16;
  wait_for_server = 4; wait_for_client = 4;
  start_action = wait; user = meta1q;
  restart_dependencies = { smtps, smtpc, smar };
  path = "/usr/libexec/qmgr"; arguments = "qmgr -f /etc/meta1/meta1.conf";
}

smtps { flags = {8bitmime}; CDB_gid = 261; IO_timeout = 5m3s;
  listen_socket { type = inet; port = 25; }
  start_action = pass; pass_fd_socket = smtps/smtpsfd;
  user = meta1s; path = /usr/libexec/smtps;
  arguments = "smtps -f /etc/meta1/meta1.conf"; }

smtpc {
  Log_Level = 12; IO_timeout = 6m; wait_for_server = 4;
  start_action = wait; user = meta1c; path = "/usr/libexec/smtpc";
  arguments = "smtpc -f /etc/meta1/meta1.conf"; }

smar {
  Log_Level = 12;
  DNS {
    nameservers = {10.10.10.9, 127.0.0.1};
    timeout = 6;
  }
  start_action = wait; user = meta1m; restart_dependencies = { smtps, qmgr };
  path = "/usr/libexec/smar"; arguments = "smar -f /etc/meta1/meta1.conf";
}

3.4  Common Global Configuration

1. hostname : set the hostname to use for the various components. This can be set if gethostbyname(3) does not return a valid (fully qualified) hostname (format: string).
2. CDB_base_directory : base directory of CDB (format: string); this should either be empty (which is the default) or a path to a directory including a trailing slash; the CDB library currently simply appends the directory names (see Section 2.4.1) to it. It might be useful to move some subdirectories to different disks (by creating (symbolic) links (ln(1))) to spread the I/O load.
3. SMAR_socket : socket created by the address resolver over which clients (SMTPS, QMGR) can send requests (format: string).
4. SMTPC_socket : communication socket between SMTPC and QMGR (format: string).
5. SMTPS_socket : communication socket between SMTPS and QMGR (format: string).

3.5  Common Configuration Options

1. log : this is a section with the following options:
   1. facility : see syslog(3) for valid facilities, here are some valid options provided the OS offers them: daemon, mail, auth, local0, etc.
   2. ident : identification string for openlog(3), defaults to name of the modules. It might be useful to chose other identifiers, e.g., MeTA1 or MeTA1QMGR.
   3. options : options for openlog(3) (without the leading LOG_) as provided by the OS, e.g., pid or ndelay.
   Example:

   qmgr { log { facility = daemon; ident=meta1-qmgr; } }
   smtps { log { facility = mail; ident=meta1-MTA; } }
   
   

   Note: debug output is currently sent to stdout or stderr; syslog(3) is not used for debugging.

3.6  Pathnames for Files, Directories, and Maps

1. the configuration directory: maps and configuration files, e.g., aliases.db and cert_file.
2. the main queue directory: pathnames of sockets, and databases to store envelope information (IBDB, DEFEDB) or message contents (CDB).

3.7  Configuration for MCP

1. start_action : one of nostartaccept, accept, pass, wait (required).
2. listen_socket : this is a subsection that specifies the socket on which a process should listen. It must be specified for any start_action except wait. There are three different socket types available: (IPv6 requires the compile time option MTA_NETINET6)
   1. type = inet
      1. port : port number on which process should listen (format: numeric).
      2. address : IP address on which process should listen, if none is specified the process listens on all local (IPv4) addresses (format: IPv4 address).
   2. type = inet6
      1. port : port number on which process should listen (format: numeric).
      2. address : IP address on which process should listen, if none is specified the process listens on all local (IPv6) addresses (format: IPv6 address).
   3. type = unix
      1. path : pathname of Unix Domain socket on which process should listen (format: string).
      2. umask : umask for socket (format: numeric).
      3. user : owner of socket (format: string).
      4. group : group of socket (format: string).
3. pass_fd_socket : pathname of Unix Domain socket to pass a file descriptor to the process.
4. user : user name to run process.
5. group : group name to run process.
6. restart_dependencies : list of other MeTA1 components that need to be restarted when this one is restarted.
7. path : path to program to execute (required).
8. arguments : arguments (argv), must start with name of program, see execv(2) (required).
9. pass_id : this configuration option specifies the command line option for the process to be spawned that MCP must use to pass a unique, numeric identifier. The command line option will be inserted as first argument. It is useful if more than one process should be started and the invocations need a unique id. Example:

   smtpc { pass_id = "-i"; processes_min = 4; processes_max = 4;
     path = /usr/libexec/smtpc; arguments = "smtpc -f meta1.conf"; }
   
   

   will cause MCP to start four smtpc processes, each with the options -iID -f meta1.conf where ID is replaced with a unique identifier. Note: currently the option must start with a hyphen and have exactly one character after that.
10. failure_max : override the builtin limit for service failures. This can be useful for services that are started for individual requests but may fail in various ways. By setting the value to 0, MCP will still restart the service for each request.

• For start_action = pass the option pass_fd_socket must be specified; in this case MCP binds to the specified socket (listen_socket) and passes it via the Unix domain socket (pass_fd_socket) to the started process.
• For start_action = nostartaccept MCP waits for incoming connections, and then starts a process to handle a single connection.
• For start_action = accept MCP binds to the socket and then starts a process to handle the connections without waiting for an actual request.
• For start_action = wait MCP simply starts the requested number of processes without passing them any open connections. This is intended for processes that do not communicate with external clients.

3.8  Configuration for QMGR

1. AQ_entries_max : maximum number of entries in AQ (active queue) (unit: entries). Note: this value must be larger than the largest number of recipients accepted by a single transaction.
2. conf : name of configuration map (including extension), see Section 3.8.1 for details. See also Section 3.6 about relative pathnames.
3. control_socket : specify pathname of "control" socket (for querying and making requests). This socket can be used by the query/control program qmgrctl, see Section 4.7.3.
4. subsection DEFEDB:
   1. base_directory : home directory for DEFEDB.
   2. log_directory : log directory for DEFEDB. For better performance, this directory can be set to point to a different disk than the base directory of DEFEDB.
5. subsection DSN_handling:
   1. merge_delay_max : maximum time to wait for merging multiple DSNs into one (unit: s).
   2. flags : configuration flags:
      1. header_only : include only the headers in a DSN; by default the first bounce includes the entire message and subsequent ones include only the headers.
      2. MIME_Format : use MIME to structure a DSN. Note: this is not a DSN in the format specified by RFC 3464 [MV03], use RFC_Format (see 5(b)iii) instead.
      3. RFC_Format : create DSNs in the format specified by RFC 3464 [MV03].
      4. no_LMTP_delay_DSN : do not generate a delay DSN if the RCPT is delivered via lmtp.
   3. errors_per_DSN_max : maximum number of error messages (failed recipients) in a bounce (DSN) (unit: entries).
6. double_bounce_address : RFC 2821 address for double bounces; defaults to <doublebounce@hostname>. The SMTP server discards mails to this address if the sender address is <>.
7. subsection IBDB:
   1. commit_delay_max : maximum time between commits to IBDB (unit: ms)
   2. size : maximum size of each IBDB file (unit: B).
   3. open_TAs_max : maximum number of open transactions in IBDB before a commit is performed (unit: entries).
   Note: the configuration file offers no way to specify a base directory for IBDB, however, the directory can be easily moved elsewhere and a (symbolic) link (ln(1)) can be added.
8. subsection IQDB:
   1. cache_entries_max : maximum number of entries in IQDB cache (unit: entries). This must be larger than the sum of all recipients in open transactions.
   2. hash_table_entries : size of hash table for IQDB (unit: entries). This must be larger than cache_entries_max.
9. log_level : logging level.
10. disk_space_min : minimum amount of free disk space (unit: KB). This value should be significantly larger than the maximum size of a message to be accepted by the SMTP server, it should be as large as the maximum message size multiplied by the maximum number of incoming connections.
11. disk_space_ok : amount of free disk space at which normal operation continues (unit: KB). Must be larger than disk_space_min.
12. OCC_entries_max : size of outgoing (SMTPC) connection cache (unit: entries). This should be large enough to keep track of outgoing connections over a time span that is at least as long as the maximum retry time.
13. There are two subsections which relate to the time of messages in the queue:
    1. queue_return : maximum time in queue (unit: s).
    2. subsection queue_delay : send delay warning ("delayed DSN") if the mail is still in the queue after at least this duration (unit: s). To turn off delayed DSNs set this 0. Note: based on the retry schedule the delayed DSN might be sent later than the option specifies.
    Each of them has two possible entries: default and DANE_no_match. The latter is only available if DANE is enabled (see section 14.2). It is used for those case where a delivery fails because the destination provides usable TLSA records, but none of them matches the fingerprint of the provided certificate. This allows to try delivery again in case of a misconfiguration of the server or DNS. For all other error cases, the default value is used.
14. retry_delay_max : maximum time for retrying a delivery (unit: s).
15. retry_delay_min : minimum time for retrying a delivery (unit: s).
16. subsection smtpc:
    1. initial_connections : maximum initial number of outgoing connections to a single host (unit: entries). The sliding window for the slow start algorithm (see Section 3.8.1) is initialized with this value.
    2. connections_max : maximum number of outgoing connections to a single host (unit: entries).
    3. transactions_per_session_max : maximum number of transactions per session (unit: entries).
    4. lmtp_rcpts_per_transaction_max : maximum number of recipients per transaction for mail sent via LMTP (unit: entries).
    5. smtp_rcpts_per_transaction_max : maximum number of recipients per transaction for mail sent via (E)SMTP (unit: entries).
    6. subsection connection_limits : This named section can be specified multiple times. An entry is selected via the configuration map for QMGR (Section 3.8.1) using the tag smtpc_conf_rcpt_domain with the domain part of the recipient as argument.
       1. initial_connections : maximum initial number of outgoing connections to a single host (unit: entries).
       2. connections_max : maximum number of outgoing connections to a single host (unit: entries).
       3. transactions_per_session_max : maximum number of transactions per session (unit: entries).
       Example:
       Configuration file:

       connection_limits low {
         initial_connections = 1;
         connections_max = 2;
       }
       
       

       Map entry:

       smtpc_conf_rcpt_domain:example.com	connection_limits=low;
       
       
    7. flags : configuration flags:
       1. lookup_rcpt_conf : Look up recipient configuration data (see Section 3.11.1) in the access map (see Section 3.9.3)
       2. lookup_session_conf : Look up session configuration data (see Section 3.11.1) in the configuration map (see item 2). This flag is needed if there is no session_features section in smtpc (see Section 3.11, item 5), but only entries in the map containing other configuration option, e.g., tls_requirements.
    8. rcpt_conf_lookup_flags : If recipient configuration data (see item 16(g)i) is looked up in the access map, then these flags determine which kind of lookups should be performed.
       1. full_address: use the full address as key.
       2. detail_plus: look up also "user++@subdomain".
       3. detail_star: look up also "user+*@subdomain".
       4. star: look up also "user*@subdomain".
       5. domain: look up domain part.
       6. dotsubdomain: iterate through subdomains.
       7. dot: look up also ".".
       The default is to perform all lookups.
    9. source : This section can be used to define some features for an SMTP client session.
       1. ips : list of IP addresses to which the client should bind(2) when delivering mail. Note: if an IP address is specified which causes a bind(2) error, a warning will be logged but mail delivery continues without binding to a specific local IP address.
          Example:
          source net10 { ips = { 10.2.3.4, 10.5.9.122 } }
       A source section can be selected via the configuration map for QMGR (Section 3.8.1) using the following tags and arguments:
       1. tag smtpc_conf_cltaddr: argument: IP address of client from which the mail has been submitted.
       2. tag smtpc_conf_mail: argument: mail (envelope) address of the submitted mail. Only a subset of the lookups specified in Section 3.12.1 is performed: full address, domain, and (dot-)subdomains.
       The RHS in the map must be of the form
       source = name;
       where name is the name of a source section in the configuration file.
17. subsection smtps:
    1. connection_rate_max : maximum incoming connection rate from a single host (unit: connections/60s).
    2. connections_max : maximum number of open incoming connection from a single host (unit: entries).
18. subsection VERP: If VERP is turned on then the original MAIL address is modified for an outgoing transaction to make tracking simpler. The replacement is as follows: if MAIL is <lm@mail> and RCPT is <lr@rcpt> then the new sender address is <lm+lr=rcpt@mail>.
    1. when : This option has two possible values: always and never. If neither of these is set, then VERP is done on demand as explained in Section 3.14.
    2. delimiter1 : This delimiter is used to separate the local part of the original MAIL address from the (modified) RCPT address that is added (default: '+').
    3. delimiter2 : This delimiter is used to replace the '@' sign in the RCPT address before it is added to the new sender address (default: '=').
19. wait_for_client : maximum amount of time to wait for a client to become available (unit: s)
20. wait_for_server : maximum amount of time to wait for a server to become available (unit: s)

3.8.1  Configuration Map for QMGR

1. oci: this key specifies the initial number of concurrent outgoing connection to an IP address.
2. ocm: this key specifies the maximum number of concurrent outgoing connection to an IP address.
3. ocr: this key specifies the maximum rate of outgoing connection to an IP address in connections per minute (requires compile time option OCC_RATE).
4. octo: specify the timeout for an entry in the outgoing connection cache.
5. icr:, icl: specify the maximum rate for incoming connections (per minute).
6. icm:, icc: specify the maximum number of concurrently open incoming sessions.
7. smtpc_conf_rcpt_domain: see Section 3.8, item 16f.
8. smtpc_session_conf: see Section 3.11.1.

oci:127.0.0.1      5
ocm:127.0.0.1     10
oci:10            10
ocm:10            50
oci:               1
ocm:               4
icr:10             5
icr:127.0.0.1    100
icm:127.0.0.1    120
icl:meta1.org.    10
smtpc_conf_rcpt_domain:example.com	connection_limits=low;
smtpc_conf_cltaddr:10.              source = net10;
smtpc_conf_mail:sender@example.com  source = netex;

1. -C n maximum number of concurrent connections to one IP address [default: 100]
2. -c n initial number of concurrent connections to one IP address [default: 10]
3. -O R=n maximum connection rate per 60s (SMTPS) [default: 100]
4. -O O=n maximum number of open connections (SMTPS) [default: 100]

3.9  Configuration for SMAR

3.9.1  Declaring Maps for SMAR

1. type : type of the map; currently one of hash (Berkeley DB hash), cdb (tinycdb), regex, sequence, socket, and passwd.
2. file : the filename of the db file (including the extension) (for type hash, cdb, regex).
3. mapname : name of the map used in the protocol (type socket only).
4. address : IPv4 address of inet socket. (type socket only).
5. path : the pathname of the Unix domain socket (for type socket).
6. port : port for inet socket (type socket only).
7. maps : list of map names to use in the map (type sequence only).

map localusers { type = hash; file = "/etc/meta1/localusr.db"; }
map otherusers { type = cdb; file = "/etc/meta1/otherusr.cdb"; }
map password { type = passwd; }
map seq1 { type = sequence; maps = { localusers, otherusers }; }
map seq2 { type = sequence; maps = { password, otherusers }; }

3.9.2  Configuration Options for SMAR

1. access_map : this is a subsection that specifies the access control map. See Section 3.9.3 for details.
   Note: only one of file (1a) and name (1b) must be specified.
   1. file : filename of access map (including extension) [default: access.db].
   2. name : name of access map . This can be used if a different map type should be used, in which case the map must be declared as explained in Section 3.9.1.
2. address_delimiter : list of delimiters (specified as string) for address extensions in local part, [default: "+"]. Note: if address_delimiter has more than one character, the first one that is found in the local part of an address is used as delimiter in map lookups (see Section 3.12). For example: if the following option is used in the configuration file:
   address_delimiter = "/_-";
   then for the address " < user/ext-list@dom.ain > ", the delimiter for map lookups is "/" and the address detail is "ext-list", while for the address " < user-ext_list@dom.ain > ", the delimiter for map lookups is "-" and the address detail is "ext_list".
3. aliases : this is a subsection that specifies the parameters for aliases.
   Note: only one of file (3a) and name (3b) must be specified.
   1. file : filename of aliases map (including extension) [default: aliases.db].
   2. name : name of aliases map . This can be used if a different map type should be used, in which case the map must be declared as explained in Section 3.9.1.
   3. flags :
      1. localpart : the aliases map contains only localparts of addresses and those are only looked up for local addresses.
      2. local_domains : the aliases map contains fully qualified addresses which are only looked up for local addresses. This can be used similar to virtual users in sendmail 8, e.g.,

         vuser1@virt1.tld:	user1
         vuser2@virt1.tld:	user2
         vuser3@virt2.tld:	user3
      3. all_domains : the aliases map contains fully qualified addresses which are looked up for all domains.
      4. implicitly_match_detail : the items are looked up according to the algorithm specified in Section 3.12.1. and additionally +detail is implicitly matched when the pattern is "user@hostname". That is, it overrides the default matching explained in case 1e in Section 3.12.1.
      5. replace_macros : replace macros in the RHS of the map entries by the appropriate value, see Section 3.12.3.
      6. preserve_domain : if the RHS of an entry is an unqualified address, do not append the local hostname to it but the domain of the original address, i.e., preserve the original domain.
4. DNS : this subsection contains DNS related options.
   1. nameservers : list of up to four IPv4 addresses⁸ of nameservers. Note: it is important that all of these nameservers work properly, as the method to exclude unresponsive nameservers is not very efficient.
   2. retries : maximum number of retries. A value of 0 means one query only, i.e., no retry.
   3. timeout : the default timeout for a single DNS query (unit: s). Notes:
      • the timeout for a DNS request is the product of the number of tries and the individual timeout, i.e., (retries + 1) * timeout.
      • this value is only the default timeout which can be overridden by an application. For example, QMGR dynamically increases the timeout for addresses which did not resolve in earlier tries.
   4. flags : The flag use_resolvconf causes the list of nameservers (see 4a) to be read from /etc/resolv.conf. This flag is set by default unless the nameservers option is used. Note: the list of nameservers is not updated when /etc/resolv.conf is changed, smar needs to be restarted to achieve that. If the option nameservers is not used and the flag use_resolvconf is cleared, then smar uses 127.0.0.1 as default.
      More flags can be found in Section 8.4.
   5. port : Specify the port on which the nameservers are listening. By default (or if set to 0), port 53 is used (domain).
   6. Use_DNSSEC : Use DNSSEC for DNS queries.
5. dnsbl : specify a DNS based blacklist⁹. This section can be specified multiple times¹⁰; it has the following required options:
   • domain : specify the domain to use for DNS lookups, e.g., dnsbl.tld.
   • tag : specify the tag to use for lookups in the access map (which must be enabled, see Section 3.10, 4b).
   The client IPv4 address A.B.C.D is looked up via DNS as D.C.B.A.domain querying for an A record. If an A record W.X.Y.Z is found, then it is looked up in the access map as tag:W.X.Y.Z. for temporary and permanent DNS lookup failures the entries that will be checked in the access map are tag:temp and tag:perm, respectively.
   Notes:
   • DNS lookups in blacklists can be disabled via entries in the access map using the tags cltaddr, certissuer, or certsubject with quick:ok or quick:relay as RHS, see Section 3.9.3,
   • Some DNS blacklists return multiple A records. For those the A records are checked (in the order returned by the DNS server) until an access map entry is found. This is an intermediate solution as it may cause random results if multiple access map entries for a DNS blacklist exist. However, as long as all of them have the same return code type (i.e., temporary or permanent), this behaviour is sufficient.
   • currently a colon is added as delimiter after tag, this may be removed in later versions to allow for more flexibility; e.g., the configuration option itself can include a delimiter.
   The access map entry should have one of the usual rejection RHSs as explained in 3.9.3. Example: configuration file:

   smar { dnsbl { domain = dnsbl.tld; tag = dnsbltld; } }
   
   

   access map:

   dnsbltld:127.0.0.1  error:550 5.7.1 listed at dnsbl.tld as open relay
   dnsbltld:127.0.0.2  error:550 5.7.1 listed at dnsbl.tld as spam source
   dnsbltld:127.0.0.9  error:451 4.7.1 listed at dnsbl.tld as suspicious
   dnsbltld:temp       error:451 4.7.1 temporary lookup failure at dnsbl.tld
   
   

   If multiple DNS based blacklists are specified, the DNS queries are made concurrently but the lookups in the access map are performed in the order in which the blacklists are given; the first successful lookup is used as result, no further priorization is performed.
6. greylisting : specify greylisting options, see Section 3.9.4 for details.
   1. grey_wait : how long before greylisted can be confirmed.
   2. grey_expire : timeout for greylisted entries (did not confirm within that time).
   3. white_expire : expire whitelisted entries after this time if necessary.
   4. white_timeout : force whitelisted entries to reconfirm after this time.
   5. main_DB_name : name of main database (including .db extension).
   6. secondary_DB_name : name of secondary database (including .db extension).
   7. expire_limit : try to expire entries when this limit is reached.
   8. netmask : by default the entire IPv4 address is used as a key, however, by specifying a netmask, e.g., 0xFFFFFF00, the least significant bits can be cut off. This can be used to deal with server farms, see Section 3.9.4, e.g., if those are in the same class C subnet.
7. local_user_map : this is a subsection that specifies a map of valid local addresses.
   1. name : Name of the map of valid local addresses; the map must have been declared as explained in Section 3.9.1.
   2. flags :
      1. implicitly_match_detail : +detail is implicitly matched when the pattern is "user@hostname". That is, it overrides the default matching explained in case 1e in Section 3.12.1.
8. log_level : logging level.
9. mailertable : this is a subsection that specifies a mailertable, currently you can specify exactly one of the following two options:
   1. file : filename of mailertable [default: mt]. In this case a plain text file is read during startup and placed in an internal hash table. Note: it is strongly suggested to use lower case keys in this case, see Section 6.5, item 2.
   2. name : name of a mailertable map that has been declared before (see Section 3.9.1).
   3. flags : these flags can be used to select a subset of the matching described in Section 3.12.1.
      1. full_address: use the full address as key.
      2. detail_plus: look up also "user++@subdomain".
      3. detail_star: look up also "user+*@subdomain".
      4. star: look up also "user*@subdomain".
      5. domain: look up domain part.
      6. dotsubdomain: iterate through subdomains.
      7. dot: look up also ".".
      The default is domain, dotsubdomain, dot.
   The format of entries in the map is explained in Section 3.9.3. Note: reloading mailertable (Section 4.8) while SMAR is running can be done only if it is declared as Berkeley DB (case 9b with the proper map)

3.9.3  Configuration Maps for SMAR

Access Map

Mailertable

• either a specification following the same syntax as the configuration file (in this case the specification must be enclosed by curly braces),
• or it uses a syntax specific to mailertable consisting of an optional port number, an optional (esmtp) protocol and a hostname or a list of IP addreses (in square brackets) which are separated by spaces.

Aliases

• the local part of a valid (local) e-mail address,
• or a complete local e-mail address,
• or any e-mail address,

3.9.4  Greylisting

1. simple greylisting: only uses the client IP address as key. [Posa].
2. full greylisting: uses a tuple consisting of client IP address, envelope sender, and envelope recipient as key.

Greylisting: Whitelisting

Possible Problems with Greylisting

3.10  Configuration for SMTP Server

1. auth : this is a subsection that specifies the parameters for AUTH support. It is only available if the system has been configured with the option --enable-SASL, see Section 2.2.1.
   1. flags : flags for SMTP AUTH
      See the Cyrus SASL documentation for the meaning of these flags: noplaintext, noactive, nodictionary, forward_secrecy, noanonymous, pass_credentials, mutual_auth.
   2. trusted_mechanisms : list of SASL mechanisms for which relaying is allowed if a client successfully authenticated using one of those
   3. user_realm : the following description is taken from the Cyrus-SASL documentation for the sasl_server_new() call: The realm the connected client is in. The Kerberos mechanisms ignore this parameter and default to the local Kerberos realm. A value of NULL (here: if not set) makes the library default, usually to the serverFQDN; a value of "" specifies that the client should specify the realm; this also changes the semantics of @ in a username for mechanisms that don't support realms.
   Note: the name for the Cyrus-SASL configuration file is currently meta1.conf. That file can be used to adjust the list of mechanisms (option mech_list) that should be advertised (besides many other things), hence this option is not in the SMTP server itself.
2. CDB_gid : (numeric) group id for CDB files, i.e., the group id of meta1c, see Section 2.4.1.
3. DKIM_signing : this is a subsection that specifies the parameters for DKIM signing support. It is only available if the system has been configured with the option --enable-DKIM, see Section 2.2.1. For details about DKIM see RFC 4871 [ACD⁺07].
   1. sign_if : always: default, trusted: only create a DKIM signature if the client authenticated via AUTH or STARTTLS (certificate) and is allowed to relay.
   2. rcpt_domains : a list of domains for which a DKIM signature is generated if the domain matches that of a RCPT in a transaction. By default, all mails are DKIM signed. See dkim_rcpt_domains about the matching algorithm.
   3. signature_method : signature method: rsa-sha256 (default) or rsa-sha1.
   4. body_canonicalization : canonicalization algorithm for mail body: simple (default) or relaxed.
   5. header_canonicalization : canonicalization algorithm for mail header: simple (default) or relaxed.
   6. ignore_errors : if set, the server will ignore errors that occur during signing and accept the mail nevertheless. By default, any error is returned to the SMTP client as corresponding reply code.
   7. sign_header : specifies a list of header names which will be signed by DKIM. See below for a description of the algorithm.
   8. skip_header : specifies a list of header names which will not be signed by DKIM. The match is done via a prefix comparision against the header name plus a trailing colon, which allows to also perform a full match. For example, skip_header = { "X-", "Received:" }; will skip all headers that start with X-, and all Received headers.
      The decision whether or not to sign a header is made as follows (any decision is final, i.e., it is not overridden by subsequent steps):
      1. if a header is listed in skip_header it will not be signed.
      2. if sign_header is empty, the header will be signed.
      3. if sign_header is not empty, the header will be signed if it is in the list.
      4. in all other cases the header will not be signed.
   9. over_sign_headers : specifies a list of header names which will be over-signed by DKIM, i.e., each specified header name will be listed in the header list (h=) one more time than it is specified in the header of the mail itself, thus preventing an attacker to add another header of the same name (without breaking the DKIM signature).
   10. A subsection called sign must be specified at least once:
       1. keyfile : name of file containing the private (RSA) key (required).
       2. domain : the domain of the signing entity (required). This is the domain that will be queried for the public key by a DKIM verification program and is places in the DKIM-Signature header as d=.
       3. selector : selector name (required).
       4. from : specifies (part of) an address that must match the From: address in the mail. This option is required in all but one entry, obviously different entries must use different from values. An entry without this option is the default entry that will be used for signing if none of the from values matches. The From: address is checked against the specified from options based on the algorithm described in Section 3.12.1, however, no +detail handling is (currently) performed. The flags full_address and dotsubdomain, are set for this map, thus influencing the lookups that are performed. Moreover, domain lookups are done without leading @.
       Example: sign messages that have a sender address of sender@example.net with the domain example.net and selector net, messages which have a sender domain of example.org with the domain example.org and selector org, all others are signed with the domain example.com and selector default:

        DKIM_signing {
          sign {
           domain=example.com; selector=default; keyfile=com.key; }
          sign {
           from=sender@example.net;
           domain=example.net; selector=net; keyfile=net.key; }
          sign {
           from=example.org;
           domain=example.org; selector=org; keyfile=org.key; }
         }
       
       
   Notes:
   • DKIM signing is done unconditionally if this section is specified and sign_if is not set to something else than the default value of always. Hence you must not use this kind of setup on a publically accessible SMTP server. Either set sign_if to trusted, or define a separate SMTP submission server (see Section 3.10.2) and restrict access to authenticated users or to some trusted IP range.
   • If a pmilter changes the mail body or a header that has been signed, then the DKIM signature becomes invalid. Currently no attempt is made to deal with this situation.
4. flags :
   1. 8bitmime : offer 8BITMIME: MeTA1 is 8 bit transparent, but it does not perform any conversion, so this option should only be used if all communication partners can deal with 8 bit data.
   2. access : use access map (in SMAR). Note: currently this flag is required to perform a reverse lookup for a client IP address to get the hostname of the client which then can be used for logging and the Received: header.
   3. allow_data_before_greeting : allow a client to send data before the initial 220 greeting.
   4. allow_space_after_colon_for_MAIL_and_RCPT : Unfortunately some people are not able to read RFCs but try to implement mail programs nevertheless. To deal with one of their errors, this option has been created. It allows a space after the colon in the MAIL and RCPT commands, e.g.,

      MAIL FROM: <banktransfers@cashedge.com>
      
      
   5. delay_checks : delay acceptance check until RCPT stage (unless explicitly overridden, see Section 3.9.3).
   6. delay_greylisting_error_until_DATA : if greylisting (4g) is enabled then wait until the DATA command to return an error; see Section 3.9.4 for details.
   7. greylisting : enable simple greylisting; this also requires the access map (see 3.9.3) and must be enabled in SMAR, see Section 3.9.2 item 6), see Section 3.9.4 for details.
   8. fullgreylisting : enable full greylisting (which must also be enabled in SMAR, see Section 3.9.2 item 6), see Section 3.9.4 for details.
   9. rcpt_conf : request SMAR lookup of RCPT address in the access map using the tag smtps_rcpt_conf.
      Currently the RHS for this kind of entry is a flags option and the only possible value is greylisting, which allows to turn on greylisting per RCPT, e.g.,

      smtps_rcpt_conf:some@local.domain

      flags = greylisting;

      Note: this will change in a subsequent version (syntax and features) as soon as some basic concept has been determined.
   10. lmtp_does_not_imply_relaying : even if a domain in the mailertable has lmtp: as RHS do not implicitly allow relaying to it, i.e., do not consider the domain as "local" with respect to relaying. This is useful for an MSA to avoid external mail to local domains without authentication.
   11. lookup_session_conf : Look up session configuration data (see Section 3.10.1) in the access map (which must be activated, see 4b).
   12. require_EHLO_before_MAIL : require EHLO (or HELO) before a MAIL command.
   13. soft_bounce : change permanent (5xy) SMTP error replies into temporary (4xy) errors. This is a useful feature for testing to avoid bounces due to misconfigurations.
   14. strict_EHLO_checks : perform a strict syntax check on the argument for EHLO (or HELO).
   15. smtps : enable smtps submission service, i.e., implicit TLS handshake, as described in RFC 8314.
   16. xverp : offer XVERP extension to turn on VERP [Ber97] support for a transaction. This is a parameter for the MAIL command, e.g.
       MAIL From:<sender@some.domain> XVERP
   17. prdr : PRDR is an SMTP extension [Hal07] to return individual RCPT status after the end of data (similar to LMTP). This feature is turned on if a policy milter is configured (see item 19).
5. greeting : initial ESMTP greeting text. Unless the greeting string starts with the text "220" and ends with CRLF (rn), it will be appended to the greeting code 220, and the host name (separated by a space each). Otherwise, the entire string will be used verbatim. To specify a multiline greeting, use something like:

   greeting = "220-host.name Welcome to my fancy ESMTP server\r\n"
      "220-Sending UBE is forbidden.\r\n220 Violators will be prosecuted.\r\n";
   
   

   The default greeting text consists of the code 220, the host name, the word "ESMTP" and the MeTA1 version (separated by spaces). Note: RFC 2821 requires that the greeting has the form

   220 FULLY.QUALIFIED.HOST.NAME optionally more text
   
   

   that is, the first word after the 220 code must be the host name, hence these two words are usually prepended to the specified greeting text.
6. id : unique identifier for SMTP server (0); see Section 3.10.2.
7. IO_timeout : timeout for SMTP operations.
8. threads_max : maximum number of threads.
9. bad_commands_per_session_max : maximum number of bad, i.e., unknown, SMTP commands per session accepted by server. After this limit is reached the connection is terminated with an 421 error.
10. invalid_addresses_per_session_max maximum number of invalid, e.g., unknown, RCPT addresses per session accepted by server. After this limit is reached the connection is terminated with an 421 error.
11. nop_commands_between_transactions_max : maximum number of NOOP, RSET, and related SMTP commands between two successful transactions accepted by server. After this limit is reached the connection is terminated with an 421 error.
12. bad_commands_per_transaction_max : maximum number of bad, i.e., unknown, SMTP commands per transaction accepted by server. After this limit is reached the connection is terminated with an 421 error.
13. nop_commands_in_transaction_max : maximum number of NOOP and related SMTP commands in a single transaction accepted by server. After this limit is reached the connection is terminated with an 421 error.
14. invalid_addresses_per_transaction_max maximum number of invalid, e.g., unknown, RCPT addresses per transaction accepted by server. After this limit is reached the connection is terminated with an 421 error.
15. recipients_per_session_max : maximum number of recipients per session.
16. recipients_per_transaction_max : maximum number of recipients per transaction.
17. hops_max : maximum number of hops (Received: headers). If this value is exceeded the incoming mail is rejected because it is considered a possible mail loop.
18. message_size_max : maximum message size (unit: KB).
19. policy_milter : this is a subsection that specifies the parameters for pmilter support (see Section 5). It is only available if it has been enabled during configure (--enable-pmilter, see Section 2.2.1).
    1. socket : this is a subsection that specifies the socket to communicate with policy milter. The type (option type) of the socket must be either inet or unix.
       1. type = inet
          1. port : port number for connection.
          2. address : IP address for connection.
       2. type = unix
          1. path : pathname of Unix Domain socket.
    2. timeout : maximum amount of time to wait for a reply from a policy milter.
    3. flags: policy milter flags. If the connection to pmilter fails then SMTPS will ignore pmilter by default. This behaviour can be changed by setting one of following two flags:
       1. abort : if the connection to pmilter fails then abort the current session with a 421 error.
       2. accept_but_reconnect : if the connection to pmilter fails then continue the current session but try to reconnect for the next session.
20. proxy : this subsection uses a generic socket type specification (see section 3.7, item 2) to define which proxy is allowed to connect to this server - if any (requires the compile time option SS_PROXY). client_key : If the proxy smtpp is used this defines a shared key which must also be passed as option to smtpp to perform a very basic authentication of requests from smtpp to smtps.
21. processes : number of processes to start.
22. protected_recipients : this is a subsection which provides a few simple options to protect recipients by restricting who can send mail to them.
    1. allow_by : this is a required subsection which has two possible flags (at least one must be specified).
       1. sender : allow sending mail based on the envelope sender (MAIL) address. Even though this address can be forged it provides some basic protection.
       2. client_ip : allow sending mail based on the client IP address. Note: if this option is used and backup MX servers are configured then the IP addresses of those servers must be allowed too.
    2. match_type : this specifies what type of matching should be done. By default, exact matches are required. Alternatively, one of the following two options can be selected:
       1. generic_lookup : the items are looked up according to the algorithm specified in Section 3.12.1.
       2. implicitly_match_detail : the items are looked up according to the algorithm specified in Section 3.12.1. and additionally +detail is implicitly matched when the pattern is "user@hostname". That is, it overrides the default matching explained in case 1e in Section 3.12.1.
    See Section 3.10.3 for details.
23. transactions_max : maximum number of transactions per session.
24. tls : this is a subsection that specifies the parameters for STARTTLS support. It is only available if the system has been configured with the option --enable-TLS, see Section 2.2.1. See Section 11.1 for some background information about these options. Note: this description lists all options, but not all of them are available for the SMTP server and client.
    1. cache_size : size of TLS session session cache (0: disable cache) (see Section 11.3).
    2. cache_timeout : timeout for entries in TLS session session cache (only smtpc).
    3. cert_file : file with certificate in PEM format.
    4. key_file : file with private key for certificate in PEM format.
    5. CAcert_file : file with CA certificate in PEM format.
    6. CAlist_file : file with CA certificates in PEM format (for SSL_CTX_set_client_CA_list(3); only smtps unless TLSv1.3 is used and the TLS library supports SSL_CTX_set0_CA_list(3)). Notes: if CAlist_file is not set, then CAcert_file will be used, if CAlist_file is set to "", then NULL will be passed to (for SSL_CTX_set_client_CA_list(3)), otherwise the specified value will be used.
    7. CAcert_directory : directory with (symbolic links for) CA certificates in PEM format.
    8. options : TLS related options, see SSL_CTX_set_options(3) and SSL_set_options(3).
    9. CipherList : specify list of ciphers to use, see SSL_CTX_set_cipher_list(3) and SSL_set_cipher_list(3). Note: this only works for protocol versions before TLSv1.3. The format of the string (list) is explained in ciphers(1).
    10. CipherSuites : specify list of ciphers to use, see SSL_CTX_set_ciphersuites(3) and SSL_set_ciphersuites(3). Note: this only works for protocol version TLSv1.3.
    11. CRL_file : Name of file that contains certificate revocation status information.
    12. CRL_directory : Name of directory that contains certificate revocation status information.
    13. Digest : specify the digest to use to calculate the fingerprint of a cert. Default: sha1. This affects logging but more importantly the possible restriction of STARTTLS connections, see section 3.13, item 1. See dgst(1) for a list.
    14. DHParam : specify DH parameters for the server. This is a section which provides one of the follow options:
        1. bits to specify the size of the DH parameters to be generated which must be one of 2048, 1024, or 512, or
        2. file to specify a file containing the DH parameters to use.
    15. flags : some flags are available to influence the behaviour of the SMTP server with respect to STARTTLS.
        1. allow_relaying_if_verified : if the client presented a certificate that can be verified by the CA certificates that are available to the server (see above: CAcert_file and CAcert_directory), then relaying is allowed for the SMTP session.
        2. check_access_map_for_relaying : if this flag is set then the access map (which must be activated, see 4b) is checked to see whether relaying should be allowed for a client which presented a certificate that has been verified (see above). For this purpose, the DN of the cert issuer is looked up in the access map using the tag certissuer:. If the resulting value is relay, relaying is allowed. If it is cont, the DN of the cert subject is looked up next in the access map using the tag certsubject:. If the value is relay, relaying is allowed; every other value is currently ignored.
           To avoid problems with the DN names in map lookups, they are modified as follows: each non-printable character and the characters '<', '>', '(', ')', '"', '+', ' ' are replaced by their hexadecimal ASCII value with a leading '+'. For example:
           /C=US/ST=California/O=endmail.org/OU=private/CN=
           Darth Mail (Cert)/emailAddress=darth+cert@endmail.org
           is encoded as:
           /C=US/ST=California/O=endmail.org/OU=private/CN=
           Darth+20Mail+20+28Cert+29/emailAddress=darth+2Bcert@endmail.org
           /Examples:
           To allow relaying for everyone who can present a cert signed by
           /C=US/ST=California/O=endmail.org/OU=private/CN=
           Darth+20Mail+20+28Cert+29/emailAddress=darth+2Bcert@endmail.org
           simply use:

           certissuer:/C=US/ST=California/O=endmail.org/OU=private/CN=
           Darth+20Mail+20+28Cert+29/emailAddress=darth+2Bcert@endmail.org	relay

           To allow relaying only for a subset of machines that have a cert signed by
           /C=US/ST=California/O=endmail.org/OU=private/CN=
           Darth+20Mail+20+28Cert+29/emailAddress=darth+2Bcert@endmail.org
           use:

           certissuer:/C=US/ST=California/O=endmail.org/OU=private/CN=
           Darth+20Mail+20+28Cert+29/emailAddress=darth+2Bcert@endmail.org	cont
           CertSubject:/C=US/ST=California/O=endmail.org/OU=private/CN=
           DeathStar/emailAddress=deathstar@endmail.org	relay

           Notes:
           • if a CN contains a bogus value (e.g., an embedded NUL), then it will be represented by a textual error description instead:

             BadCert:TooLong	CN is too long
             BadCert:ContainsNUL	CN contains an embedded NUL
             BadCert:Unknown	other, unspecified error while extracting CN
           • if a DN contain an unprintable character, then it will be replaced by a backslash, an 'x', and the hexadecimal value (two digits), e.g., an embedded NUL is shown as \x00.
           • line breaks have been inserted after CN= for readability, each tagged entry must be one (long) line in the access map.
        3. request_cert : request a (client) cert. This flag is set by default and can be turned off via the usual negation methods, (see section 8.1.1) e.g., dont_request_cert. This can be useful for broken clients that fail the TLS handshake if a cert is requested.
        4. use_chain : Use SSL_CTX_use_certificate_chain_file(3) to load a certificate chain instead of just SSL_CTX_use_certificate_file(3).
    16. violation : This option decides how to (globally) handle TLS requirement violations (see Section 3.10.1). Possible values are: permfail: generate permanent failure, tempfail: generate temporary failure, abort: abort session. These options take effect for session/recipient restrictions when a MAIL/RCPT command is (about to be) issued by the client, respectively.
    17. verify_depth : specify the limit up to which depth certificates in a chain are used during the verification procedure. If the certificate chain is longer than allowed, the certificates above the limit are ignored, see SSL_CTX_set_verify_depth(3)).
25. session_features : This section can be used to define classes of features for an SMTP server session which then can be referenced via the access map.
    There are currently two options allowed:
    • flags Available flags are a subset of those listed in item 4: starttls, auth, delay_checks, allow_data_before_greeting, allow_space_after_colon_for_MAIL_and_RCPT, require_EHLO_before_MAIL, strict_EHLO_checks, check_EHLO.
    • tls this subsection can specify some parameters for STARTTLS support (see 24 for details). Valid options are: cert_file, key_file, CAlist_file, flags, options (note: this only sets additional options, see SSL_set_options(3)), and CipherList, as well as the flags section.
    Example: to turn off STARTTLS for some clients, declare a notls class in the configuration file:

    session_features  notls { flags = { -starttls }}
    
    

    and reference it in the access map for those clients:

    smtps_session_conf:217.126.135.148	session_feature=notls;
    
    

3.10.1  SMTP Server Session Configuration

3.10.2  Multiple SMTP Servers with different Configurations

smtps MTA {
  id = 0;
  listen_socket { type=inet; port = 25; }
  start_action = pass; pass_fd_socket = smtps/mtafd;
  user = meta1s;
  path = /usr/libexec/smtps;
  arguments = "smtps -N MTA -f /etc/meta1/meta1.conf";
  log { facility = mail; ident=meta1-MTA; }
}

smtps MSA {
  id = 1;
  DKIM_signing { domain=example.net; selector=test;
    keyfile=DKIM.private.key; }
  listen_socket { type=inet; port = 587; address=127.0.0.1; }
  start_action = pass; pass_fd_socket = smtps/msafd;
  user = meta1s;
  path = /usr/libexec/smtps;
  arguments = "smtps -N MSA -f /etc/meta1/meta1.conf";
  log { facility = mail; ident=meta1-MSA; }
  auth { trusted_mechanisms = "CRAM-MD5 DIGEST-MD5";
         flags = { noplaintext }; } }

smtps IPv6 { id = 0;
  listen_socket { type=inet6; port = 25; }
  start_action = pass; pass_fd_socket = smtps/ipv6;
  user = meta1s;
  path = /usr/libexec/smtps;
  arguments = "smtps -N IPv6 -f /etc/meta1/meta1.conf";
}

smtps IPv4 { id = 1;
  listen_socket { type=inet; port = 25; }
  start_action = pass; pass_fd_socket = smtps/ipv4;
  user = meta1s;
  path = /usr/libexec/smtps;
  arguments = "smtps -N IPv4 -f /etc/meta1/meta1.conf";

3.10.3  Protecting Recipients

3.11  Configuration for SMTP Client

1. IO_timeout : timeout for SMTP operations (unit: s).
2. LMTP_socket : Unix domain socket to use for LMTP [default: lmtpsock].
3. log_level : logging level.
4. tls : this is a subsection that specifies the parameters for STARTTLS support. It is only available if the system has been configured with the option --enable-TLS, see Section 2.2.1. See Section 11.1 for some background information about these options. The options are basically the same as for the SMTP server (see section 3.10, item 24).
5. session_features : This section can be used to define classes of features for an SMTP client session. This is only available if the system has been configured with the option --enable-TLS and also requires the compile time option SC_SESS_FEATS.
   1. flags :
      • starttls can be used to turn off (see Section 8.1.1) the use of STARTTLS for servers with a broken implementation.
      For other flags see Section 8.6, item 3.
   2. tls : this is a subsection that can be used to set some STARTTLS related options, which are a subset of those available globally (see Section 3.10, item 24): cert_file, key_file, flags, options, CipherList, and CipherSuites.
   Session features can be selected via the configuration map for QMGR (Section 3.8.1) using the following tags and arguments:
   1. tag smtpc_session_conf, argument: IP address of server to which smtpc connects.
6. wait_for_server : maximum amount of time to wait for a server (QMGR) to become available (unit: s).
7. proxy : this subsection uses a generic socket type specification (see section 3.7, item 2) to define the proxy to use - if any (requires the compile time option SC_PROXY). proxy_key : If the proxy smtpp is used this defines a shared key which must also be passed as option to smtpp to perform a very basic authentication of requests from smtpc to smtpp.
8. dkim_rcpt_domains : this can consist of a list of domains for which a DKIM signature is added if it has been generated in smtps and the domain of a RCPT in a transaction matches one of the entries. If the list is not set then no restrictions apply. Otherwise each domain is compared against the RCPT address from its end. To avoid substring matches, it is suggested to anchor a domain with a leading dot (matching also subdomains) or @ (matching only the full domain). An available DKIM signature header is added to a transaction if any of its RCPT domains matches.

3.11.1  SMTP Client Session/Recipient Configuration

3.12  Lookup Orders

3.12.1  Lookup Orders in Maps

1. Repeat the following lookups for each subdomain of domain (as explained above):
   1. "user+detail@subdomain" if "+detail" exists; this is a verbatim match. Flag: full_address.
   2. "user++@subdomain" if "+detail" exists and "detail" is not empty; this matches any non-empty "+detail". Note: the second "+" character is a fixed metacharacter, it does not depend on address_delimiter; it is a modelled after the "+" operator in regular expressions etc to denote a non-empty sequence of items. Flag: detail_plus
   3. "user+*@subdomain" if "+detail" exists; this matches any "+detail" (including just "+"). Flag: detail_star
   4. "user*@subdomain"; this matches "user@subdomain" as well as "user+detail@subdomain" ("detail" can be empty). Note: "*" is not a generic metacharacter here, it matches only a token beginning with address_delimiter or an empty sequence, it does not match any other character sequence. For example: the input "user1@subdomain" does not match the LHS "user*@subdomain". Flag: star
   5. "user@subdomain"; this does not match if "+detail" exists, unless the flag implicitly_match_detail is selected for the map to implicitly match a detail even if there is no wildcard in the pattern.
   6. "@subdomain".
2. If nothing has been found and the map type requests it, then try localpart only (with the same meaning as above):
   1. "user+detail" if detail exists
   2. "user++" if detail exists and is not empty,
   3. "user+*" if detail exists,
   4. "user*",
   5. "user"

3.12.2  Lookup Orders for Anti-Spam Measures

Connect

1. start PTR lookup for client IP address,
2. check: look up client IP address using tag cltaddr: (as explained in 3.12.1)
3. map client IP address to client hostname returning the tuple (clientresolve, clientname).
4. check: look up cltresolve:clientresolve
5. check: look up cltname:clientname (as explained in 3.12.1)
6. start DNS blacklist queries,
7. check: look up results of DNS blacklists in access map.

MAIL

1. check: is the address routeable? That is, if the sender address would be used as a recipient address (as it would be necessary if a DSN must be sent) is it possible to find a host that will deal with the address? This means that the domain part must have a valid MX or A record or that routing is specified via mailertable.
2. check: if the domain of sender address is local: is the local part valid?
3. check: look up the address in the access map (provided it is enabled) with the tag from:.
4. check: look up the IP addresses that were found when trying to determine whether the address is routeable with the tag mxbadip: in the access map.

RCPT

1. is this a relaying attempt and if so, is it authorized? Relaying can be allowed for the entire session, e.g., due to the client IP address or other authorization based on some authentication (STARTTLS, AUTH).
2. are there any other restrictions for the recipient address?

1. check: is the recipient local and does the address exist? If yes, it is not a relaying attempt and hence allowed.
2. check: look up the recipient address with the tag to: (provided the access map is enabled) (provided the access map is enabled) and check whether the RHS is relay, otherwise reject the RCPT command as unauthorized relaying attempt unless the RHS is an error entry which is then used as reply.

1. look up address with tag protectedrcpt:, if found perform all the necessary checks as explained in Section 3.10.3.
2. check: look up the address using the tag to: if all of the following three conditions are met:
   1. the access map is enabled.
   2. a session check did not result in quick:relay.
   3. a session check did not result in quick:ok and relaying is allowed by other means.
3. check: perform greylisting unless the session is marked as ok or relay or the RCPT lookup returned quick:ok or quick:relay.

3.12.3  Macro Replacements in RHS

alias*@.domain     user${extension}@${subdomain}.domain

alias@host.domain             user@host.domain
alias+detail@host2.domain     user+detail@host2.domain

3.13  STARTTLS Restrictions

1. cert_fps A list of fingerprints, one of which must match the fingerprint of the presented TLS certificate. By default, SHA1 is used to calculate the fingerprint, but this can be changed via the Digest option (see section 3.10, item 24m).
2. cert_issuer require that the DN (Distinguised Name) of the issuer of the presented TLS certificate matches the specified value.
3. cert_subject require that the CS (CERT subject) of the presented TLS certificate matches the specified value.
4. cipher_bits_min require that the effective keylength (in bits) of the symmetric encryption algorithm used for a TLS connection is at least as big as the specified value.
5. common_name: require that the CN (Common Name) of the presented TLS certificate matches the specified value.
6. flags: available flags are currently:
   1. verified: the TLS connection must be verified, i.e., the cert issuer must be listed in CAcert_file or CAcert_directory (see Section 3.10, item 24).
   2. encrypted: the TLS connection must be encrypted, i.e., the effective keylength (in bits) of the symmetric encryption algorithm used for a TLS connection is greater than zero.
7. hostnames A list of hostnames, one of which must match a DNS value in subjectAltNames or the CN of the presented TLS certificate. This list can contain FQHN, or a domain name with a leading dot. A DNS name in subjectAltName can contain a leading wildcard * which matches exactly one level in the FQHN. The rules for matching are (first name refers to an entry in hostnames, the second name refers to an entry in the cert):
   1. exact match.
   2. host.tld matches *.host.tld. Note: *.tld in a cert is not accepted.
   3. .host.tld matches anything.host.tld where anything can be "*" or one or more subdomains.
   Note: This restriction is only useful in conjunction with the verified flag.
8. root_ca_subjects A list of CNs, one of which must match the CN of the root CA cert that signed the presented TLS certificate. This feature is useful to restrict the list of CA that should be accepted for a server as the list of CAs is currently only global and hence applies to all TLS connections. Otherwise a compromised CA could be abused to create a bogus intermediate cert that is used to sign a cert that is required by other restrictions, e.g., common_name, cert_subject, or cert_issuer, and thus circumvent the security of a connection.
9. violation See Section 3.10, item 24p, for possible values.

smtpc_rcpt_conf:@meta1.org	tls_requirements { cert_issuer="/C=US/ST=Berkeley/L=Endmail+20Org/O=MTA/CN=Claus+20Assmann+20CA+20RSA+202007/emailAddress=ca+ca-rsa2007@esmtp.org"; }
smtpc_rcpt_conf:@example.org	tls_requirements { flags={verified}; hostnames={ server.example.org, server.example.net }}

3.14  VERP

1. Turning it always on in QMGR (see Section 3.8, item 18). Note: this option overrides the next two.
2. Via the XVERP extension in the SMTP server (see Section 3.10, item 4p).
3. Via an entry in aliases marking a list with verp-:

   otherlist: <user5@my.dom> <user6@other.dom> <user7@local.host>

   verp-otherlist: something

Chapter 4
Running MeTA1

4.1  Starting MeTA1

# ./mcp.sh start

# ./mcp.sh stop

1. fatal (e.g., EX_USAGE): the service will not be restarted.
2. hard (e.g., EX_UNAVAILABLE): the service will be restarted, unless a hard restart limit is exceeded within a certain time.
3. soft (e.g., EX_TEMPFAIL): the service will be restarted. unless a soft restart limit is exceeded within a certain time.
4. ok: the service will be restarted, unless a restart rate is exceeded.

4.2  Using MeTA1 only for Outgoing Mail

LOCAL_RULE_0
R$* + X<@$*>    $#meta1 $@ localhost $: $1 <@$2>

LOCAL_RULESETS
SHdrToSMTP
R$+                     $: $>PseudoToReal $1            sender/recipient common
R$+                     $: $>MasqSMTP $1                qualify unqual'ed names
R$* + X<@$*>            $: $1 < @ $2 >
R$* < @ *LOCAL* > $*    $: $1 < @ $j . > $2

MAILER_DEFINITIONS
Mmeta1,   P=[IPC], F=kmDFMuXa, S=EnvFromSMTP/HdrFromSMTP, R=EnvToSMTP/HdrToSMTP,
        E=\r\n, L=990, T=DNS/RFC822/SMTP,
        A=TCP $h 2009

4.3  Using MeTA1 for Incoming Mail

4.3.1  Local Delivery and Specifying Local Domains

4.3.2  Specifying Valid Local Addresses

4.4  Using MeTA1 as Gateway

4.5  Using MeTA1 as Backup MX Server

4.5.1  Note about Backup MX Servers

4.6  Using MeTA1 with a Proxy

ssh -tt -o ExitOnForwardFailure=yes -R :25:localhost:25 root@STATIC.HOST \
runas meta1p PATH/TO/libexec/smtpp -f -l :2525

smtpc {
  proxy { type=inet; port=2525; address=IP.OF.STATIC.HOST; }
}

• access to the proxy should be protected by a firewall.
• all SMTP connections on the host with the dynamic address to MeTA1 are coming from localhost, hence restrictions and authorizations (e.g., allowing to relay!) cannot be based on the IP address nor name.

4.7  Miscellaneous Programs

4.7.1  Do not run programs as root User

# /usr/local/bin/runas meta1q mailq -V

4.7.2  Displaying Content of Mail Queues

4.7.3  Interacting with QMGR

4.8  Reloading Maps

# mv $MAP.db $MAP.old.db
# /usr/local/bin/runas meta1q createmap -F $MAP.db < $MAP
# kill -USR1 $PID

4.9  Logging

• logfiles must exist with the proper owner and permissions to be used. Neither MCP nor the modules will currently create logfiles. This is done by make install, i.e., misc/sm.setup.sh, which parses meta1.conf to extract the section titles/names and user entries to create the logfiles with the correct name and owner. This does not (yet) properly work if unique logfile names are created, see Section 8.2, 3.
• MCP uses facility LOG_DAEMON; this is currently not configurable. Hence log entries from MCP may end up in a different logfile, e.g., /var/log/messages (depending on syslog.conf).

4.9.1  Logfile Rotation

# cp qmgr.log qmgr.log.0

4.10  Regular Checks

1. Check the logfile for errors¹³:

   $ egrep 'sev=(ALERT|CRIT|ERR|FAIL|FATAL)|\<assertion\>' $LOGFILE
   
   
2. Keep track of the size of the processes, e.g,

   $ date >> $MTAPROCS
   $ ps axuww | grep '^meta1' | sort >> $MTAPROCS
   
   

   If one of the processes continuously grows then MeTA1 should be compiled with -DSM_HEAP_CHECK (see Section 12.1.5) and a heap dump should be taken regularly by sending the USR1 signal to the process. By comparing subsequent heap dumps it should be possible to locate a possible memory leak.

4.11  Dealing with Errors

4.11.1  Resource Problems

• memory shortage: the memory usage of MeTA1 can be controlled by restricting the size of various data structures, see Section 3.8, e.g., AQ_entries_max, IQDB, and OCC_entries_max. However, setting these values too low will result in a very slow MTA that may operate in a degraded state which is not acceptable.
• disk shortage: MeTA1 has options that let it decide how much free disk space is needed for operation, see Section 3.8: disk_space_ok and disk_space_min. However, if there is not enough space to store the envelope databases (DEFEDB and IBDB) then the system cannot work, hence sufficiently free disk space is essential for proper operation.

4.11.2  Database Problems

# ls -1 [0-9A-F]/S*

$ egrep "ss_ta=$TAID, (mail|rcpt)=" $LOG | \
  sed -e 's;^.*\(mail=<.*>\), .*;\1;' -e 's;^.*\(rcpt=<.*>\), .*;\1;'

4.11.3  Writing Core Dumps

4.12  Replacements for Features available in other MTAs

1. Address Masquerading: The best way to use the correct e-mail addresses is to properly configure your MUA. Some MUAs offer more flexibility for this than the default masquerading features of sendmail 8, e.g., mutt [mut] allows to select sender addresses based on recipient addresses.
   Alternatively a mail submission program (MSP) can be used which offers address rewriting capabilities, e.g., the MSP from sendmail 8.
2. .forward: procmail can be used as LDA (see Section 4.3.1) and its configuration file .procmailrc allows to implement the same functionality as a .forward from sendmail 8 and some other MTAs.
3. Sending mail to programs: see previous item 2: this can be done with the help of procmail.
4. Appending mails to files: see item 2: this can be done with the help of procmail.

Chapter 5
Policy Milter

5.1  Policy Milter Overview

Chapter 6
Miscellaneous

6.1  Troubleshooting

6.1.1  Startup Problems

1. invalid configuration file: use misc/smconf to check the syntax before deploying a new configuration file.
2. wrong permissions: check the permissions as explained in Section 2.4:

   $ ./misc/sm.check.sh
   
   
3. missing or invalid maps: make sure maps are created properly with createmap(8).

6.1.2  Logfile Entries

smtps: ... client_name=Hostname_Not_Determined

6.2  Caveats

• If the system runs out of memory then the MTA may not act gracefully in all cases, see Section 4.11.1.
• If a disk that is used for one of the queues becomes full, some errors may not be handled gracefully, see Section 4.11.1. To avoid this, MeTA1 has some limits for the amount of available disk space that is required to accept mail (see Section 3.8).

6.3  Checks in SMTP Server

6.3.1  Strict RFC Compliance

MAIL From:<user@some.domain>

5.5.0 Syntax error., input=MAIL FROM: <blafwhoyqjywvu@asia.com>

6.3.2  Various Checks

6.4  Security Checks

6.5  Restrictions

1. DNS lookups currently use only UDP by default, hence answers that exceed the UDP packet size will cause problems. However, such DNS packets are really rare (because they cause operational problems in various places, e.g., some firewalls may block TCP for port 53). A possible workaround might be to force TCP (see Section 8.4, item 1(a)i), the correct way is a change in the DNS library to retry with TCP, but this has not yet been implemented.
2. Map lookups convert keys to lower case before checking an entry. In general this is not a problem unless local addresses rely on preserving the case of the local parts of addresses. That is, local addresses which require upper case characters do not work.
3. Multi-line replies from an SMTP server are currently neither stored (for a possible DSN) nor logged, instead just the last line is used for that purpose.

6.6  Code Review, Enhancements, Patches

6.7  Porting

6.8  Version Naming

1. PreAlpha: This means the software is not feature complete and hence might be missing some functionality that is considered important by different users. Additionally, there might be no compatibility in data structures stored on disk between different pre-alpha versions, e.g., when upgrading from PreAlpha16 to PreAlpha17 the main queue format may have changed without checks in the software for this. Hence old queues must be drained before upgrading. Moreover, the protocols used for communication between MeTA1 modules may have changed without providing backward compatibility, therefore modules from different releases must not be used together. Such incompatibilities are usually stated in the list of changes ChangeLog.
   Do not run this on a production server unless you are aware of the possible consequences. The software is still under development and not fully functional. Moreover, it may not be sufficiently tested.
2. Alpha: In this state the software is ready for public testing but its features may still change.
3. Beta: Feature changes are unlikely, but still possible if required. Usually only bugfixes occur between beta versions.
4. Gamma: This is a release candidate. Usually only critical bugfixes occur between gamma versions. There might be no gamma versions at all if beta testing was considered successful and sufficient.
5. A release version does not have an explicit qualifier.

6.8.1  Snapshots

Chapter 7
Data and Control Flow in MeTA1

7.1  Data Flow in MeTA1

7.2  Caching of Routing Information

Chapter 8
Advanced Configuration Options

8.1  Overview

8.1.1  Flags

8.2  Advanced Configuration for MCP

1. processes_max : maximum number of processes to start [default: 1].
2. processes_min : minimum number of processes to start [default: 1].
3. use_id_in_logfile_name : if more than one process can be started then it might be useful to have unique logfiles unless the processes use syslog(3). If set, this (boolean) option causes MCP to include a unique identifier (the same as for pass_id, which must be used too) in the logfile name. By default the logfile has the name of the section (or the section keyword if no section name is given), preceeded by the log directory (option -L for MCP), and .log appended. If use_id_in_logfile_name is turned on, then the numeric id is added before the extension, e.g., /var/log/meta1/mailer0.log for -L /var/log/meta1/ and a section with the name mailer.
4. working_directory : perform a chdir(2) to the specified directory before executing the process. Note: this option essentially requires that all relevant pathnames in the configuration file are absolute, otherwise it is very easy to misconfigure some pathnames, especially those shared between different processes.

8.3  Advanced Configuration for QMGR

1. debug_level : debug level (only if compiled with QMGR_DEBUG).
2. subsection DEFEDB: Note: The Berkeley DB documentation [Sleb] should be consulted before modifying any of these options.
   1. page_size : DB page size (this can only be set when the DB is initially created).
   2. cache_size : DB cache size.
   3. KBytes_written_for_checkpointing : If non-zero, a checkpoint will be done if more than the amount of KBytes of log data have been written since the last checkpoint (unit: KB).
   4. delay_between_2_checkpoints : Minimum delay between two checkpoints (unit: s).
   5. flags : flags for DEFEDB:
      1. remove_unused_logfiles : this is on by default, hence to turn it off one of the forms explained in Section 8.1.1, e.g., dont_remove_unused_logfiles, can be used. This should only be done if the Berkeley DB logfiles are removed some other way, e.g., after archiving.
   6. hash_table_entries : Initial size for the in-memory cache of entries in DEFEDB in order of the next time to try. This should be as large as the estimated number of entries in DEFEDB and should be a power of 2; the valid range is 128 to 67108864 (2²⁶). Note: this is not a Berkeley DB configuration option.
3. delivery_timeout : timeout for a single delivery attempt (unit: s). This value should be large enough that even big mails can be delivered over a slow link before the QMGR considers the delivery attempt a failure because the delivery agent did not return a result yet.
4. flags : configuration flags:
   1. reuse_connection : try to reuse open SMTP connections for delivery. Note: this feature is still experimental.
5. fds_max : maximum number of file descriptors. This sets an upper limit on the number of clients that can connect to QMGR.
6. threads_max : maximum number of threads.
7. threads_min : minimum number of threads.
8. scheduler_timeout : as a safety measure against unforseen problems an item is removed from AQ after the specified timeout. This timeout must be large enough to allow for scheduling delays if all delivery agents are busy which can happen if deliveries are slow or if there are fewer delivery agents available than entries in the active queue.
9. SMAR_timeout : timeout in address resolver, i.e., how long to wait for a result from SMAR (unit: s). Note: this value must be larger than the total DNS timeout and it must take alias expansion into account.
10. subsection smtps:
    1. connection_control_cache_size : size of connection control hash table.
    2. connection_control_hash_table_size : size of the hash table used for connection control, i.e., number of incoming connections and connection rate (see Section 3.8, 17a and 17b)
11. tests : testing only (available if QMGR is compiled with -DQMGR_TEST). See the source code for details.

8.4  Advanced Configuration for SMAR

1. DNS : this subsection contains DNS related options.
   1. flags : valid flags are:
      1. use_TCP : use TCP instead of UDP for connections to a nameserver.
         Notes:
         1. currently the DNS resolver does not automatically fall back to a TCP connection if the reply was too big. This may be added in a later version.
         2. the current implementation immediately reconnects if a DNS server closes a TCP connection, e.g., due to a timeout. Hence the DNS server should be configured such that it does not close the connection.
      2. use_connect : use connect(2) even if using UDP. This is required on systems like FreeBSD jail(8).
2. fds_max : maximum number of file descriptors. This sets an upper limit on the number of clients that can connect to SMAR.
3. threads_max : maximum number of threads.
4. threads_min : minimum number of threads.

8.5  Advanced Configuration for SMTP Server

1. daemon_address : address for daemon to listen on; this should not be used in normal operation. Current (preliminary) format is: host:port, :port (listen on 0.0.0.0) host (port defaults to 8000). Up to 16 addresses¹⁸ can be specified. See the notes below.
2. flags :
   1. background : fork(2) after start; this should not be used in normal operation.
   2. serialize_accept : serialize accept(2) calls, see the statethreads documentation [SGI01] for details.
3. DKIM_signing :
   Note: the maximum length of the DKIM-signature header is currently 1000 byte.
   1. total_header_len : DKIM signing requires to buffer the entire header before it can be fed into the hashing algorithm. Hence it is necessary to restrict the amount of memory consumed for this purpose. The default is 1 MB, the valid range is 257 B to 1 GB.
   2. header_val_len_max : Maximum length of an individual header value. The default is 64 KB, the valid range is 257 B to 1 MB.
4. listen_queue : length of listen(2) queue; this must not be used in normal operation, i.e., if MCP is used.
5. wait_threads_max : maximum number of waiting threads.
6. wait_threads_min : minimum number of waiting threads.
7. module_timeout : timeout for communication with other modules.
8. processes : number of processes to start.
9. wait_for_smar : maximum amount of time to wait for a reply from SMAR.

8.5.1  Experimental Configuration for SMTP Server

1. action: currently only one of permfail: generate permanent failure, tempfail: generate temporary failure, abort: abort session.
2. condition: boolean expression that specifies when to apply the action. Note: for implementation-specific reasons this requires instead of a single after the option, e.g,
   condition == mail =~ "example.com";

check mail {
   condition == mail =~ "example.com";
   action = permfail; }
check mail {
   condition == mail =~ "example.org"; action = tempfail; }
check rcpt { condition == rcpt =~ "example.org";
  action = tempfail; }

8.6  Advanced Configuration for SMTP Client

1. connect_only_to : Specify an IP address to which all outgoing mail is sent. This can be used for testing with otherwise real data, i.e., addresses, by running an SMTP sink¹⁹ on a computer and specifying its IP address. Then all mails that should be sent via SMTP will go to that host instead of the addresses determined by SMAR. Note: it is nevertheless a good idea to use firewall rules to prevent mail going out to the internet, i.e., prohibit connections to port 25 to external hosts.
2. debug_level : debug level (only if compiled with SMTPC_DEBUG).
3. flags : Note: all of these flags can all be set via session_features (see Section 3.11, 5)
   1. smtps : use implicit TLS handshake.
   2. timing : log the time it takes to complete most steps the SMTP dialogue (in microseconds), e.g., func=sc_data, ..., t_connect=2792, t_ehlo=2240, t_starttls=396355, t_mail=420, t_rcpts=20, t_data=7333, t_msg=326, t_eom=10948, size=219, stat=0, reply=250 ok
      (requires compile time option SC_STATS). Note: PIPELINING causes distortions of the timings, as the times are the interval between SMTP commands, which means that the time for synchronization points includes reading all replies for previous commands in a pipelined sequence. For example, if MAIL, RCPT, and DATA are issued together, the largest time will be shown for t_data.
   3. read_QUIT_reply : read the reply to the QUIT command instead of just closing the connection after sending it. Note: this option causes problems with procmail [vdBG] as it will exit with an OS error (EX_OSERR) when sending the 221 reply, which in turn will triger the error handling of mcp. Hence this option should be turned off for LMTP delivery to procmail, or procmail should be patched to ignore that error.
   4. separate_final_dot_and_QUIT : send the final dot of a message and the QUIT command in different TCP packages even if PIPELINING is offered. This can avoid problems with some broken servers or firewalls.
   5. talk_to_myself : do not check whether server greets with the hostname of the machine on which smtpc runs.
4. wait_threads_max : maximum number of waiting threads.
5. wait_threads_min : minimum number of waiting threads.
6. module_timeout : timeout for communication with QMGR.
7. remote_port : port to which connections should be made. Note: if multiple SMTP clients are specified, all of them must use the same value for remote_port. Currently the scheduler requires that all SMTP clients behave the same. If different ports are required, then those must be listed in mailertable entries.

Chapter 9
Tuning

9.1  Size of Queues, Caches, and Databases

9.2  Disk I/O

1. IBDB: the directory can be linked to a different disk.
2. DEFEDB: the base directory can be changed via an option (Section 3.8, item 4a), as well as the directory for logfiles (Section 3.8, item 4b).
3. CDB: the base directory can be changed via an option (see Section 3.4, item 2). Individual subdirectories (see Section 2.4.1) can be linked to different disks.

9.3  Processes and Threads

9.4  Process Statistics

Chapter 10
Format Specifications

10.1  Regex Map

/regex/ value

/bounce-[0-9]+-[0-9]+@/ei error:550 5.7.1 no numbered bounces
;user@friendly.domain;i   OK
,sender\+[a-z]+@.*\.other.domain,e   OK

10.2  Socket Map

11:hello there,

aliases {
     name = aliasmap;
     flags = { localpart, local_domains };
}

aliases foo@bar.net
aliases foo*@bar.net
aliases foo

31:OK resolved.address@example.com,

8:NOTFOUND,

55:TEMP this text explains that we had a temporary failure,

10.3  Format of Session/Transaction/Recipient Identifiers

10.4  Logfile Format

550 5.7.1 no, not now, 99% usage

550 5.7.1 no%2C not now%2C 99%25 usage

ss_se=S00000000407EAE3800, client_ip=127.0.0.1,
  client_name=localhost.endmail.org.
ss_se=S00000000407EAE3800, starttls=TLSv1
ss_se=S00000000407EAE3800, ss_ta=S00000000407EAE4E00,
  mail=<SENDER@meta1.org>, stat=0
ss_se=S00000000407EAE3800, ss_ta=S00000000407EAE4E00,
  rcpt=<RECIPIENT@meta1.org>, idx=0, stat=0
ss_se=S00000000407EAE3800, ss_ta=S00000000407EAE4E00,
  rcpt=<SOMEONE@SOME.DOMAIN>, idx=1, stat=0
ss_se=S00000000407EAE3800, ss_ta=S00000000407EAE4E00,
  msgid=<20040916050457.GG54961@endmail.org>, size=1177, stat=0

da_se=C01000006C800000002, status=connected, port=25, addr=64.81.247.36
da_se=C01000006C800000002, starttls=TLSv1
da_se=C01000006C800000002, da_ta=C01000006C900000002,
  ss_ta=S00000000407EAE4E00, mail=<SENDER@meta1.org>, stat=0,
  reply=250 2.5.0 MAIL command succeeded
da_se=C01000006C800000002, da_ta=C01000006C900000002,
  ss_ta=S00000000407EAE4E00, rcpt=<RECIPIENT@meta1.org>, stat=0,
  reply=250 2.1.5 RCPT ok
da_se=C01000006C800000002, da_ta=C01000006C900000002,
  ss_ta=S00000000407EAE4E00, where=final_dot, size=1177, stat=0

func=q_upd_rcpt_ok, rcpt_id=S00000000407EAE4E00-000000,
  rcpt=<RECIPIENT@meta1.org>, xdelay=0, delay=1

10.5  Format of Received Header

Received: from EHLO-NAME (CLIENT-NAME [CLIENT-ADDR])
        by HOST-NAME (MTA-VERSION) with PROTOCOL
        id SMTP-TA-ID; DATE

10.6  Format of DSNs

From: Mailer-Daemon@HOST.NAME
Subject: Undeliverable mail

A mail from you could not be delivered. See below for details.

Recipient:
<user@example.com>
Remote-MTA:
10.2.3.4
Reason:
550 5.7.1 <user@example.com>... Access denied
during RCPT

Chapter 11
Setup for STARTTLS

11.1  Certificates for STARTTLS

• client (as part of the CertificateRequest) (SSL_CTX_set_client_CA_list(3)),
• server if TLSv1.3 is used (SSL_CTX_set0_CA_list(3)).

error:14094417:SSL routines:SSL3_READ_BYTES:
sslv3 alert illegal parameter:s3_pkt.c:964:SSL alert number 47

C=FileName_of_CA_Certificate
ln -s $C `openssl x509 -noout -hash < $C`.0

-r--r--r--  1 root     wheel       CAcert.pem
-r--r--r--  1 meta1s   meta1c      smcert.pem
-r--r-----  1 meta1s   meta1c      smkey.pem
drwxr-xr-x  2 root     wheel       certs/

11.2  Advanced Configuration for STARTTLS

1. DSA_cert_file : file with DSA certificate in PEM format.
2. DSA_key_file : file with private key for DSA certificate in PEM format.
3. EC_cert_file : file with EC certificate in PEM format.
4. EC_key_file : file with private key for EC certificate in PEM format.
5. EC_curve : Names of elliptic curves to use (can be a list), e.g., something like of prime256v1 or secp384r1.

11.3  TLS Session Cache

Chapter 12
More About Configuration, Compilation, Debugging, and Testing

12.1  Compile Time Options

12.1.1  Generic

12.1.2  QMGR

12.1.3  SMAR

• SM_DNS_MX_MAX: maximum number of MX records for a domain,
• SM_DNS_A_PER_MX_MAX: maximum number of A records for one MX record,
• SM_DNS_A_MAX: maximum number of A records for a domain (after performing MX lookups).

12.1.4  SMTPS

• SS_EHLO_ACCESS_CHK enables lookups of the EHLO/HELO argument in the access map (Section 3.10, 4b) using the tag ehlo:. This must be enabled at runtime via the flag check_ehlo.

12.1.5  Debugging Compile Time Options

$ CFLAGS="-DSM_HEAP_CHECK" $PATHTO/meta1-$VERSION/configure

$ CFLAGS="-O -g -DSM_HEAP_CHECK -I/usr/local/include" \
 LDFLAGS="-L/usr/local/lib" \
 $PATHTO/meta1-$VERSION/configure

$ CPPFLAGS="-DOPENSSL_NO_KRB5"

12.2  Possible Compilation Problems or Warnings

1. If gcc is used as C compiler and full checking is turned on warnings like these are produced:

   warning: unknown conversion type character `N' in format
   warning: unsigned int format, sm_str_P arg (arg 3)
   warning: too many arguments for format
   
   

   Unfortunately gcc cannot be told about additional format specifiers and hence the misleading warning might be generated.
2. On some systems the following warning is generated by the compiler:

   `sys_nerr' is deprecated; use `strerror' or `strerror_r' instead
   
   

   sys_nerr is used to determine whether it makes sense to invoke strerror(3) at all. The systems that generate this error do not provide an alternative way to perform this check. Just ignore the warning or ask the authors of that warning for an alternative way to determine the range of defined error codes.

12.3  More About Test Programs

12.3.1  More Environment Variables used by Test Programs

• MTA_NAMESERVER : can be used to set a specific nameserver (IPv4 address) in case the simple script which extracts the first line beginning with nameserver from the file /etc/resolv.conf does not give the desired result.
• MTA_PMILTER_REGEX_TEST : can be used to enable the tests (make check in chkmts/) for the policy milter milter-regex provided it is enabled and compiled. Notes:
  • this requires that make check is executed in contrib/ before make check in chkmts/.
  • make check in contrib/ may fail due to a compilation error for milter-regex.c. If your OS has yacc(1) (or bison(1) installed then remove that file (milter-regex.c) and try again.
• Some test programs use SMTP servers and sinks listening on an INET port. The default values for these ports are specified in chkmts/common.sh. If one of the default ports is used by another program, then the corresponding environment variable must be set as otherwise all related test programs will fail.
  • MTA_SNKPORT : set the port on which the SMTP sink is listening.
  • MTA_SRVPORT : set the port on which the SMTP test server is listening.
• MTA_NO_IPV6_TEST : skips IPv6 related tests even if the compile time option MTA_NETINET6 is set.

12.3.2  Other Potential Problems with Test Programs

Known Test Program Problems specific to an OS/setup

• The test programs for SMAR which perform DNS lookups can fail because UDP does not work in a jail(8) as expected. A workaround for this is to use the -U option for smar which can be achieved by setting the environment variable SMAROPTS to that value.
• Connections from localhost to the SMTP server do not have 127.0.0.1 as source IP address, but the IP address of a NIC. Hence relaying must be allowed for it by setting the environment variable MTA_SERVER_OPTIONS to the option -C and the IP address, e.g., -C 10.2.3.4. Moreover, because the tests chkmts/t-mts-icr.sh and chkmts/t-mts-ocr.sh rely on connections coming from 127.0.0.1 they will fail too.

Chapter 13
Licenses

Chapter 14
Experimental Features

14.1  Cert Pinning

14.2  DANE

1. secure: only check TLSA records if they can be retrieved using DNSSEC (default).
2. never: turn off DANE.
3. always: check TLSA records even without DNSSEC (this is mostly for testing).

Chapter 15
Policy Milter

15.1  Native Policy Milter API

15.1.1  Data Structures

1. pmg_ctx: "global" libpmilter context (only one per process).
2. pmss_ctx: libpmilter context per SMTP server that connects to this instance. There can be multiple SMTP servers connecting to one libpmilter instance.
3. pmse_ctx: libpmilter context per SMTP session.

15.1.2  Start and Stop

15.1.3  New SMTP Server

15.1.4  SMTP Session and Transaction

• New SMTP session:
  sfsistat_T pmfi_connect(pmse_ctx_P pmse_ctx, const char *hostname, sm_sock_addr_T *hostaddr)
  hostname: host name, as determined by a reverse lookup on the host IP address; hostaddr: host address, as determined by a getpeername(2) call on the SMTP socket.
• SMTP HELO/EHLO command:
  sfsistat_T pmfi_helo(pmse_ctx_P pmse_ctx, const char *helohost, bool ehlo)
  helohost: Value passed to HELO/EHLO command, which should be the domain name of the sending host. ehlo: true iff EHLO was used.
• MAIL (envelope sender):
  sfsistat_T pmfi_mail(pmse_ctx_P pmse_ctx, const char *mail, char **argv)
  mail: envelope mail address; argv: null-terminated MAIL command arguments.
• RCPT (envelope recipient):
  sfsistat_T pmfi_rcpt(pmse_ctx_P pmse_ctx, const char *rcpt, char **argv)
  rcpt: envelope recipient address; argv: null-terminated RCPT command arguments.
• DATA:
  sfsistat_T pmfi_data(pmse_ctx_P pmse_ctx)
• unknown/not implemented SMTP command:
  sfsistat_T pmfi_unknown(pmse_ctx_P pmse_ctx, const char *cmd)
  cmd: SMTP command. Note: this is not yet implemented.
• For each chunk of a message:
  sfsistat_T pmfi_msg(pmse_ctx_P pmse_ctx, unsigned char *msgp, size_t msglen)
  msgp: pointer to message data; msglen: length of message data. There may be multiple message chunks passed to the filter. End-of-lines are represented as received from SMTP (normally Carriage-Return/Line-Feed; CRLF). Notes:
  • the last message chunk contains the final dot of the SMTP transmission, i.e., "CRLF.CRLF"
  • the message is not modified in any form, i.e., dots at the begin of a line are duplicated (by the SMTP client) as specified in section 4.5.2 of RFC 2821 [Kle01] which must be undone by the application if so desired.
  • the message is streamed while being received. That is, the mail is not first stored on disk and then sent to the filter, but each part received from the client is sent directly to the filter (at the same speed as received from the network which might be slow). This may mean that the filter does not receive the entire message as the transmission may get interrupted or the SMTP server may decide to skip the rest of the message because it exceeds the maximum size.
  • the return code is ignored unless SM_SCAP_PM_MSG_RC is set, see Section A.1.11, item 2.
• End of message (final dot of message has been received):
  sfsistat_T pmfi_eom(pmse_ctx_P pmse_ctx)
• Message is aborted outside of the control of the filter, for example, if the SMTP client issues an RSET command.
  sm_ret_T pmfi_abort(pmse_ctx_P pmse_ctx)
• QUIT (end of an SMTP session):
  sm_ret_T pmfi_close(pmse_ctx_P pmse_ctx)
  This is called when an SMTP session ends.

15.1.5  Set and Get pmilter Contexts

15.1.6  Accessing MTA Symbols

1. PMM_SRVHOSTNAME hostname of SMTP server.
2. PMM_SEID session id.
3. PMM_CLIENT_RESOLVE result of client lookups.
4. PMM_MAIL_TAID transaction id.
5. PMM_DOT_MSGID Message-Id.
6. PMM_TLS_VERSION TLS/SSL version used.
7. PMM_TLS_CIPHER_SUITE cipher suite used.
8. PMM_TLS_CIPHER_BITS effective key length of the symmetric encryption algorithm.
9. PMM_TLS_ALG_BITS maximum key length of the symmetric encryption algorithm. This may be less than the effective key length for export controlled algorithms.
10. PMM_TLS_VRFY the result of the verification of the presented cert.
11. PMM_TLS_CERT_SUBJECT the DN (distinguished name) of the presented certificate.
12. PMM_TLS_CERT_ISSUER the DN (distinguished name) of the CA (certifcate authority) that signed the presented certificate (the cert issuer).
13. PMM_TLS_CN_SUBJECT the CN (common name) of the presented certificate.
14. PMM_TLS_CN_ISSUER the CN (common name) of the CA that signed the presented certificate.
15. PMM_AUTH_TYPE the AUTH mechanism used.
16. PMM_AUTH_AUTHEN the client's authentication credentials as determined by authentication.
17. PMM_AUTH_AUTHOR The authorization identity, i.e. the AUTH= parameter of the MAIL command if supplied.

• PMM_MAIL_TAID cannot be requested before PM_SMST_MAIL and PMM_DOT_MSGID can only be requested at stage PM_SMST_DOT.
• All macros beginning with PMM_TLS are only valid after a STARTTLS command.

Additional Functions to set the list of MTA Symbols

• int sm_pmfi_name2mac(const char *name, const char **pname)
  returns the macro number for an MTA symbol. If **pname is not NULL then *pname points to the constant string of the MTA symbol name after a successful lookup.
• const char * sm_pmfi_mac2name(uint32_t n)
  Return a pointer to the constant string of the MTA symbol specified by the macro.
• int sm_pmfi_mac_stage(uint32_t n)
  Return the earliest stage in which the specified MTA symbol is valid.

15.1.7  Sender Modification

15.1.8  Recipient Modifications

15.1.9  Header Modifications

15.1.10  Message Replacement

• as the entire message is replaced and by default only the data that is received from the SMTP client is sent to a pmilter, the Received: header field that smtps generates is lost. To avoid this, a pmilter can request to receive that header field by setting SM_SCAP_PM_SND_RCVD and sending it as first chunk of the message replacement.
• the message must be in SMTP format, i.e., lines must end in CRLF and the final chunk should have the usual SMTP end of message indication: CRLF dot CRLF (rn.rn), however, it can also just end in CRLF.
• if pmfi_msg_rplc() encounters an error, e.g., due to an API violation or due to a communication error with smtps, then it will invoke pmfi_msg_rplc_stat() directly without waiting for the entire message even if it consists of more chunks.

15.1.11  Further Capabilities

1. SM_SCAP_PM_RCPT_ST causes the MTA to send RCPT information even if the command has been rejected, e.g., because the recipient is unknown, the recipient has been rejected due to access map checks, or relaying has been denied. Note: RCPT commands that are rejected for other reasons, e.g., because the address is syntactically invalid, or some limit (maximum number of recipients) is exceeded, will not be sent to pmilter.
   The function
   sm_ret_T sm_pmfi_getstatus(pmse_ctx_P pmse_ctx, sfsistat_T *pstatus)
   should be used in that case to access the current SMTP reply code for the command. This functionality is useful for a pmilter that wants to keep track of all recipients, not just those which are accepted, e.g., to deal with dictionary attacks.
2. SM_SCAP_PM_MSG_RC allows a pmilter to return a reply code as specified in A.1.13 from pmfi_msg(). This is useful if a pmilter can make a decision about the mail without having to read the entire message. If this capability is turned on, pmfi_msg() must return SMTP_R_CONT for each message chunk by default to receive subsequent parts. Otherwise pmfi_eom() will not be called but the return code from pmfi_msg() will be used at the end of the message (in response to the final dot).

15.1.12  Miscellaneous Functions

XYZ-D.S.N text1
XYZ-D.S.N text2
XYZ D.S.N text3

15.1.13  Return Values

• SMTP_R_OK: accept command.
• SMTP_R_ACCEPT: accept entire transaction or session depending on where this value is returned. Note: this is just a shortcut for SMTP_R_SET_QUICK(SMTP_R_OK).
• SMTP_R_DISCARD: discard effect of command.
• SMTP_R_CONT: continue other checks.
• SMTP_R_SSD: shut down SMTP session.
• SMTP_R_TEMP: reject command with a temporary error.
• SMTP_R_SYNTAX: syntax error.
• SMTP_R_PERM: reject command with a permanent error.
• other valid SMTP reply codes [Kle01].

15.1.14  Implementation Notes

15.2  Policy Milter Examples

15.2.1  Compiling Policy Milters

Bibliography

[ACD⁺07]

E. Allman, J. Callas, M. Delany, M. Libbey, J. Fenton, and M. Thomas. DomainKeys Identified Mail (DKIM) Signatures. RFC 4871, Internet Engineering Task Force, 2007.

[Aßma]

Claus Aßmann. Sendmail X. http://www.sendmail.org/%7Eca/email/sm-9-rfh.html.

[Aßmb]

Claus Aßmann. Sendmail X: Requirements, Architecture, Functional Specification, Implementation, and Performance. http://www.sendmail.org/%7Eca/email/sm-X/.

[Ber97]

Dan Bernstein. VERP: Variable Envelope Return Paths, 1997. http://cr.yp.to/proto/verp.txt.

[Cyr]

Project Cyrus. http://asg.web.cmu.edu/cyrus/, http://asg.web.cmu.edu/sasl/.

[DKI]

DKIM. http://www.dkim.org/.

[Fre00]

N. Freed. SMTP service extension for command pipelining. RFC 2920, Internet Engineering Task Force, 2000.

[Gnu]

GnuPG. GNU Privacy Guard. http://www.gnupg.org/.

[Hal07]

Eric A. Hall. Smtp service extension for per-recipient data responses (prdr). Draft, Internet Engineering Task Force, 2007.

[Hara]

Evan Harris. The next step in the spam control war: Greylisting. http://greylisting.org/articles/whitepaper.shtml.

[Harb]

Evan Harris. Whitelisting. http://greylisting.org/whitelisting.shtml.

[Harc]

Daniel Hartmeier. benzedrine.cx - milter-spamd. http://www.benzedrine.cx/milter-spamd.html.

[Hof99]

P. Hoffman. SMTP service extension for secure SMTP over TLS. RFC 2487, Internet Engineering Task Force, 1999.

[Kle01]

Simple mail transfer protocol. RFC 2821, Internet Engineering Task Force, 2001.

[MeT]

PGP keys. http://www.MeTA1.org/security/PGPKEYS.

[Moc87]

P.V. Mockapetris. Domain names - implementation and specification. RFC 1035, Internet Engineering Task Force, 1987.

[mut]

mutt. http://www.mutt.org/.

[MV03]

K. Moore and G. Vaudreuil. An Extensible Message Format for Delivery Status Notifications. RFC 3464, Internet Engineering Task Force, 2003.

[Mye96]

John Myers. Local mail transfer protocol. RFC 2033, Internet Engineering Task Force, 1996.

[Mye99]

J. Myers. SMTP service extension for authentication. RFC 2554, Internet Engineering Task Force, 1999.

[New04]

Chris Newman. ESMTP and LMTP Transmission Types Registration. RFC 3848, Internet Engineering Task Force, 2004.

[Ope]

OpenSSL. http://www.openssl.org/.

[PGP]

PGP. http://www.pgp.com/.

[Posa]

Jef Poskanzer. graymilter - simple graylist mail filter module. http://www.acme.com/software/graymilter/.

[Posb]

Jef Poskanzer. mini_sendmail - accept email on behalf of real sendmail. http://www.acme.com/software/mini_sendmail/.

[SGI01]

SGI. State threads for internet applications, 2001. http://state-threads.sourceforge.net/.

[Slea]

Berkeley DB 4.4.XX Change Log. http://www.sleepycat.com/update/4.4.XX/if.4.4.XX.html.

[Sleb]

Berkeley DB Tutorial and Reference Guide, version 4.3.28. http://www.sleepycat.com/docs/.

[Tok]

Michael Tokarev. tinycdb: A package for maintenance of constant databases. ftp://ftp.corpit.ru/pub/tinycdb/.

[Vau03]

G. Vaudreuil. Enhanced mail system status codes. RFC 3463, Internet Engineering Task Force, 2003.

[vdBG]

S.R. van den Berg and Philip Guenther. procmail. http://www.procmail.org/.

Index (showing section)

Footnotes: