10.5.1 The Version Level Command

The version level command is an optional command not found in all sendmail.cf files. You don't add a V command to the sendmail.cf file or change one if it is already there. The V command is inserted into the configuration file when it is first built from m4 macros or by the vendor.

The level number on the V command line indicates the version level of the configuration syntax. V1 is the oldest configuration syntax and V7 is the version supported by sendmail V8.8.5. Every level in between adds some feature extensions. The vendor part of the V command identifies if any vendor specific syntax is supported. The default vendor value for the sendmail distribution is "Berkeley".

The V command tells the sendmail executable the level of syntax and commands required to support this configuration. If the sendmail program cannot support the requested commands and syntax, it displays the following error message:

# /usr/lib/sendmail -Ctest.cf
test.cf: line 63: Bad V line: Only V1/sun syntax is supported in
     this release

The error message shown above indicates that this sendmail program supports level 1 configuration files with Sun syntax extensions. [12] The example was produced on a Solaris 2.5.1 running the sendmail program that came with the operating system. In the example we attempted to read a sendmail.cf that was created by the m4 macros that came with sendmail 8.8.5. The syntax and functions needed by the sendmail.cf file are not available in the sendmail program. To use this configuration file, we would have to compile a newer version of the sendmail program. See Appendix E for an example of compiling sendmail.

[12] See Table 10-4 for Sun-specific syntax.

You will never change the values on a V command. You might, however, need to customize some D commands.

10.5.2 The Define Macro Command

The define macro command ( D ) defines a macro and stores a value in it. Once the macro is defined, it is used to provide the stored value to other sendmail.cf commands and directly to sendmail itself. This allows sendmail configurations to be shared by many systems, simply by modifying a few system-specific macros.

A macro name can be any single ASCII character or, as of sendmail V8, a word enclosed in curly braces. User-created macros use uppercase letters as names. sendmail's own internal macros use lowercase letters and special characters as names. This does not mean that you won't be called upon to define a value for a macro with a lowercase name. A few of these internal macros are sometimes defined in the sendmail.cf file. Table 10.2 provides a complete list of sendmail's internal macros.

Table 10.2: sendmail's Internal Macros

