21.3 Configuration-File Definitions

When sendmail reads the configuration file, macros that are declared in that file are assigned values. The configuration-file command that declares macros begins with the letter D. There can be only one macro command per line. The form of the D macro configuration command is:

DXtext

The symbolic name of the macro (here, X) is a single-character or a multicharacter name (Section 21.4):

DX text  single-character name X  
D{XXX} text  multicharacter name XXX  

The symbolic name must immediately follow the D with no intervening space. The value that is given to the macro is the text, consisting of all characters beginning with the first character following the name and including all characters up to the end of the line. Any indented lines that follow the definition are joined to that definition. When joined, the newline and indentation characters are retained. Consider the following three configuration lines:

DXsometext
        moretext
        moretext
     
   tabs

These are read and joined by sendmail to form the following text value for the macro named X:

sometext\n\tmoretext\n\tmoretext

Here, the notation \n represents a newline character, and the notation \t represents a tab character.

If text is missing, the value assigned to the macro is that of an empty string; that is, a single byte that has a value of zero.

If both the name and the text are missing, the following error is printed, and that D configuration line is ignored:

configfile: line num: Name required for macro/class 

21.3.1 Syntax of the Configuration-File Macro's Text

The text of a macro's value in the configuration file can contain escaped control codes. Control codes are embedded by using a backslash escape notation. The backslash escape notations understood by sendmail are listed in Table 21-2.

Table 21-2. Special characters allowed in macro text

Notation	Placed in text
\b	Backspace character
\f	Formfeed character
\n	Newline character
\r	Carriage-return character
\\	Backslash character

All other escaped characters are taken as is. For example, the notation \X becomes an X, whereas the notation \b is converted to a backspace character (usually a Ctrl-H). For example:

DXO\bc May\, 2003    becomes   O^Hc May, 2003

Here, the \b is translated into a backspace character (Ctrl-H is shown as ^H), and the \, is translated into a literal comma character.

Note that prior to V8.8, the first comma and all characters following it were stripped from the text unless the comma was quoted or escaped. For example:

DXMay, 2003    became  May

Beginning with V8.8 sendmail, the comma is no longer special in defined sendmail macros.

Quoted text will have the quotation marks stripped. Only double quotation marks are recognized. Multiple parts of text can be quoted, or text can be quoted entirely.

Trailing spaces are automatically stripped. If you need to keep trailing spaces you need to quote them:

DX"2003 "

Leading space characters are retained in text regardless of whether they are quoted. Spaces are harmless, provided that the macro is used only in rules (because spaces are token separators. If the macro is used to define other macros, problems can arise. For example:

Dw ourhost
DH nlm.nih.gov
Dj $w.$H

Here, the text of the $w and $H macros is used to define the $j macro. The $j macro is used in the HELO SMTP command and in the Message-ID: header line. The value given to $j in this case is:

  ourhost. nlm.nih.gov
          
two        a spaces
spaces  

Here, the value of $j should contain a correctly formed, fully qualified domain name. The unwanted spaces cause it to become incorrectly formed, which can cause mail to fail.

21.3.2 Required Macros (V8.6 and Earlier)

Table 21-3 shows the sendmail macro names that must (prior to V8.6) be given values in the configuration file.

Table 21-3. Required macros

Macro	§	Description	As of V8.7
$e	SmtpGreetingMessage	The SMTP greeting message	The SmtpGreetingMessage option
$j	$j	Official canonical hostname	Automatically defined
$l	UnixFromLine	Unix From format	The UnixFromLine option
$n	$n	Name used for error messages	Automatically defined
$o	OperatorChars	Delimiter operator characters	The OperatorChars option
$q	$q	Format of the sender's address	No longer used

Each macro is described at the end of this chapter in Section 21.9. Prior to V8.7, failure to define a required macro could have resulted in unpredictable problems. Beginning with V8.7 sendmail, no macros are required. Some are predefined^[4] for you by sendmail, and others have become options.

^[4] But you still might need to declare an occasional macro in your configuration file to solve unusual problems.