Introduction

sendmail is a mail router. Mail from external hosts is routed to local users. Mail from local users is routed to the outside world. Mail from the user 's mail tool is routed to the correct mailer for delivery. In fact, all of the functions covered so far in this book ”delivery, forwarding, relaying, and masquerading ”are part of the work sendmail does as a mail router. The roles that the aliases database and the .forward file play in routing mail from one user account to another, and that relaying plays in routing mail from one host to another, are obviously components of mail routing. Even masquerading, which ensures that replies to the mail that originates from your site are routed to the correct system, is an aspect of routing.

Given that every recipe discussed so far has something to do with mail routing, why do we have a separate chapter with routing in the title? The reason is that the recipes in this chapter take mail routing and "BAM! Kick it up a notch !" ^[1] This chapter focuses on sendmail features that provide increased control over mail routing.

^[1] My apologies to Chef Emeril Lagasse and the Food Network, but, heck, this is a cookbook.

sendmail routes mail to internal mailers based on the mail's delivery address. When sendmail processes a delivery address, it returns a mail delivery triple that identifies the mailer that will be used, the host to which the mail will be sent, and the recipient address of the user to whom the mail is bound. The result of this process can be seen with a sendmail -bv test:

 #  sendmail -bv [e-mail]  [e-mail]... deliverable: mailer esmtp, host big.wrotethebook.net,  user [e-mail] 

The mailer used to send the mail, the host to which it is sent, and the recipient address used in that mail can all be seen in this simple test. The processing of a delivery address into a mail delivery triple is a fundamental part of what sendmail does, and it determines how mail is routed for delivery.

The mailertable

The mailertable database gives you direct control over this process by allowing you to specify which mailer is used and what remote host the mail is sent to based on the hostname part of the delivery address. Each mailertable entry contains two fields: a key that is matched against the hostname part of the delivery address and a return value that contains the mailer and host values for the mail delivery triple.

The key to a mailertable database entry is a full or partial domain name. A partial domain name key starts with a dot (.); e.g., jamis.wrotethebook.com is a full domain name key and .wrotethebook.com is a partial domain name key. To match a full domain name key, the entire hostname part of the delivery address must match the key. For example, if the key is crab.wrotethebook.com , only a delivery address of user @crab.wrotethebook.com matches the key. A partial domain name key is matched by any delivery address that ends with the key value. For example, if the key is .wrotethebook.com , any delivery address of the form user @ host .wrotethebook.com matches the key. A special key composed of a standalone dot (.) matches every possible hostname.

The return value in a mailertable entry is the internal name of the mailer through which the mail should be routed, and the hostname of the remote mail host to which the mail should be sent, written in the form mailer : host . The mailer field must always be a valid sendmail internal mailer name (e.g., esmtp , local , error , and so on). The host field is more flexible because its content is determined by what the specified mailer expects in the host part of a mail delivery triple. The host field often contains the hostname of a remote host. But in the case of the error mailer, the host field contains the error message; in the case of the local mailer, it contains a username. Recipes in this chapter provide examples of the various host field formats, but a basic mailertable entry looks something like the following:

 big.wrotethebook.net      smtp:mail.wrotethebook.com 

The impact of this mailertable entry is easy to see:

 #  sendmail -bv [e-mail]  [e-mail]... deliverable: mailer smtp, host mail.wrotethebook.com,  user [e-mail] 

Here, sendmail no longer uses the default esmtp mailer nor does it route mail through that mailer to the remote system big.wrotethebook.net . Instead, it uses the routing specified in the mailertable; in this case, mail addressed to big.wrotethebook.net is routed through the smtp mailer to mail.wrotethebook.com .

In the test above, only the mailer and host values changed, as specified in the mailertable . However, the recipient address in the user field is sometimes also rewritten. Specifying the mailer is one way the mailertable affects how the recipient address is processed . The R parameter in each mailer definition specifies the rulesets applied to the recipient address. All mailertable entries affect the recipient address indirectly through the mailer's R parameter. The mailertable can also directly control the recipient address in the user value of the mail delivery triple as described below.