Name	Function
a	Origination date in RFC 822 format
b	Current date in RFC 822 format
c	Hop count
d	Date in UNIX (ctime) format
e	SMTP entry message
f	Sender \(lqfrom\(rq address
g	Sender address relative to the recipient
h	Recipient host
i	Queue id
j	Fully qualified domain name (host plus domain)
k	UUCP node name
l	Format of the UNIX from line
m	Name of this domain (domain only)
n	Name of the daemon (for error messages)
o	Set of "operators" in addresses[13]
p	Sendmail's pid
q	Default format of sender address[13]
r	Protocol used
s	Sender's hostname
t	Numeric representation of the current time
u	Recipient user
v	Version number of sendmail
w	Hostname of this site (host only)
x	Full name of the sender
z	Home directory of the recipient
-	Validated sender address

[13] Obsolete in sendmail V8.

To retrieve the value stored in a macro, reference it as $ x , where x is the macro name. Macros are expanded when the sendmail.cf file is read. A special syntax, $& x , is used to expand macros when they are referenced. The $& x syntax is only used with certain internal macros that change at runtime.

The code below defines the macros R, M, and Q. After this code executes, $R returns almond , $M returns nuts.com , and $Q returns almond.nuts.com . This sample code defines Q as containing the value of R ( $R ), plus a literal dot, plus the value of M ( $M ).

DRalmond
DMnuts.com
DQ$R.$M

If you customize your sendmail.cf file, it will probably be necessary to modify some macro definitions. The macros that usually require modification define site-specific information, such as hostnames and domain names.

10.5.3 The Define Class Command

Two commands, C and F , define sendmail classes. A class is similar to an array of values. Classes are used for anything with multiple values that are handled in the same way, such as multiple names for the local host or a list of uucp hostnames. Classes allow sendmail to compare against a list of values, instead of against a single value. Special pattern matching symbols are used with classes. The $= symbol matches any value in a class, and the $~ symbol matches any value not in a class. (More on pattern matching later.)

Like macros, classes usually have single-character names, and user-created classes use uppercase letters for names. Class values can be defined on a single line, on multiple lines, or loaded from a file. For example, class w is used to define all of the hostnames by which the local host is known. To assign class w the values goober and pea , you can enter the values on a single line:

Cwgoober pea

Or you can enter the values on multiple lines:

Cwgoober
Cwpea

You can also use the F command to load the class values from a file. The F command reads a file and stores the words found there in a class variable. For example, to define class w and assign it all of the strings found in /etc/sendmail.cw , use:

Fw/etc/sendmail.cw

You may need to modify a few class definitions when creating your sendmail.cf file. Frequently information relating to uucp , to alias hostnames, and to special domains for mail routing is defined in class statements. If your system has a uucp connection as well as a TCP/IP connection, pay particular attention to the class definitions. But in any case, check the class definitions carefully and make sure they apply to your configuration.

Here we grep the Linux sample configuration file for lines beginning with C or F :

% 

grep '^[CF]' linux.smtp.cf


Cwlocalhost
CP.
CO @ % 
C..
CE root

This grep shows that linux.smtp.cf defines classes w, P, O, ., and E. w contains the host's alias hostnames. P holds pseudo-domains used for mail routing. O stores operators that cannot be part of a valid username. The class . (dot) is primarily of interest because it shows that variable names do not have to be alphabetic characters. E lists the usernames that should always be associated with the local host's fully qualified domain name, even if simplified email addresses are being used for all other users. (More on simplified addresses later.) In our sample file, the variables are all assigned default values.

Remember that your system will be different. The uppercase letters used for some of these class names mean that they are user-created classes. These same class names may be used for other purposes on your system, and are only presented here as an example. Carefully read the comments in your sendmail.cf file for guidance as to how classes and macros are used in your configuration.

The class names that are lowercase letters or special characters are reserved for internal sendmail use. All internal classes defined in sendmail versions after 8.8 are shown in Appendix E . Most of these can be ignored. Only class w, which defines all of the hostnames the system will accept as its own, is commonly modified in the sendmail.cf file.

10.5.4 The Set Option Command

The set option commands ( O ) command is used to define the sendmail environment. Use the O command to set values appropriate for your installation. The value assigned to an option is a string, an integer, a Boolean, or a time interval, as appropriate for the individual option. All options define values used directly by sendmail.

There are no user-created options. The meaning of each sendmail option is defined within sendmail itself. Appendix E lists the meaning and use of each option, and there are plenty of them.

A few sample options from the linux.smtp.cf file are shown below. The AliasFile option defines the name of the sendmail aliases file as /etc/aliases . If you want to put the aliases file elsewhere, change this option. The TempFileMode option defines the default file mode as 0600 for temporary files created by sendmail in /var/spool/mqueue . The Timeout.queuereturn option sets the timeout interval for undeliverable mail, here set to five days (5d). These options show the kind of general configuration parameters set by the option command.

# location of alias file
O AliasFile=/etc/aliases
# temporary file mode
O TempFileMode=0600
# default timeout interval
O Timeout.queuereturn=5d

The syntax of the option command shown in this example and in Table 10.1 was introduced in sendmail version 8.7.5. Prior to that the option command used a syntax more like the other sendmail commands. The old syntax is: O ovalue , where O is the command, o is the single character option name, and value is the value assigned to the option. The options shown in the previous discussion, if written in the old syntax, would be:

# location of alias file
OA/etc/aliases
# temporary file mode
OF0600
# default timeout interval
OT5d

Appendix E contains a full listing of the old options as well as the new options.

Most of the options defined in a sample file don't require modification. People change options settings because they want to change the sendmail environment, not because they have to. The options in your configuration file are almost certainly correct for your system.

10.5.5 Defining Trusted Users

The T command defines a list of users who are trusted to override the sender address using the mailer -f flag. [14] Normally the trusted users are defined as root , uucp , and daemon . Trusted users can be specified as a list of usernames on a single command line, or on multiple command lines. The users must be valid usernames from the /etc/passwd file.

[14] Mailer flags are listed in Appendix E .

The most commonly defined trusted users are:

Troot
Tdaemon
Tuucp

Most sites do not need to modify this list.

10.5.6 Defining Mail Precedence

Precedence is one of the factors used by sendmail to assign priority to messages entering its queue. The P command defines the message precedence values available to sendmail users. The higher the precedence number, the greater the precedence of the message. The default precedence of a message is 0. Negative precedence numbers indicate especially low-priority mail. Error messages are not generated for mail with a negative precedence number, making low priorities attractive for mass mailings. Some commonly used precedence values are:

Pfirst-class=0
Pspecial-delivery=100
Plist=-30
Pbulk=-60
Pjunk=-100

To specify the precedence he desires, a user adds a Precedence header to his message. He uses the text name from the P command in the Precedence header to set the specific precedence of the message. Given the precedence definitions shown above, a user who wanted to avoid receiving error messages for a large mailing could select a message precedence of -60 by including the following header line in his mail:

Precedence: bulk

The five precedence values shown above are probably more than you'll ever need.

10.5.7 Defining Mail Headers

The H command defines the format of header lines that sendmail inserts into messages. The format of the header command is the H command, optional header flags enclosed in question marks, a header name, a colon, and a header template. The header template is a combination of literals and macros that are included in the header line. Macros in the header template are expanded before the header is inserted in a message. The same conditional syntax used in macro definitions can be used in header templates, and it functions in exactly the same way: it allows you to test whether a macro is set and to use another value if it is not set.

The header flags often arouse more questions than they merit. The function of the flags is very simple. The header flags control whether or not the header is inserted into mail bound for a specific mailer. If no flags are specified, the header is used for all mailers. If a flag is specified, the header is used only for a mailer that has the same flag set in the mailer's definition. (Mailer flags are listed in Appendix E .) Header flags only control header insertion . If a header is received in the input, it is passed to the output, regardless of the flag settings.

Some sample header definitions from the linux.smtp.cf sample file are:

H?P?Return-Path: $g
H?D?Date: $a
H?F?From: $?x$x <$g>$|$g$.
H?x?Full-Name: $x
HSubject:
H?M?Message-Id: <$t.$i@$j>

The headers provided in your system's sendmail.cf are sufficient for most installations. It's unlikely you'll ever need to change them.

10.5.8 Defining Mailers

The M commands define the mail delivery programs used by sendmail. The syntax of the command is:

M


name

, {

field=value

}

name is an arbitrary name used internally by sendmail to refer to this mailer. The name doesn't matter as long as it is used consistently within the sendmail.cf file to refer to this mailer. For example, the mailer used to deliver SMTP mail within the local domain might be called smtp on one system, and it might be called ether on another system. The function of both mailers is the same, only the names are different.

There are a few exceptions to this freedom of choice. The mailer that delivers local mail to users on the same machine must be called local , and a mailer named local must be defined in the sendmail.cf file. Three other special mailer names are:

prog

Delivers mail to programs.

*file*

Sends mail to files.

*include*

Directs mail to :include: lists.

Of these, only the prog mailer must be defined in the sendmail.cf file. The other two are defined internally by sendmail.

The mailer name is followed by a comma-separated list of field=value pairs that define the characteristics of the mailer. Table 10.3 shows the single character field identifiers and the contents of the value field associated with each of them. Most mailers don't require all of these fields.

Table 10.3: Mailer Definition Fields

Field	Meaning	Contents	Example
P	Path	Path of the mailer	P=/bin/mail
F	Flags	sendmail flags for this mailer	F=lsDFMe
S	Sender	Rulesets for sender addresses	S=10
R	Recipient	Rulesets for recipient addresses	R=20
A	Argv	The mailer's argument vector	A=sh -c $u
E	Eol	End-of-line string for the mailer	E=\r\n
M	Maxsize	Maximum message length	M=100000
L	Linelimit	Maximum line length	L=990
D	Directory	prog mailer's execution directory	D=$z:/
U	Userid	User and group ID used to run mailer	U=uucp:wheel
N	Nice	nice value used to run mailer	N=10
C	Charset	Content-type for 8-bit MIME characters	C=iso8859-1
T	Type	Type information for MIME errors	T=dns/rfc822/smtp

The Path (P) fields contain either the path to the mail delivery program or the literal string [IPC]. Mailer definitions that specify P=[IPC] use sendmail to deliver mail via SMTP. [15] The path to a mail delivery program varies from system to system depending on where the systems store the programs. Make sure you know where the programs are stored before you modify the Path field. If you use a sample configuration from another computer, such as the samples we use in this chapter, make sure that the mailer paths are valid for your system.

[15] Sun systems use [TCP] as well as [IPC].

The Flags (F) field contains the sendmail flags used for this mailer. These are the mailer flags referenced earlier in this chapter under "Defining Mail Headers," but mailer flags do more than just control header insertion. There are a large number of flags. Appendix E describes all of them and their functions.

The Sender (S) and the Recipient (R) fields identify the rulesets used to rewrite the sender and recipient addresses for this mailer. Each ruleset is identified by its number. We'll have more to say about rulesets later in this chapter, and we will refer to the S and R values when troubleshooting the sendmail configuration.

The Argv (A) field defines the argument vector passed to the mailer. It contains, among other things, macro expansions that provide the recipient username (which is $u ), [16] the recipient hostname ( $h ), and the sender's from address ( $f ). These macros are expanded before the argument vector is passed to the mailer.

[16] In the prog mailer definition, $u actually passes a program name in the argument vector.

The End-of-line (E) field defines the characters used to mark the end of a line. A carriage return and a line feed (CRLF) is the default for SMTP mailers.

Maxsize (M) defines, in bytes, the longest message that this mailer will handle. This field is used most frequently in definitions of UUCP mailers.

Linelimit (L) defines, in bytes, the maximum length of a line that can be contained in a message handled by this mailer. This mailer field was introduced in sendmail V8. Previous versions of sendmail limited lines to 80 characters because this was the limit for SMTP mail before MIME mail was introduced.

The Directory (D) field specifies the working directory for the prog mailer. More than one directory can be specified for the directory field by separating the directory paths with colons. The example in Table 10.3 tells prog to use the recipient's home directory, which is the value returned by the internal macro $z . If that directory is not available, it should use the root (/) directory.

Specify the default user and the group ID used to execute the mailer with the Userid (U) field. The example U=uucp:wheel says that the mailer should be run under the user ID uucp and the group ID wheel . If no value is specified for the Userid field, the value defined by the DefaultUser option is used.

Use Nice (N) to change the nice value for the execution of the mailer. This allows you to change the scheduling priority of the mailer. This is rarely used. If you're interested, see the nice manpage for appropriate values.

The last two fields are used only for MIME mail. Charset (C) defines the character set used in the Content-type header when an 8-bit message is converted to MIME. If Charset is not defined, the value defined in the DefaultCharset option is used. If that option is not defined, unknown-8bit is used as the default value.

The Type (T) field defines the type information used in MIME error messages. MIME-type information defines the mailer transfer agent type, the mail address type, and the error code type. The default is dns/rfc822/smtp .