Before we get into rule sets let's do a quick overview of macros and classes.
A capital D at the start of a line denotes a macro:
Djsomehost.foo.com
This sets the value of the macro, j, to somehost.foo.com. If a macro has more than one character for the macro name then the name of the macro will be enclosed within curly braces.
The macro can then be accessed by using a dollar sign followed by the name of the macro.
Both of the following denote the fully qualified domain name of the current machine:
Dj
$j
One sets the value, Dj, and the other is a reference to that value, $j.
A capital C at the start of a line denotes a class. A class is a macro with multiple values:
C{E}root smmsp
In the example above, class E, contains the values, root and smmsp.
A class could also be stored in a file by using:
FR -o /etc/mail/relay-domains
The class name is R, -o means the file is optional, and the values are stored in the file /etc/mail/relay-domains.
To reference the values of a class you would use $=classname in your rule or header definition.
$=w
tells Sendmail to compare the entry to the contents of the class w.
When we discussed terminology I mentioned a few macros that you need to be aware of. Now I'll list some more.
$_ (underscore) Identify the user and host that initiated the network connection
$a (lowercase a) The origination date in RFC 822 format.
$b (lowercase b) The current date in RFC 822 format.
$c (lowercase c) The hop count of the message
$d (lowercase d) Current date in ctime format
$f (lowercase f) The Envelope sender's address
$g (lowercase g) The sender address relative to the recipient. For example, if $f is "foo", $g will be "host!foo", "foo@host.domain", or whatever is appropriate for the receiving mailer.
$h (lowercase h) Host part of a mailer triple
$i (lowercase eye) The queue id
$j (lowercase j) Fully Qualified Domain Name of this host
$m (lowercase m) DNS domain name
$n (lowercase n) The name of the daemon (for error messages). Defaults to "MAILER-DAEMON".
$p (lowercase p) Sendmail process id
$q (lowercase q) Default format of sender address. The $q macro specifies how an address should appear in a message when it is defaulted. Defaults to "<$g>". It is commonly redefined to be "$?x$x <$g>$|$g$." or "$g$?x ($x)$.", corresponding to the following two formats: Eric Allman <eric@CS.Berkeley.EDU> eric@CS.Berkeley.EDU (Eric Allman) Sendmail properly quotes names that have special characters if the first form is used.
$r (lowercase r) Protocol used when a mail message was first received
$s (lowercase s) Sender's machine name
$t (lowercase t) Current time in YYYYMMDDHHmm format
$u (lowercase u) Address part of a mailer triple
$v (lowercase v) Version of Sendmail
$w (lowercase w) Short name of the host
$x (lowercase x) Set to the full name of the sender.
$z (lowercase z) Home directory of the recipient
$_ The validated sender address. See also ${client_resolve}
${addr_type} The type of the address which is currently being rewritten. This macro contains up to three characters, the first is either `e' or `h' for envelope/header address, the second is a space, and the third is either `s' or `r' for sender/recipient address.
${alg_bits} The maximum keylength (in bits) of the symmetric encryption algorithm used for a TLS connection. This may be less than the effective keylength, which is stored in ${cipher_bits}, for ``export controlled'' algorithms.
${auth_authen} The client's authentication credentials as determined by authentication (only set if successful). The format depends on the mechanism used, it might be just `user', or `user@realm', or something similar (SMTP AUTH only).
${auth_author} The authorization identity, i.e. the AUTH= parameter of the SMTP MAIL command if supplied.
${auth_type} The mechanism used for SMTP authentication (only set if successful).
${auth_ssf} The keylength (in bits) of the symmetric encryption algorithm used for the security layer of a SASL mechanism.
${bodytype} The message body type (7BIT or 8BITMIME), as determined from the envelope.
${cert_issuer} The DN (distinguished name) of the CA (certificate authority) that signed the presented certificate (the cert issuer) (STARTTLS only).
${cert_md5} The MD5 hash of the presented certificate (STARTTLS only).
${cert_subject} The DN of the presented certificate (called the cert subject) (STARTTLS only).
${cipher} The cipher suite used for the connection, e.g., EDH-DSS-DES-CBC3-SHA, EDH-RSA-DESCBC-SHA, DES-CBC-MD5, DES-CBC3-SHA (STARTTLS only).
${cipher_bits} The effective keylength (in bits) of the symmetric encryption algorithm used for a TLS connection.
${client_addr} The IP address of the SMTP client. IPv6 addresses are tagged with "IPv6:" before the address. Defined in the SMTP server only.
${client_connections} The number of open connections in the SMTP server for the client IP address.
${client_flags} The flags specified by the Modifier= part of ClientPortOptions where flags are separated from each other by spaces and upper case flags are doubled. That is, Modifier=hA will be represented as "h AA" in ${client_flags}, which is required for testing the flags in rulesets.
${client_name} The host name of the SMTP client. This may be the client's bracketed IP address in the form [ nnn.nnn.nnn.nnn ] for IPv4 and [ IPv6:nnnn:...:nnnn ] for IPv6 if the client's IP address is not resolvable, or if it is resolvable but the IP address of the resolved hostname doesn't match the original IP address. Defined in the SMTP server only. See also ${client_resolve}.
${client_port} The port number of the SMTP client. Defined in the SMTP server only.
${client_ptr} The result of the PTR lookup for the client IP address. Note: this is the same as ${client_name} if and only if ${client_resolve} is OK. Defined in the SMTP server only.
${client_rate} The number of incoming connections for the client IP address over the time interval specified by ConnectionRateWindowSize.
${client_resolve} Holds the result of the resolve call for ${client_name}. Possible values are:
OK - resolved successfully
FAIL - permanent lookup failure
FORGED - forward lookup doesn't match reverse lookup
TEMP - temporary lookup failure
sendmail performs a hostname lookup on the IP address of the connecting client. Next the IP addresses of that hostname is looked up. If the client IP address does not appear in that list, then the hostname is maybe forged. This is reflected as the value FORGED for ${client_resolve} and it also shows up in $_ as "(may be forged)".
${cn_issuer} The CN (common name) of the CA that signed the presented certificate (STARTTLS only).
${cn_subject} The CN (common name) of the presented certificate (STARTTLS only).
${currHeader} Header value as quoted string (possibly truncated to MAXNAME). This macro is only available in header check rulesets.
${daemon_addr} The IP address the daemon is listening on for connections.
${daemon_family} The network family if the daemon is accepting network connections. Possible values include "inet", "inet6", "iso", "ns", "x.25"
${daemon_flags} The flags for the daemon as specified by the Modifier= part of DaemonPortOptions whereby the flags are separated from each other by spaces, and upper case flags are doubled. That is, Modifier=Ea will be represented as "EE a" in ${daemon_flags}, which is required for testing the flags in rulesets.
${daemon_info} Some information about a daemon as a text string. For example, "SMTP+queueing@00:30:00".
${daemon_name} The name of the daemon from DaemonPortOptions Name= suboption. If this suboption is not set, "Daemon#", where # is the daemon number, is used.
${daemon_port} The port the daemon is accepting connection on. Unless DaemonPortOptions is set, this will most likely be "25".
${deliveryMode} The current delivery mode sendmail is using. It is initially set to the value of the DeliveryMode option.
${envid} The envelope id parameter (ENVID=) passed to sendmail as part of the envelope.
${hdrlen} The length of the header value which is stored in ${currHeader} (before possible truncation). If this value is greater than or equal to MAXNAME the header has been truncated.
${hdr_name} The name of the header field for which the current header check ruleset has been called. This is useful for a default header check ruleset to get the name of the header; the macro is only available in header check rulesets.
${if_addr} The IP address of the interface of an incoming connection unless it is in the loopback net. IPv6 addresses are tagged with "IPv6:" before the address.
${if_addr_out} The IP address of the interface of an outgoing connection unless it is in the loopback net. IPv6 addresses are tagged with "IPv6:" before the address.
${if_family} The IP family of the interface of an incoming connection unless it is in the loopback net.
${if_family_out} The IP family of the interface of an outgoing connection unless it is in the loopback net.
${if_name} The hostname associated with the interface of an incoming connection. This macro can be used for SmtpGreetingMessage and HReceived for virtual hosting. For example: O SmtpGreetingMessage=$?{if_name}${if_name}$|$j$. MTA
${if_name_out} The name of the interface of an outgoing connection.
${load_avg} The current load average.
${mail_addr} The address part of the resolved triple of the address given for the SMTP MAIL command. Defined in the SMTP server only.
${mail_host} The host from the resolved triple of the address given for the SMTP MAIL command. Defined in the SMTP server only.
${mail_mailer} The mailer from the resolved triple of the address given for the SMTP MAIL command. Defined in the SMTP server only.
${msg_id} The value of the Message-Id: header.
${msg_size} The value of the SIZE= parameter, i.e., usually the size of the message (in an ESMTP dialogue), before the message has been collected, thereafter the message size as computed by sendmail (and can be used in check_compat).
${nbadrcpts} The number of bad recipients for a single message.
${nrcpts} The number of validated recipients for a single message. Note: since recipient validation happens after check_rcpt has been called, the value in this ruleset is one less than what might be expected.
${ntries} The number of delivery attempts.
${opMode} The current operation mode (from the -b flag).
${quarantine} The quarantine reason for the envelope, if it is quarantined.
${queue_interval} The queue run interval given by the -q flag. For example, -q30m would set ${queue_interval} to "00:30:00".
${rcpt_addr} The address part of the resolved triple of the address given for the SMTP RCPT command. Defined in the SMTP server only after a RCPT command.
${rcpt_host} The host from the resolved triple of the address given for the SMTP RCPT command. Defined in the SMTP server only after a RCPT command.
${rcpt_mailer} The mailer from the resolved triple of the address given for the SMTP RCPT command. Defined in the SMTP server only after a RCPT command.
${server_addr} The address of the server of the current outgoing SMTP connection. For LMTP delivery the macro is set to the name of the mailer.
${server_name} The name of the server of the current outgoing SMTP or LMTP connection.
${time} The output of the time(3) function, i.e., the number of seconds since 0 hours, 0 minutes, 0 seconds, January 1, 1970, Coordinated Universal Time (UTC).
${tls_version} The TLS/SSL version used for the connection, e.g., TLSv1, SSLv3, SSLv2; defined after STARTTLS has been used.
${total_rate} The total number of incoming connections over the time interval specified by ConnectionRateWindowSize.
${verify} The result of the verification of the presented cert; only defined after STARTTLS has been used. Possible values are:
OK - verification succeeded.
NO - no cert presented.
NOT - no cert requested.
FAIL - cert presented but could not be verified, e.g., the signing CA is missing.
NONE - STARTTLS has not been performed.
TEMP - temporary error occurred.
PROTOCOL - some protocol error occurred.
SOFTWARE - STARTTLS handshake failed, which is a fatal error for this session, the e-mail will be queued.
There are three types of dates that can be used. The $a and $b macros are in RFC 822 format; $a is the time as extracted from the "Date:" line of the message (if there was one), and $b is the current date and time (used for postmarks). If no "Date:" line is found in the incoming message, $a is set to the current time also. The $d macro is equivalent to the $b macro in UNIX (ctime) format.
The macros $w, $j, and $m are set to the identity of this host. Sendmail tries to find the fully qualified name of the host if at all possible; it does this by calling gethostname(2) to get the current hostname and then passing that to gethostbyname(3) which is supposed to return the canonical version of that host name. Assuming this is successful, $j is set to the fully qualified name and $m is set to the domain part of the name (everything after the first dot). The $w macro is set to the first word (everything before the first dot) if you have a level 5 or higher configuration file; otherwise, it is set to the same value as $j. If the canonification is not successful, it is imperative that the config file set $j to the fully qualified domain name.
The $f macro is the id of the sender as originally determined; when mailing to a specific host the $g macro is set to the address of the sender relative to the recipient. For example, if I send to "bollard@matisse.CS.Berkeley.EDU" from the machine "vangogh.CS.Berkeley.EDU" the $f macro will be "eric" and the $g macro will be "eric@vangogh.CS.Berkeley.EDU."
The $x macro is set to the full name of the sender. This can be determined in several ways. It can be passed as flag to sendmail. It can be defined in the NAME environment variable. The third choice is the value of the "Full-Name:" line in the header if it exists, and the fourth choice is the comment field of a "From:" line. If all of these fail, and if the message is being originated locally, the full name is looked up in the /etc/passwd file.
When sending, the $h, $u, and $z macros get set to the host, user, and home directory (if local) of the recipient. The first two are set from the $@ and $: part of the rewriting rules, respectively.
The $p and $t macros are used to create unique strings (e.g., for the "Message-Id:" field). The $i macro is set to the queue id on this host; if put into the timestamp line it can be extremely useful for tracking messages. The $v macro is set to be the version number of sendmail; this is normally put in timestamps and has been proven extremely useful for debugging.
The $c field is set to the "hop count," i.e., the number of times this message has been processed. This can be determined by the -h flag on the command line or by counting the timestamps in the message.
The $r and $s fields are set to the protocol used to communicate with sendmail and the sending hostname. They can be set together using the -p command line flag or separately using the -M or -oM flags.
The $_ is set to a validated sender host name. If the sender is running an RFC 1413 compliant IDENT server and the receiver has the IDENT protocol turned on, it will include the user name on that host.
The ${client_name}, ${client_addr}, and ${client_port} macros are set to the name, address, and port number of the SMTP client who is invoking sendmail as a server. These can be used in the check_* rulesets (using the $& deferred evaluation form, of course!).
Next Section: Rule Sets - 14 of 32