The host field of a mailertable entry can contain a username. This is common when the entry routes mail through the local mailer:

 info.wrotethebook.com      local:pat 

With this entry, mail with a recipient address of user @info.wrotethebook.com is delivered to pat on the local host. In this case, user can be any username ”it does not need to really exist on any system.

Another database, the virtusertable , can route mail for hosts that do not exist as separate physical computers. The cf/README file calls these virtual domains , and the support for them in sendmail is called virtual hosting .

The virtusertable

sendmail provides support for virtual hosting through the virtusertable feature. The virtusertable allows multiple virtual mail domains to be hosted on one machine, which are similar to the virtual hosts used on Apache web servers. In the same way that a single web server can serve web pages for many virtual hosts, sendmail can provide mail service for many virtual mail domains.

Entries in the virtusertable have two fields: a key and an email address. The key contains the value that is matched against the input delivery address. The key can be a complete address in the form of user @ domain , or it can be a partial address in the form @ domain . When the @ domain format is used, mail to any user in the specified domain is routed to the mail address contained in the second field. The second field contains the address to which the mail is really delivered. There are only two exceptions to the use of a basic email address in the second field:

• The second field may contain an error message. The error messages starts with the keyword error , which is separated by a colon from an error code keyword, and followed by the text of the message. Table 5-1 contains a list of the sendmail error code keywords.

• An email address in the second field can contain variables. These variables are replaced by values from the input address that are passed to the outbound address. The username part of the input address is passed in the %1 variable, and the detail value in the + detail syntax is passed in the %2 variable. When the %2 variable is used in the second field, place +* before the @ in the first field of the virtusertable entry to indicate that the + detail syntax is used. For an example of how +* is used with %2 , see the last line of the sample virtusertable entries shown in the following example.

These sample virtusertable entries show the possible formats of the two fields:

 [e-mail]        jill [e-mail]    [e-mail] @wrotethebook.net        [e-mail] [e-mail]       error:nouser User address is not valid @other.wrotethebook.org  [e-mail] +*@thatplace.ora.com     [e-mail] 

The first three sample entries show basic virtual domains and delivery addresses. Mail addressed to [e-mail] is delivered to the jill account on the local host. Requests emailed to [e-mail] are forwarded to [e-mail] . Mail sent to any username in the wrotethebook.net domain is routed to [e-mail] . Mail is accepted with a virtual domain address and routed to a real email address

The fourth sample entry illustrates the formatting of error messages. Mail addressed to [e-mail] is not delivered. Instead an error message that says "User address is not valid" is returned to the sender. The error code is indicated by the keyword nouser in the example shown above. The keyword must be one of the valid keywords shown in Table 5-1.

Table 5-1. Error code keywords

Keyword	Meaning
config	A configuration error or routing loop was detected .
nohost	The host portion of the sender or recipient address is invalid.
nouser	The user portion of the sender or recipient address is invalid.
protocol	Network delivery failed.
tempfail	A temporary failure was detected.
unavailable	A delivery resource is not available.
usage	The syntax of the delivery address is bad.

The last two sample entries are examples of how values from the input address are used in the outbound address. In the @other.wrotethebook.org entry, the username part of the input address is passed in the %1 variable and used in the outbound address. Therefore, mail addressed to [e-mail] is routed to [e-mail] , and mail addressed to [e-mail] is sent on to [e-mail] .

The last entry passes the detail value from the + detail syntax used in the input address to the outbound address as %2 . Given the sample virtusertable entry just shown, mail sent to [e-mail] would be delivered to [e-mail] and mail to [e-mail] would be delivered to [e-mail] .

sendmail must be configured to accept mail addressed to virtual domains listed in the virtusertable database. Given the virtusertable just shown, sendmail must either accept example.com , wrotethebook.org , wrotethebook.net , chll.ora.com , other.wrotethebook.org , and thatplace.ora.com as aliases for the local host or recognize them as virtual domains. One solution is to create hostname aliases for each virtual domain. sendmail accepts any name contained in class $=w as an alias for the local host, and Recipe Recipe 2.1 shows how class $=w is loaded via the local-host- names file. When the use_cw_file feature is included in the configuration, listing the virtual domains in the local-host-names file loads them into class $=w and tells sendmail to accept mail for these domains.

However, it is not necessary to turn a virtual domain into a hostname alias to get the virtusertable working. An alternative is to store the virtual domain name in the $={VirtHost} class. Add virtual domain names to the $={VirtHost} class one at a time using the VIRTUSER_DOMAIN macro, or load the $={VirtHost} class from a file using the VIRTUSER_DOMAIN_FILE macro. Whenever virtual domains are added to the file, restart sendmail with a SIGHUP signal to make sure it loads the new values into class $={VirtHost} .

Before either the mailertable or the virtusertable can be used by sendmail, the text file that contains the database entries must be turned into a database using makemap . Specify the database type and the name of the database on the makemap command line:

 # makemap hash /etc/mail/mailertable < /etc/mail/mailertable 

By default, the sendmail.cf K commands for these databases define both mailertable and virtusertable as hash databases. The default filename for the mailertable is /etc/mail/mailertable , and the default name for the virtusertable database is /etc/mail/virtusertable . The default filenames and database types can be overridden in the sendmail configuration using the optional fields in the FEATURE macro. For example, a sendmail configuration that used the defaults for the mailertable , and overrode the defaults for the virtusertable , might contain the following FEATURE macros:

 FEATURE(`mailertable') FEATURE(`virtusertable', `dbm /etc/virtual-mail-domains') 

Changing the default database filename is not recommended. All of the documentation that comes with the sendmail distribution points to /etc/mail/mailertable and /etc/mail/virtusertable as the location of these files. Changing the filename provides no real advantages, and it makes it harder for other system administrators to locate the file when maintenance is required. Also, if you override the default database type, make sure that your sendmail program has the necessary database support compiled in.

LDAP Routing

sendmail can obtain mail routing information from an LDAP server. It can do this by reading the mailertable and the virtusertable from an LDAP server ”all sendmail databases can be read via LDAP. Recipe 5.5 shows how the mailertable is read from an LDAP server, and Recipe 5.8 shows how to read the virtusertable via LDAP. In addition to this, sendmail supports the IETF Internet Draft LDAP Schema for Intranet Mail Routing . The IETF draft schema defines the inetLocalMailRecipient object class. The attributes of this object class are:

mailLocalAddress

This attribute contains an email address, which is the key to the LDAP database. sendmail looks for records in which the mailLocalAddress attribute matches the recipient address that sendmail is processing. Every inetLocalMailRecipient object class record contains a mailLocalAddress attribute.

mailHost

This attribute contains the hostname of the mail host that handles mail address to the recipient identified by the mailLocalAddress attribute. Mail addressed to that recipient should be routed to this host for delivery. The mailHost attribute is a possible return value provided to sendmail in response to a query.

mailRoutingAddress

This attribute contains an email address. Mail addressed to the recipient identified by the mailLocalAddress attribute is delivered to the address specified by the mailRoutingAddress attribute. The mailRoutingAddress attribute is a possible return value provided to sendmail in response to a query.

Adding the ldap_routing feature to a sendmail configuration causes sendmail to query LDAP for routing information when sendmail processes a piece of mail addressed to a host listed in the $={LDAPRoute} class. If the query returns a mailHost value, sendmail uses that as the $h host value in the mail delivery triple. If the query returns a mailRoutingAddress value, sendmail uses that as the $u user address value in the mail delivery triple. Recipe 5.9 and Recipe 5.10 show how to use ldap_routing and the effect that the feature has on the mail delivery triple.

The mail routing information defined by the IETF draft schema does not provide any information that cannot already be provided by traditional sendmail databases, which is no surprise given the wide scope of sendmail configuration. Sites use the ldap_routing feature because they are already running an LDAP server, and they find the IETF schema more compatible with their database architecture. However, this is a draft schema, which may change in the future; hence, anything implemented using a draft schema may be affected by future changes. Consider your options carefully before using LDAP mail routing.