diff options
Diffstat (limited to 'contrib/sendmail/doc/op/op.me')
| -rw-r--r-- | contrib/sendmail/doc/op/op.me | 8226 |
1 files changed, 8226 insertions, 0 deletions
diff --git a/contrib/sendmail/doc/op/op.me b/contrib/sendmail/doc/op/op.me new file mode 100644 index 0000000..fc3290e --- /dev/null +++ b/contrib/sendmail/doc/op/op.me @@ -0,0 +1,8226 @@ +.\" Copyright (c) 1998 Sendmail, Inc. All rights reserved. +.\" Copyright (c) 1983, 1995 Eric P. Allman. All rights reserved. +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" By using this file, you agree to the terms and conditions set +.\" forth in the LICENSE file which can be found at the top level of +.\" the sendmail distribution. +.\" +.\" +.\" @(#)op.me 8.129 (Berkeley) 6/29/98 +.\" +.\" eqn op.me | pic | troff -me +.eh 'SMM:08-%''Sendmail Installation and Operation Guide' +.oh 'Sendmail Installation and Operation Guide''SMM:08-%' +.\" SD is lib if sendmail is installed in /usr/lib, sbin if in /usr/sbin +.ds SD sbin +.\" SB is bin if newaliases/mailq are installed in /usr/bin, ucb if in /usr/ucb +.ds SB bin +.nr si 3n +.de $0 +.(x +.in \\$3u*3n +.ti -3n +\\$2. \\$1 +.)x +.. +.de $C +.(x +.in 0 +\\$1 \\$2. \\$3 +.)x +.. +.sc +.+c +.(l C +.sz 16 +.b SENDMAIL\u\s-6TM\s0\d +.sz 12 +.sp +.b "INSTALLATION AND OPERATION GUIDE" +.sz 10 +.sp +.r +Eric Allman +Sendmail, Inc. +eric@Sendmail.COM +.sp +Version 8.129 +.sp +For Sendmail Version 8.9 +.)l +.(f +Sendmail is a trademark of Sendmail, Inc. +.)f +.sp 2 +.pp +.i Sendmail \u\s-2TM\s0\d +implements a general purpose internetwork mail routing facility +under the UNIX\(rg +operating system. +It is not tied to any one transport protocol \*- +its function may be likened to a crossbar switch, +relaying messages from one domain into another. +In the process, +it can do a limited amount of message header editing +to put the message into a format that is appropriate +for the receiving domain. +All of this is done under the control of a configuration file. +.pp +Due to the requirements of flexibility +for +.i sendmail , +the configuration file can seem somewhat unapproachable. +However, there are only a few basic configurations +for most sites, +for which standard configuration files have been supplied. +Most other configurations +can be built by adjusting an existing configuration file +incrementally. +.pp +.i Sendmail +is based on +RFC821 (Simple Mail Transport Protocol), +RFC822 (Internet Mail Headers Format), +RFC1123 (Internet Host Requirements), +RFC2045 (MIME), +RFC1869 (SMTP Service Extensions), +RFC1652 (SMTP 8BITMIME Extension), +RFC1870 (SMTP SIZE Extension), +RFC1891 (SMTP Delivery Status Notifications), +RFC1892 (Multipart/Report), +RFC1893 (Mail System Status Codes), +RFC1894 (Delivery Status Notifications), +RFC1985 (SMTP Service Extension for Remote Message Queue Starting), +and +RFC2033 (Local Message Transmission Protocol). +However, since +.i sendmail +is designed to work in a wider world, +in many cases it can be configured to exceed these protocols. +These cases are described herein. +.pp +Although +.i sendmail +is intended to run +without the need for monitoring, +it has a number of features +that may be used to monitor or adjust the operation +under unusual circumstances. +These features are described. +.pp +Section one describes how to do a basic +.i sendmail +installation. +Section two +explains the day-to-day information you should know +to maintain your mail system. +If you have a relatively normal site, +these two sections should contain sufficient information +for you to install +.i sendmail +and keep it happy. +Section three +describes some parameters that may be safely tweaked. +Section four +has information regarding the command line arguments. +Section five +contains the nitty-gritty information about the configuration +file. +This section is for masochists +and people who must write their own configuration file. +Section six +describes configuration that can be done at compile time. +The appendixes give a brief +but detailed explanation of a number of features +not described in the rest of the paper. +.pp +.\"XXX +.b DISCLAIMER: +This documentation is under modification. +.bp +.rs +.sp |4i +.ce 2 +This page intentionally left blank; +replace it with a blank sheet for double-sided output. +.bp 7 +.sh 1 "BASIC INSTALLATION" +.pp +There are two basic steps to installing +.i sendmail . +First, you have to compile and install the binary. +If +.i sendmail +has already been ported to your operating system +that should be simple. +Second, you must build a run-time configuration file. +This is a file that +.i sendmail +reads when it starts up +that describes the mailers it knows about, +how to parse addresses, +how to rewrite the message header, +and the settings of various options. +Although the configuration file can be quite complex, +a configuration can usually be built +using an M4-based configuration language. +.pp +The remainder of this section will describe the installation of +.i sendmail +assuming you can use one of the existing configurations +and that the standard installation parameters are acceptable. +All pathnames and examples +are given from the root of the +.i sendmail +subtree, +normally +.i /usr/src/usr.\*(SD/sendmail +on 4.4BSD. +.pp +If you are loading this off the tape, +continue with the next section. +If you have a running binary already on your system, +you should probably skip to section 1.2. +.sh 2 "Compiling Sendmail" +.pp +All +.i sendmail +source is in the +.i src +subdirectory. +To compile sendmail, +.q cd +into the +.i src +directory and type +.(b +\&./Build +.)b +This will leave the binary in an appropriately named subdirectory, +e.g., +obj.BSD-OS.2.1.i386. +It works for multiple object versions +compiled out of the same directory. +.sh 3 "Tweaking the Build Invocation" +.pp +You can give parameters on the +.i Build +command. +In most cases these are only used when the +.i obj.* +directory is first created. +These commands include: +.nr ii 0.5i +.ip "\-L \fIlibdirs\fP" +A list of directories to search for libraries. +.ip "\-I \fIincdirs\fP" +A list of directories to search for include files. +.ip "\-E \fIenvar\fP=\fIvalue\fP" +Set an environment variable to an indicated +.i value +before compiling. +This is normally used to set an ABI on Irix. +.ip "\-c" +Create a new +.i obj.* +tree before running. +.ip "\-f \fIsiteconfig\fP" +Read the indicated site configuration file. +If this parameter is not specified, +.i Build +includes +.i all +of the files +.i $BUILDTOOLS/Site/site.$oscf.m4 +and +.i $BUILDTOOLS/Site/site.config.m4 , +where $BUILDTOOLS is normally +.i \&../BuildTools +and $oscf is the same name as used on the +.i obj.* +directory. +See below for a description of the site configuration file. +.ip "\-S" +Skip auto-configuration. +.i Build +will avoid auto-detecting libraries if this is set. +All libraries and map definitions must be specified +in the site configuration file. +.lp +Any other parameters are passed to the +.i make +program. +.sh 3 "Creating a Site Configuration File" +.\"XXX +.pp +(This section is not yet complete. +For now, see the file BuildTools/README for details.) +.sh 3 "Tweaking the Makefile" +.pp +.b "XXX This should all be in the Site Configuration File section." +.i Sendmail +supports two different formats +for the local (on disk) version of databases, +notably the +.i aliases +database. +At least one of these should be defined if at all possible. +.nr ii 1i +.ip NDBM +The ``new DBM'' format, +available on nearly all systems around today. +This was the preferred format prior to 4.4BSD. +It allows such complex things as multiple databases +and closing a currently open database. +.ip NEWDB +The Berkeley DB package. +If you have this, use it. +It allows +long records, +multiple open databases, +real in-memory caching, +and so forth. +You can define this in conjunction with +.sm NDBM ; +if you do, +old alias databases are read, +but when a new database is created it will be in NEWDB format. +As a nasty hack, +if you have NEWDB, NDBM, and NIS defined, +and if the alias file name includes the substring +.q /yp/ , +.i sendmail +will create both new and old versions of the alias file +during a +.i newalias +command. +This is required because the Sun NIS/YP system +reads the DBM version of the alias file. +It's ugly as sin, +but it works. +.lp +If neither of these are defined, +.i sendmail +reads the alias file into memory on every invocation. +This can be slow and should be avoided. +There are also several methods for remote database access: +.ip NIS +Sun's Network Information Services (formerly YP). +.ip NISPLUS +Sun's NIS+ services. +.ip NETINFO +NeXT's NetInfo service. +.ip HESIOD +Hesiod service (from Athena). +.lp +Other compilation flags are set in conf.h +and should be predefined for you +unless you are porting to a new environment. +.sh 3 "Compilation and installation" +.pp +After making the local system configuration described above, +You should be able to compile and install the system. +The script +.q Build +is the best approach on most systems: +.(b +\&./Build +.)b +This will use +.i uname (1) +to create a custom Makefile for your environment. +.pp +If you are installing in the standard places, +you should be able to install using +.(b +\&./Build install +.)b +This should install the binary in +/usr/\*(SD +and create links from +/usr/\*(SB/newaliases +and +/usr/\*(SB/mailq +to +/usr/\*(SD/sendmail. +On 4.4BSD systems it will also format and install man pages. +.sh 2 "Configuration Files" +.pp +.i Sendmail +cannot operate without a configuration file. +The configuration defines the mail delivery mechanisms understood at this site, +how to access them, +how to forward email to remote mail systems, +and a number of tuning parameters. +This configuration file is detailed +in the later portion of this document. +.pp +The +.i sendmail +configuration can be daunting at first. +The world is complex, +and the mail configuration reflects that. +The distribution includes an m4-based configuration package +that hides a lot of the complexity. +.pp +These configuration files are simpler than old versions +largely because the world has become simpler; +in particular, +text-based host files are officially eliminated, +obviating the need to +.q hide +hosts behind a registered internet gateway. +.pp +These files also assume that most of your neighbors +use domain-based UUCP addressing; +that is, +instead of naming hosts as +.q host!user +they will use +.q host.domain!user . +The configuration files can be customized to work around this, +but it is more complex. +.pp +Our configuration files are processed by +.i m4 +to facilitate local customization; +the directory +.i cf +of the +.i sendmail +distribution directory +contains the source files. +This directory contains several subdirectories: +.nr ii 1i +.ip cf +Both site-dependent and site-independent descriptions of hosts. +These can be literal host names +(e.g., +.q ucbvax.mc ) +when the hosts are gateways +or more general descriptions +(such as +.q "generic-solaris2.mc" +as a general description of an SMTP-connected host +running Solaris 2.x. +Files ending +.b \&.mc +(``Master Configuration'') +are the input descriptions; +the output is in the corresponding +.b \&.cf +file. +The general structure of these files is described below. +.ip domain +Site-dependent subdomain descriptions. +These are tied to the way your organization wants to do addressing. +For example, +.b domain/CS.Berkeley.EDU.m4 +is our description for hosts in the CS.Berkeley.EDU subdomain. +These are referenced using the +.sm DOMAIN +.b m4 +macro in the +.b \&.mc +file. +.ip feature +Definitions of specific features that some particular host in your site +might want. +These are referenced using the +.sm FEATURE +.b m4 +macro. +An example feature is +use_cw_file +(which tells +.i sendmail +to read an /etc/sendmail.cw file on startup +to find the set of local names). +.ip hack +Local hacks, referenced using the +.sm HACK +.b m4 +macro. +Try to avoid these. +The point of having them here is to make it clear that they smell. +.ip m4 +Site-independent +.i m4 (1) +include files that have information common to all configuration files. +This can be thought of as a +.q #include +directory. +.ip mailer +Definitions of mailers, +referenced using the +.sm MAILER +.b m4 +macro. +The mailer types that are known in this distribution are +fax, +local, +smtp, +uucp, +and usenet. +For example, to include support for the UUCP-based mailers, +use +.q MAILER(uucp) . +.ip ostype +Definitions describing various operating system environments +(such as the location of support files). +These are referenced using the +.sm OSTYPE +.b m4 +macro. +.ip sh +Shell files used by the +.b m4 +build process. +You shouldn't have to mess with these. +.ip siteconfig +Local UUCP connectivity information. +This directory has been supplanted by the mailertable feature; +any new configurations should use that feature to do UUCP +(and other) routing. +.pp +If you are in a new domain +(e.g., a company), +you will probably want to create a +cf/domain +file for your domain. +This consists primarily of relay definitions +and features you want enabled site-wide: +for example, Berkeley's domain definition +defines relays for +BitNET +and UUCP. +These are specific to Berkeley, +and should be fully-qualified internet-style domain names. +Please check to make certain they are reasonable for your domain. +.pp +Subdomains at Berkeley are also represented in the +cf/domain +directory. +For example, +the domain +CS.Berkeley.EDU +is the Computer Science subdomain, +EECS.Berkeley.EDU +is the Electrical Engineering and Computer Sciences subdomain, +and +S2K.Berkeley.EDU +is the Sequoia 2000 subdomain. +You will probably have to add an entry to this directory +to be appropriate for your domain. +.pp +You will have to use or create +.b \&.mc +files in the +.i cf/cf +subdirectory for your hosts. +This is detailed in the +cf/README +file. +.sh 2 "Details of Installation Files" +.pp +This subsection describes the files that +comprise the +.i sendmail +installation. +.sh 3 "/usr/\*(SD/sendmail" +.pp +The binary for +.i sendmail +is located in /usr/\*(SD\**. +.(f +\**This is usually +/usr/sbin +on 4.4BSD and newer systems; +many systems install it in +/usr/lib. +I understand it is in /usr/ucblib +on System V Release 4. +.)f +It should be setuid root. +For security reasons, +/, /usr, and /usr/\*(SD +should be owned by root, mode 755\**. +.(f +\**Some vendors ship them owned by bin; +this creates a security hole that is not actually related to +.i sendmail . +Other important directories that should have restrictive ownerships +and permissions are +/bin, /usr/bin, /etc, /usr/etc, /lib, and /usr/lib. +.)f +.sh 3 "/etc/sendmail.cf" +.pp +This is the configuration file for +.i sendmail \**. +.(f +\**Actually, the pathname varies depending on the operating system; +/etc is the preferred directory. +Some older systems install it in +.b /usr/lib/sendmail.cf , +and I've also seen it in +.b /usr/ucblib +and +.b /etc/mail . +If you want to move this file, +add -D_PATH_SENDMAILCF=\e"/file/name\e" +to the flags passed to the C compiler. +Moving this file is not recommended: +other programs and scripts know of this location. +.)f +This is the only non-library file name compiled into +.i sendmail \**. +.(f +\**The system libraries can reference other files; +in particular, system library subroutines that +.i sendmail +calls probably reference +.i /etc/passwd +and +.i /etc/resolv.conf . +.)f +.pp +The configuration file is normally created +using the distribution files described above. +If you have a particularly unusual system configuration +you may need to create a special version. +The format of this file is detailed in later sections +of this document. +.sh 3 "/usr/\*(SB/newaliases" +.pp +The +.i newaliases +command should just be a link to +.i sendmail : +.(b +rm \-f /usr/\*(SB/newaliases +ln \-s /usr/\*(SD/sendmail /usr/\*(SB/newaliases +.)b +This can be installed in whatever search path you prefer +for your system. +.sh 3 "/usr/\*(SB/hoststat" +.pp +The +.i hoststat +command should just be a link to +.i sendmail , +in a fashion similar to +.i newaliases . +This command lists the status of the last mail transaction +with all remote hosts. The +.b \-v +flag will prevent the status display from being truncated. +It functions only when the +.b HostStatusDirectory +option is set. +.sh 3 "/usr/\*(SB/purgestat" +.pp +This command is also a link to +.i sendmail . +It flushes all information that is stored in the +.b HostStatusDirectory +tree. +.sh 3 "/var/spool/mqueue" +.pp +The directory +.i /var/spool/mqueue +should be created to hold the mail queue. +This directory should be mode 700 +and owned by root. +.pp +The actual path of this directory +is defined in the +.b Q +option of the +.i sendmail.cf +file. +.sh 3 "/var/spool/mqueue/.hoststat" +.pp +This is a typical value for the +.b HostStatusDirectory +option, +containing one file per host +that this sendmail has chatted with recently. +It is normally a subdirectory of +.i mqueue . +.sh 3 "/etc/aliases*" +.pp +The system aliases are held in +.q /etc/aliases . +A sample is given in +.q lib/aliases +which includes some aliases which +.i must +be defined: +.(b +cp lib/aliases /etc/aliases +.i "edit /etc/aliases" +.)b +You should extend this file with any aliases that are apropos to your system. +.pp +Normally +.i sendmail +looks at a database version of the files, +stored either in +.q /etc/aliases.dir +and +.q /etc/aliases.pag +or +.q /etc/aliases.db +depending on which database package you are using. +The actual path of this file +is defined in the +.b AliasFile +option of the +.i sendmail.cf +file. +.sh 3 "/etc/rc or /etc/init.d/sendmail" +.pp +It will be necessary to start up the +.i sendmail +daemon when your system reboots. +This daemon performs two functions: +it listens on the SMTP socket for connections +(to receive mail from a remote system) +and it processes the queue periodically +to insure that mail gets delivered when hosts come up. +.pp +Add the following lines to +.q /etc/rc +(or +.q /etc/rc.local +as appropriate) +in the area where it is starting up the daemons +on a BSD-base system, +or on a System-V-based system +in one of the startup files, typically +.q /etc/init.d/sendmail : +.(b +if [ \-f /usr/\*(SD/sendmail \-a \-f /etc/sendmail.cf ]; then + (cd /var/spool/mqueue; rm \-f [lnx]f*) + /usr/\*(SD/sendmail \-bd \-q30m & + echo \-n ' sendmail' >/dev/console +fi +.)b +The +.q cd +and +.q rm +commands insure that all lock files have been removed; +extraneous lock files may be left around +if the system goes down in the middle of processing a message. +The line that actually invokes +.i sendmail +has two flags: +.q \-bd +causes it to listen on the SMTP port, +and +.q \-q30m +causes it to run the queue every half hour. +.pp +Some people use a more complex startup script, +removing zero length qf files and df files for which there is no qf file. +For example, see Figure 1 +for an example of a complex script which does this clean up. +.(z +.hl +#!/bin/sh +# remove zero length qf files +for qffile in qf* +do + if [ \-r $qffile ] + then + if [ ! \-s $qffile ] + then + echo \-n " <zero: $qffile>" > /dev/console + rm \-f $qffile + fi + fi +done +# rename tf files to be qf if the qf does not exist +for tffile in tf* +do + qffile=`echo $tffile | sed 's/t/q/'` + if [ \-r $tffile \-a ! \-f $qffile ] + then + echo \-n " <recovering: $tffile>" > /dev/console + mv $tffile $qffile + else + if [ \-f $tffile ] + then + echo \-n " <extra: $tffile>" > /dev/console + rm \-f $tffile + fi + fi +done +# remove df files with no corresponding qf files +for dffile in df* +do + qffile=`echo $dffile | sed 's/d/q/'` + if [ \-r $dffile \-a ! \-f $qffile ] + then + echo \-n " <incomplete: $dffile>" > /dev/console + mv $dffile `echo $dffile | sed 's/d/D/'` + fi +done +# announce files that have been saved during disaster recovery +for xffile in [A-Z]f* +do + if [ \-f $xffile ] + then + echo \-n " <panic: $xffile>" > /dev/console + fi +done +.sp +.ce +Figure 1 \(em A complex startup script +.hl +.)z +.pp +If you are not running a version of UNIX +that supports Berkeley TCP/IP, +do not include the +.b \-bd +flag. +.sh 3 "/usr/lib/sendmail.hf" +.pp +This is the help file used by the SMTP +.b HELP +command. +It should be copied from +.q lib/sendmail.hf : +.(b +cp lib/sendmail.hf /usr/lib +.)b +The actual path of this file +is defined in the +.b HelpFile +option of the +.i sendmail.cf +file. +.sh 3 "/etc/sendmail.st" +.pp +If you wish to collect statistics +about your mail traffic, +you should create the file +.q /etc/sendmail.st : +.(b +cp /dev/null /etc/sendmail.st +chmod 666 /etc/sendmail.st +.)b +This file does not grow. +It is printed with the program +.q mailstats/mailstats.c. +The actual path of this file +is defined in the +.b S +option of the +.i sendmail.cf +file. +.sh 3 "/usr/\*(SB/mailq" +.pp +If +.i sendmail +is invoked as +.q mailq, +it will simulate the +.b \-bp +flag +(i.e., +.i sendmail +will print the contents of the mail queue; +see below). +This should be a link to /usr/\*(SD/sendmail. +.sh 1 "NORMAL OPERATIONS" +.sh 2 "The System Log" +.pp +The system log is supported by the +.i syslogd \|(8) +program. +All messages from +.i sendmail +are logged under the +.sm LOG_MAIL +facility\**. +.(f +\**Except on Ultrix, +which does not support facilities in the syslog. +.)f +.sh 3 "Format" +.pp +Each line in the system log +consists of a timestamp, +the name of the machine that generated it +(for logging from several machines +over the local area network), +the word +.q sendmail: , +and a message\**. +.(f +\**This format may vary slightly if your vendor has changed +the syntax. +.)f +Most messages are a sequence of +.i name \c +=\c +.i value +pairs. +.pp +The two most common lines are logged when a message is processed. +The first logs the receipt of a message; +there will be exactly one of these per message. +Some fields may be omitted if they do not contain interesting information. +Fields are: +.ip from +The envelope sender address. +.ip size +The size of the message in bytes. +.ip class +The class (i.e., numeric precedence) of the message. +.ip pri +The initial message priority (used for queue sorting). +.ip nrcpts +The number of envelope recipients for this message +(after aliasing and forwarding). +.ip msgid +The message id of the message (from the header). +.ip proto +The protocol used to receive this message (e.g., ESMTP or UUCP) +.ip relay +The machine from which it was received. +.lp +There is also one line logged per delivery attempt +(so there can be several per message if delivery is deferred +or there are multiple recipients). +Fields are: +.ip to +A comma-separated list of the recipients to this mailer. +.ip ctladdr +The ``controlling user'', that is, the name of the user +whose credentials we use for delivery. +.ip delay +The total delay between the time this message was received +and the time it was delivered. +.ip xdelay +The amount of time needed in this delivery attempt +(normally indicative of the speed of the connection). +.ip mailer +The name of the mailer used to deliver to this recipient. +.ip relay +The name of the host that actually accepted (or rejected) this recipient. +.ip stat +The delivery status. +.lp +Not all fields are present in all messages; +for example, the relay is not listed for local deliveries. +.sh 3 "Levels" +.pp +If you have +.i syslogd \|(8) +or an equivalent installed, +you will be able to do logging. +There is a large amount of information that can be logged. +The log is arranged as a succession of levels. +At the lowest level +only extremely strange situations are logged. +At the highest level, +even the most mundane and uninteresting events +are recorded for posterity. +As a convention, +log levels under ten +are considered generally +.q useful; +log levels above 64 +are reserved for debugging purposes. +Levels from 11\-64 are reserved for verbose information +that some sites might want. +.pp +A complete description of the log levels +is given in section +.\" XREF +4.6. +.sh 2 "Dumping State" +.pp +You can ask +.i sendmail +to log a dump of the open files +and the connection cache +by sending it a +.sm SIGUSR1 +signal. +The results are logged at +.sm LOG_DEBUG +priority. +.sh 2 "The Mail Queue" +.pp +Sometimes a host cannot handle a message immediately. +For example, it may be down or overloaded, causing it to refuse connections. +The sending host is then expected to save this message in +its mail queue +and attempt to deliver it later. +.pp +Under normal conditions the mail queue will be processed transparently. +However, you may find that manual intervention is sometimes necessary. +For example, +if a major host is down for a period of time +the queue may become clogged. +Although +.i sendmail +ought to recover gracefully when the host comes up, +you may find performance unacceptably bad in the meantime. +.sh 3 "Printing the queue" +.pp +The contents of the queue can be printed +using the +.i mailq +command +(or by specifying the +.b \-bp +flag to +.i sendmail ): +.(b +mailq +.)b +This will produce a listing of the queue id's, +the size of the message, +the date the message entered the queue, +and the sender and recipients. +.sh 3 "Forcing the queue" +.pp +.i Sendmail +should run the queue automatically +at intervals. +The algorithm is to read and sort the queue, +and then to attempt to process all jobs in order. +When it attempts to run the job, +.i sendmail +first checks to see if the job is locked. +If so, it ignores the job. +.pp +There is no attempt to insure that only one queue processor +exists at any time, +since there is no guarantee that a job cannot take forever +to process +(however, +.i sendmail +does include heuristics to try to abort jobs +that are taking absurd amounts of time; +technically, this violates RFC 821, but is blessed by RFC 1123). +Due to the locking algorithm, +it is impossible for one job to freeze the entire queue. +However, +an uncooperative recipient host +or a program recipient +that never returns +can accumulate many processes in your system. +Unfortunately, +there is no completely general way to solve this. +.pp +In some cases, +you may find that a major host going down +for a couple of days +may create a prohibitively large queue. +This will result in +.i sendmail +spending an inordinate amount of time +sorting the queue. +This situation can be fixed by moving the queue to a temporary place +and creating a new queue. +The old queue can be run later when the offending host returns to service. +.pp +To do this, +it is acceptable to move the entire queue directory: +.(b +cd /var/spool +mv mqueue omqueue; mkdir mqueue; chmod 700 mqueue +.)b +You should then kill the existing daemon +(since it will still be processing in the old queue directory) +and create a new daemon. +.pp +To run the old mail queue, +run the following command: +.(b +/usr/\*(SD/sendmail \-oQ/var/spool/omqueue \-q +.)b +The +.b \-oQ +flag specifies an alternate queue directory +and the +.b \-q +flag says to just run every job in the queue. +If you have a tendency toward voyeurism, +you can use the +.b \-v +flag to watch what is going on. +.pp +When the queue is finally emptied, +you can remove the directory: +.(b +rmdir /var/spool/omqueue +.)b +.sh 2 "Disk Based Connection Information" +.pp +.i Sendmail +stores a large amount of information about each remote system it +has connected to in memory. It is now possible to preserve some +of this information on disk as well, by using the +.b HostStatusDirectory +option, so that it may be shared between several invocations of +.i sendmail . +This allows mail to be queued immediately or skipped during a queue run if +there has been a recent failure in connecting to a remote machine. +.pp +Additionally enabling +.b SingleThreadDelivery +has the added effect of single-threading mail delivery to a destination. +This can be quite helpful +if the remote machine is running an SMTP server that is easily overloaded +or cannot accept more than a single connection at a time, +but can cause some messages to be punted to a future queue run. +It also applies to +.i all +hosts, so setting this because you have one machine on site +that runs some software that is easily overrun +can cause mail to other hosts to be slowed down. +If this option is set, +you probably want to set the +.b MinQueueAge +option as well and run the queue fairly frequently; +this way jobs that are skipped because another +.i sendmail +is talking to the same host will be tried again quickly +rather than being delayed for a long time. +.pp +The disk based host information is stored in a subdirectory of the +.b mqueue +directory called +.b \&.hoststat \**. +.(f +\**This is the usual value of the +.b HostStatusDirectory +option; +it can, of course, go anywhere you like in your filesystem. +.)f +Removing this directory and its subdirectories has an effect similar to +the +.i purgestat +command and is completely safe. +The information in these directories can +be perused with the +.i hoststat +command, which will indicate the host name, the last access, and the +status of that access. +An asterisk in the left most column indicates that a +.i sendmail +process currently has the host locked for mail delivery. +.pp +The disk based connection information is treated the same way as memory based +connection information for the purpose of timeouts. +By default, information about host failures is valid for 30 minutes. +This can be adjusted with +the +.b Timeout.hoststatus +option. +.pp +The connection information stored on disk may be purged at any time +with the +.i purgestat +command or by invoking sendmail with the +.b \-bH +switch. +The connection information may be viewed with the +.i hoststat +command or by invoking sendmail with the +.b \-bh +switch. +.sh 2 "The Service Switch" +.pp +The implementation of certain system services +such as host and user name lookup +is controlled by the service switch. +If the host operating system supports such a switch +.i sendmail +will use the native version. +Ultrix, Solaris, and DEC OSF/1 are examples of such systems\**. +.(f +\**HP-UX 10 has service switch support, +but since the APIs are apparently not available in the libraries +.i sendmail +does not use the native service switch in this release. +.)f +.pp +If the underlying operating system does not support a service switch +(e.g., SunOS, HP-UX, BSD) +then +.i sendmail +will provide a stub implementation. +The +.b ServiceSwitchFile +option points to the name of a file that has the service definitions. +Each line has the name of a service +and the possible implementations of that service. +For example, the file: +.(b +hosts dns files nis +aliases files nis +.)b +will ask +.i sendmail +to look for hosts in the Domain Name System first. +If the requested host name is not found, +it tries local files, +and if that fails it tries NIS. +Similarly, +when looking for aliases +it will try the local files first +followed by NIS. +.pp +Service switches are not completely integrated. +For example, despite the fact that the host entry listed in the above example +specifies to look in NIS, +on SunOS this won't happen because the system implementation of +.i gethostbyname \|(3) +doesn't understand this. +If there is enough demand +.i sendmail +may reimplement +.i gethostbyname \|(3), +.i gethostbyaddr \|(3), +.i getpwent \|(3), +and the other system routines that would be necessary +to make this work seamlessly. +.sh 2 "The Alias Database" +.pp +After recipient addresses are read from the SMTP connection +or command line +they are parsed by ruleset 0, +which must resolve to a +{\c +.i mailer , +.i host , +.i user } +triple. +If the flags selected by the +.i mailer +include the +.b A +(aliasable) flag, +the +.i user +part of the triple is looked up as the key +(i.e., the left hand side) +into the alias database. +If there is a match, the address is deleted from the send queue +and all addresses on the right hand side of the alias +are added in place of the alias that was found. +This is a recursive operation, +so aliases found in the right hand side of the alias +are similarly expanded. +.pp +The alias database exists in two forms. +One is a text form, +maintained in the file +.i /etc/aliases. +The aliases are of the form +.(b +name: name1, name2, ... +.)b +Only local names may be aliased; +e.g., +.(b +eric@prep.ai.MIT.EDU: eric@CS.Berkeley.EDU +.)b +will not have the desired effect +(except on prep.ai.MIT.EDU, +and they probably don't want me)\**. +.(f +\**Actually, any mailer that has the `A' mailer flag set +will permit aliasing; +this is normally limited to the local mailer. +.)f +Aliases may be continued by starting any continuation lines +with a space or a tab. +Blank lines and lines beginning with a sharp sign +(\c +.q # ) +are comments. +.pp +The second form is processed by the +.i ndbm \|(3)\** +.(f +\**The +.i gdbm +package does not work. +.)f +or the Berkeley DB library. +This form is in the file +.i /etc/aliases.db +(if using NEWDB) +or +.i /etc/aliases.dir +and +.i /etc/aliases.pag +(if using NDBM). +This is the form that +.i sendmail +actually uses to resolve aliases. +This technique is used to improve performance. +.pp +The control of search order is actually set by the service switch. +Essentially, the entry +.(b +O AliasFile=switch:aliases +.)b +is always added as the first alias entry; +also, the first alias file name without a class +(e.g., without +.q nis: +on the front) +will be used as the name of the file for a ``files'' entry +in the aliases switch. +For example, if the configuration file contains +.(b +O AliasFile=/etc/aliases +.)b +and the service switch contains +.(b +aliases nis files nisplus +.)b +then aliases will first be searched in the NIS database, +then in /etc/aliases, +then in the NIS+ database. +.pp +You can also use +.sm NIS -based +alias files. +For example, the specification: +.(b +O AliasFile=/etc/aliases +O AliasFile=nis:mail.aliases@my.nis.domain +.)b +will first search the /etc/aliases file +and then the map named +.q mail.aliases +in +.q my.nis.domain . +Warning: if you build your own +.sm NIS -based +alias files, +be sure to provide the +.b \-l +flag to +.i makedbm (8) +to map upper case letters in the keys to lower case; +otherwise, aliases with upper case letters in their names +won't match incoming addresses. +.pp +Additional flags can be added after the colon +exactly like a +.b K +line \(em for example: +.(b +O AliasFile=nis:\-N mail.aliases@my.nis.domain +.)b +will search the appropriate NIS map and always include null bytes in the key. +Also: +.(b +O AliasFile=nis:\-f mail.aliases@my.nis.domain +.)b +will prevent sendmail from downcasing the key before the alias lookup. +.sh 3 "Rebuilding the alias database" +.pp +The +.i hash +or +.i dbm +version of the database +may be rebuilt explicitly by executing the command +.(b +newaliases +.)b +This is equivalent to giving +.i sendmail +the +.b \-bi +flag: +.(b +/usr/\*(SD/sendmail \-bi +.)b +.pp +If the +.b RebuildAliases +(old +.b D ) +option is specified in the configuration, +.i sendmail +will rebuild the alias database automatically +if possible +when it is out of date. +Auto-rebuild can be dangerous +on heavily loaded machines +with large alias files; +if it might take more than the rebuild timeout +(option +.b AliasWait , +old +.b a , +which is normally five minutes) +to rebuild the database, +there is a chance that several processes will start the rebuild process +simultaneously. +.pp +If you have multiple aliases databases specified, +the +.b \-bi +flag rebuilds all the database types it understands +(for example, it can rebuild NDBM databases but not NIS databases). +.sh 3 "Potential problems" +.pp +There are a number of problems that can occur +with the alias database. +They all result from a +.i sendmail +process accessing the DBM version +while it is only partially built. +This can happen under two circumstances: +One process accesses the database +while another process is rebuilding it, +or the process rebuilding the database dies +(due to being killed or a system crash) +before completing the rebuild. +.pp +Sendmail has three techniques to try to relieve these problems. +First, it ignores interrupts while rebuilding the database; +this avoids the problem of someone aborting the process +leaving a partially rebuilt database. +Second, +it locks the database source file during the rebuild \(em +but that may not work over NFS or if the file is unwritable. +Third, +at the end of the rebuild +it adds an alias of the form +.(b +@: @ +.)b +(which is not normally legal). +Before +.i sendmail +will access the database, +it checks to insure that this entry exists\**. +.(f +\**The +.b AliasWait +option is required in the configuration +for this action to occur. +This should normally be specified. +.)f +.sh 3 "List owners" +.pp +If an error occurs on sending to a certain address, +say +.q \fIx\fP , +.i sendmail +will look for an alias +of the form +.q owner-\fIx\fP +to receive the errors. +This is typically useful +for a mailing list +where the submitter of the list +has no control over the maintenance of the list itself; +in this case the list maintainer would be the owner of the list. +For example: +.(b +unix-wizards: eric@ucbarpa, wnj@monet, nosuchuser, + sam@matisse +owner-unix-wizards: unix-wizards-request +unix-wizards-request: eric@ucbarpa +.)b +would cause +.q eric@ucbarpa +to get the error that will occur +when someone sends to +unix-wizards +due to the inclusion of +.q nosuchuser +on the list. +.pp +List owners also cause the envelope sender address to be modified. +The contents of the owner alias are used if they point to a single user, +otherwise the name of the alias itself is used. +For this reason, and to obey Internet conventions, +the +.q owner- +address normally points at the +.q -request +address; this causes messages to go out with the typical Internet convention +of using ``\c +.i list -request'' +as the return address. +.sh 2 "User Information Database" +.pp +If you have a version of +.i sendmail +with the user information database +compiled in, +and you have specified one or more databases using the +.b U +option, +the databases will be searched for a +.i user :maildrop +entry. +If found, the mail will be sent to the specified address. +.sh 2 "Per-User Forwarding (.forward Files)" +.pp +As an alternative to the alias database, +any user may put a file with the name +.q .forward +in his or her home directory. +If this file exists, +.i sendmail +redirects mail for that user +to the list of addresses listed in the .forward file. +For example, if the home directory for user +.q mckusick +has a .forward file with contents: +.(b +mckusick@ernie +kirk@calder +.)b +then any mail arriving for +.q mckusick +will be redirected to the specified accounts. +.pp +Actually, the configuration file defines a sequence of filenames to check. +By default, this is the user's .forward file, +but can be defined to be more generally using the +.b ForwardPath +option. +If you change this, +you will have to inform your user base of the change; +\&.forward is pretty well incorporated into the collective subconscious. +.sh 2 "Special Header Lines" +.pp +Several header lines have special interpretations +defined by the configuration file. +Others have interpretations built into +.i sendmail +that cannot be changed without changing the code. +These builtins are described here. +.sh 3 "Errors-To:" +.pp +If errors occur anywhere during processing, +this header will cause error messages to go to +the listed addresses. +This is intended for mailing lists. +.pp +The Errors-To: header was created in the bad old days +when UUCP didn't understand the distinction between an envelope and a header; +this was a hack to provide what should now be passed +as the envelope sender address. +It should go away. +It is only used if the +.b UseErrorsTo +option is set. +.pp +The Errors-To: header is officially deprecated +and will go away in a future release. +.sh 3 "Apparently-To:" +.pp +RFC 822 requires at least one recipient field +(To:, Cc:, or Bcc: line) +in every message. +If a message comes in with no recipients listed in the message +then +.i sendmail +will adjust the header based on the +.q NoRecipientAction +option. +One of the possible actions is to add an +.q "Apparently-To:" +header line for any recipients it is aware of. +.pp +The Apparently-To: header is non-standard +and is deprecated. +.sh 3 "Precedence" +.pp +The Precedence: header can be used as a crude control of message priority. +It tweaks the sort order in the queue +and can be configured to change the message timeout values. +.sh 2 "IDENT Protocol Support" +.pp +.i Sendmail +supports the IDENT protocol as defined in RFC 1413. +Although this enhances identification +of the author of an email message +by doing a ``call back'' to the originating system to include +the owner of a particular TCP connection +in the audit trail +it is in no sense perfect; +a determined forger can easily spoof the IDENT protocol. +The following description is excerpted from RFC 1413: +.ba +5 +.lp +6. Security Considerations +.lp +The information returned by this protocol is at most as trustworthy +as the host providing it OR the organization operating the host. For +example, a PC in an open lab has few if any controls on it to prevent +a user from having this protocol return any identifier the user +wants. Likewise, if the host has been compromised the information +returned may be completely erroneous and misleading. +.lp +The Identification Protocol is not intended as an authorization or +access control protocol. At best, it provides some additional +auditing information with respect to TCP connections. At worst, it +can provide misleading, incorrect, or maliciously incorrect +information. +.lp +The use of the information returned by this protocol for other than +auditing is strongly discouraged. Specifically, using Identification +Protocol information to make access control decisions - either as the +primary method (i.e., no other checks) or as an adjunct to other +methods may result in a weakening of normal host security. +.lp +An Identification server may reveal information about users, +entities, objects or processes which might normally be considered +private. An Identification server provides service which is a rough +analog of the CallerID services provided by some phone companies and +many of the same privacy considerations and arguments that apply to +the CallerID service apply to Identification. If you wouldn't run a +"finger" server due to privacy considerations you may not want to run +this protocol. +.ba +.lp +In some cases your system may not work properly with IDENT support +due to a bug in the TCP/IP implementation. +The symptoms will be that for some hosts +the SMTP connection will be closed +almost immediately. +If this is true or if you do not want to use IDENT, +you should set the IDENT timeout to zero; +this will disable the IDENT protocol. +.sh 1 "ARGUMENTS" +.pp +The complete list of arguments to +.i sendmail +is described in detail in Appendix A. +Some important arguments are described here. +.sh 2 "Queue Interval" +.pp +The amount of time between forking a process +to run through the queue +is defined by the +.b \-q +flag. +If you run with delivery mode set to +.b i +or +.b b +this can be relatively large, +since it will only be relevant +when a host that was down comes back up. +If you run in +.b q +mode +it should be relatively short, +since it defines the maximum amount of time that a message +may sit in the queue. +(See also the MinQueueAge option.) +.pp +RFC 1123 section 5.3.1.1 says that this value should be at least 30 minutes +(although that probably doesn't make sense if you use ``queue-only'' mode). +.sh 2 "Daemon Mode" +.pp +If you allow incoming mail over an IPC connection, +you should have a daemon running. +This should be set by your +.i /etc/rc +file using the +.b \-bd +flag. +The +.b \-bd +flag and the +.b \-q +flag may be combined in one call: +.(b +/usr/\*(SD/sendmail \-bd \-q30m +.)b +.pp +An alternative approach is to invoke sendmail from +.i inetd (8) +(use the +.b \-bs +flag to ask sendmail to speak SMTP on its standard input and output). +This works and allows you to wrap +.i sendmail +in a TCP wrapper program, +but may be a bit slower since the configuration file +has to be re-read on every message that comes in. +If you do this, you still need to have a +.i sendmail +running to flush the queue: +.(b +/usr/\*(SD/sendmail \-q30m +.)b +.sh 2 "Forcing the Queue" +.pp +In some cases you may find that the queue has gotten clogged for some reason. +You can force a queue run +using the +.b \-q +flag (with no value). +It is entertaining to use the +.b \-v +flag (verbose) +when this is done to watch what happens: +.(b +/usr/\*(SD/sendmail \-q \-v +.)b +.pp +You can also limit the jobs to those with a particular queue identifier, +sender, or recipient +using one of the queue modifiers. +For example, +.q \-qRberkeley +restricts the queue run to jobs that have the string +.q berkeley +somewhere in one of the recipient addresses. +Similarly, +.q \-qSstring +limits the run to particular senders and +.q \-qIstring +limits it to particular queue identifiers. +.sh 2 "Debugging" +.pp +There are a fairly large number of debug flags +built into +.i sendmail . +Each debug flag has a number and a level, +where higher levels means to print out more information. +The convention is that levels greater than nine are +.q absurd, +i.e., +they print out so much information that you wouldn't normally +want to see them except for debugging that particular piece of code. +Debug flags are set using the +.b \-d +option; +the syntax is: +.(b +.ta \w'debug-option 'u +debug-flag: \fB\-d\fP debug-list +debug-list: debug-option [ , debug-option ]* +debug-option: debug-range [ . debug-level ] +debug-range: integer | integer \- integer +debug-level: integer +.)b +where spaces are for reading ease only. +For example, +.(b +\-d12 Set flag 12 to level 1 +\-d12.3 Set flag 12 to level 3 +\-d3\-17 Set flags 3 through 17 to level 1 +\-d3\-17.4 Set flags 3 through 17 to level 4 +.)b +For a complete list of the available debug flags +you will have to look at the code +(they are too dynamic to keep this documentation up to date). +.sh 2 "Changing the Values of Options" +.pp +Options can be overridden using the +.b \-o +or +.b \-O +command line flags. +For example, +.(b +/usr/\*(SD/sendmail \-oT2m +.)b +sets the +.b T +(timeout) option to two minutes +for this run only; +the equivalent line using the long option name is +.(b +/usr/\*(SD/sendmail -OTimeout.queuereturn=2m +.)b +.pp +Some options have security implications. +Sendmail allows you to set these, +but relinquishes its setuid root permissions thereafter\**. +.(f +\**That is, it sets its effective uid to the real uid; +thus, if you are executing as root, +as from root's crontab file or during system startup +the root permissions will still be honored. +.)f +.sh 2 "Trying a Different Configuration File" +.pp +An alternative configuration file +can be specified using the +.b \-C +flag; for example, +.(b +/usr/\*(SD/sendmail \-Ctest.cf \-oQ/tmp/mqueue +.)b +uses the configuration file +.i test.cf +instead of the default +.i /etc/sendmail.cf. +If the +.b \-C +flag has no value +it defaults to +.i sendmail.cf +in the current directory. +.pp +.i Sendmail +gives up its setuid root permissions +when you use this flag, so it is common to use a publicly writable directory +(such as /tmp) +as the spool directory (QueueDirectory or Q option) while testing. +.sh 2 "Logging Traffic" +.pp +Many SMTP implementations do not fully implement the protocol. +For example, some personal computer based SMTPs +do not understand continuation lines in reply codes. +These can be very hard to trace. +If you suspect such a problem, you can set traffic logging using the +.b \-X +flag. +For example, +.(b +/usr/\*(SD/sendmail \-X /tmp/traffic \-bd +.)b +will log all traffic in the file +.i /tmp/traffic . +.pp +This logs a lot of data very quickly and should +.b NEVER +be used +during normal operations. +After starting up such a daemon, +force the errant implementation to send a message to your host. +All message traffic in and out of +.i sendmail , +including the incoming SMTP traffic, +will be logged in this file. +.sh 2 "Testing Configuration Files" +.pp +When you build a configuration table, +you can do a certain amount of testing +using the +.q "test mode" +of +.i sendmail . +For example, +you could invoke +.i sendmail +as: +.(b +sendmail \-bt \-Ctest.cf +.)b +which would read the configuration file +.q test.cf +and enter test mode. +In this mode, +you enter lines of the form: +.(b +rwset address +.)b +where +.i rwset +is the rewriting set you want to use +and +.i address +is an address to apply the set to. +Test mode shows you the steps it takes +as it proceeds, +finally showing you the address it ends up with. +You may use a comma separated list of rwsets +for sequential application of rules to an input. +For example: +.(b +3,1,21,4 monet:bollard +.)b +first applies ruleset three to the input +.q monet:bollard. +Ruleset one is then applied to the output of ruleset three, +followed similarly by rulesets twenty-one and four. +.pp +If you need more detail, +you can also use the +.q \-d21 +flag to turn on more debugging. +For example, +.(b +sendmail \-bt \-d21.99 +.)b +turns on an incredible amount of information; +a single word address +is probably going to print out several pages worth of information. +.pp +You should be warned that internally, +.i sendmail +applies ruleset 3 to all addresses. +In test mode +you will have to do that manually. +For example, older versions allowed you to use +.(b +0 bruce@broadcast.sony.com +.)b +This version requires that you use: +.(b +3,0 bruce@broadcast.sony.com +.)b +.pp +As of version 8.7, +some other syntaxes are available in test mode: +.bu +\&.D\|x\|value +defines macro +.i x +to have the indicated +.i value . +This is useful when debugging rules that use the +.b $& \c +.i x +syntax. +.bu +\&.C\|c\|value +adds the indicated +.i value +to class +.i c . +.bu +\&.S\|ruleset +dumps the contents of the indicated ruleset. +.bu +\-d\|debug-spec +is equivalent to the command-line flag. +.sh 2 "Persistent Host Status Information" +.pp +When +.b HostStatusDirectory +is enabled, +information about the status of hosts is maintained on disk +and can thus be shared between different instantiations of +.i sendmail . +The status of the last connection with each remote host +may be viewed with the command: +.(b +sendmail \-bh +.)b +This information may be flushed with the command: +.(b +sendmail \-bH +.)b +Flushing the information prevents new +.i sendmail +processes from loading it, +but does not prevent existing processes from using the status information +that they already have. +.sh 1 "TUNING" +.pp +There are a number of configuration parameters +you may want to change, +depending on the requirements of your site. +Most of these are set +using an option in the configuration file. +For example, +the line +.q "O Timeout.queuereturn=5d" +sets option +.q Timeout.queuereturn +to the value +.q 5d +(five days). +.pp +Most of these options have appropriate defaults for most sites. +However, +sites having very high mail loads may find they need to tune them +as appropriate for their mail load. +In particular, +sites experiencing a large number of small messages, +many of which are delivered to many recipients, +may find that they need to adjust the parameters +dealing with queue priorities. +.pp +All versions of +.i sendmail +prior to 8.7 +had single character option names. +As of 8.7, +options have long (multi-character names). +Although old short names are still accepted, +most new options do not have short equivalents. +.pp +This section only describes the options you are most likely +to want to tweak; +read section +.\"XREF +5 +for more details. +.sh 2 "Timeouts" +.pp +All time intervals are set +using a scaled syntax. +For example, +.q 10m +represents ten minutes, whereas +.q 2h30m +represents two and a half hours. +The full set of scales is: +.(b +.ta 4n +s seconds +m minutes +h hours +d days +w weeks +.)b +.sh 3 "Queue interval" +.pp +The argument to the +.b \-q +flag +specifies how often a sub-daemon will run the queue. +This is typically set to between fifteen minutes +and one hour. +RFC 1123 section 5.3.1.1 recommends that this be at least 30 minutes. +.sh 3 "Read timeouts" +.pp +Timeouts all have option names +.q Timeout.\fIsuboption\fP . +The recognized +.i suboption s, +their default values, and the minimum values +allowed by RFC 1123 section 5.3.2 are: +.nr ii 1i +.ip connect +The time to wait for an SMTP connection to open +(the +.i connect (2) +system call) +[0, unspecified]. +If zero, uses the kernel default. +In no case can this option extend the timeout +longer than the kernel provides, but it can shorten it. +This is to get around kernels that provide an absurdly long connection timeout +(90 minutes in one case). +.ip iconnect +The same as +.i connect, +except it applies only to the initial attempt to connect to a host +for a given message +[0, unspecified]. +The concept is that this should be very short (a few seconds); +hosts that are well connected and responsive will thus be serviced immediately. +Hosts that are slow will not hold up other deliveries in the initial +delivery attempt. +.ip initial +The wait for the initial 220 greeting message +[5m, 5m]. +.ip helo +The wait for a reply from a HELO or EHLO command +[5m, unspecified]. +This may require a host name lookup, so +five minutes is probably a reasonable minimum. +.ip mail\(dg +The wait for a reply from a MAIL command +[10m, 5m]. +.ip rcpt\(dg +The wait for a reply from a RCPT command +[1h, 5m]. +This should be long +because it could be pointing at a list +that takes a long time to expand +(see below). +.ip datainit\(dg +The wait for a reply from a DATA command +[5m, 2m]. +.ip datablock\(dg +The wait for reading a data block +(that is, the body of the message). +[1h, 3m]. +This should be long because it also applies to programs +piping input to +.i sendmail +which have no guarantee of promptness. +.ip datafinal\(dg +The wait for a reply from the dot terminating a message. +[1h, 10m]. +If this is shorter than the time actually needed +for the receiver to deliver the message, +duplicates will be generated. +This is discussed in RFC 1047. +.ip rset +The wait for a reply from a RSET command +[5m, unspecified]. +.ip quit +The wait for a reply from a QUIT command +[2m, unspecified]. +.ip misc +The wait for a reply from miscellaneous (but short) commands +such as NOOP (no-operation) and VERB (go into verbose mode). +[2m, unspecified]. +.ip command\(dg +In server SMTP, +the time to wait for another command. +[1h, 5m]. +.ip ident +The timeout waiting for a reply to an IDENT query +[30s\**, unspecified]. +.(f +\**On some systems the default is zero to turn the protocol off entirely. +.)f +.ip hoststatus +How long status information about a host +(e.g., host down) +will be cached before it is considered stale +[30m, unspecified]. +.lp +For compatibility with old configuration files, +if no +.i suboption +is specified, +all the timeouts marked with \(dg are set to the indicated value. +.pp +Many of the RFC 1123 minimum values +may well be too short. +.i Sendmail +was designed to the RFC 822 protocols, +which did not specify read timeouts; +hence, versions of +.i sendmail +prior to version 8.1 did not guarantee to reply to messages promptly. +In particular, a +.q RCPT +command specifying a mailing list +will expand and verify the entire list; +a large list on a slow system +may easily take more than five minutes\**. +.(f +\**This verification includes looking up every address +with the name server; +this involves network delays, +and can in some cases can be considerable. +.)f +I recommend a one hour timeout \*- +since a communications failure during the RCPT phase is rare, +a long timeout is not onerous +and may ultimately help reduce network load +and duplicated messages. +.pp +For example, the lines: +.(b +O Timeout.command=25m +O Timeout.datablock=3h +.)b +sets the server SMTP command timeout to 25 minutes +and the input data block timeout to three hours. +.sh 3 "Message timeouts" +.pp +After sitting in the queue for a few days, +a message will time out. +This is to insure that at least the sender is aware +of the inability to send a message. +The timeout is typically set to five days. +It is sometimes considered convenient to also send a warning message +if the message is in the queue longer than a few hours +(assuming you normally have good connectivity; +if your messages normally took several hours to send +you wouldn't want to do this because it wouldn't be an unusual event). +These timeouts are set using the +.b Timeout.queuereturn +and +.b Timeout.queuewarn +options in the configuration file +(previously both were set using the +.b T +option). +.pp +Since these options are global, +and since you can not know +.i "a priori" +how long another host outside your domain will be down, +a five day timeout is recommended. +This allows a recipient to fix the problem even if it occurs +at the beginning of a long weekend. +RFC 1123 section 5.3.1.1 says that this parameter +should be ``at least 4\-5 days''. +.pp +The +.b Timeout.queuewarn +value can be piggybacked on the +.b T +option by indicating a time after which +a warning message should be sent; +the two timeouts are separated by a slash. +For example, the line +.(b +OT5d/4h +.)b +causes email to fail after five days, +but a warning message will be sent after four hours. +This should be large enough that the message will have been tried +several times. +.sh 2 "Forking During Queue Runs" +.pp +By setting the +.b ForkEachJob +(\c +.b Y ) +option, +.i sendmail +will fork before each individual message +while running the queue. +This will prevent +.i sendmail +from consuming large amounts of memory, +so it may be useful in memory-poor environments. +However, if the +.b ForkEachJob +option is not set, +.i sendmail +will keep track of hosts that are down during a queue run, +which can improve performance dramatically. +.pp +If the +.b ForkEachJob +option is set, +.i sendmail +can not use connection caching. +.sh 2 "Queue Priorities" +.pp +Every message is assigned a priority when it is first instantiated, +consisting of the message size (in bytes) +offset by the message class +(which is determined from the Precedence: header) +times the +.q "work class factor" +and the number of recipients times the +.q "work recipient factor." +The priority is used to order the queue. +Higher numbers for the priority mean that the message will be processed later +when running the queue. +.pp +The message size is included so that large messages are penalized +relative to small messages. +The message class allows users to send +.q "high priority" +messages by including a +.q Precedence: +field in their message; +the value of this field is looked up in the +.b P +lines of the configuration file. +Since the number of recipients affects the amount of load a message presents +to the system, +this is also included into the priority. +.pp +The recipient and class factors +can be set in the configuration file using the +.b RecipientFactor +(\c +.b y ) +and +.b ClassFactor +(\c +.b z ) +options respectively. +They default to 30000 (for the recipient factor) +and 1800 +(for the class factor). +The initial priority is: +.EQ +pri = msgsize - (class times bold ClassFactor) + (nrcpt times bold RecipientFactor) +.EN +(Remember, higher values for this parameter actually mean +that the job will be treated with lower priority.) +.pp +The priority of a job can also be adjusted each time it is processed +(that is, each time an attempt is made to deliver it) +using the +.q "work time factor," +set by the +.b RetryFactor +(\c +.b Z ) +option. +This is added to the priority, +so it normally decreases the precedence of the job, +on the grounds that jobs that have failed many times +will tend to fail again in the future. +The +.b RetryFactor +option defaults to 90000. +.sh 2 "Load Limiting" +.pp +.i Sendmail +can be asked to queue (but not deliver) +mail if the system load average gets too high +using the +.b QueueLA +(\c +.b x ) +option. +When the load average exceeds the value of the +.b QueueLA +option, +the delivery mode is set to +.b q +(queue only) +if the +.b QueueFactor +(\c +.b q ) +option divided by the difference in the current load average and the +.b QueueLA +option +plus one +exceeds the priority of the message \(em +that is, the message is queued iff: +.EQ +pri > { bold QueueFactor } over { LA - { bold QueueLA } + 1 } +.EN +The +.b QueueFactor +option defaults to 600000, +so each point of load average is worth 600000 +priority points +(as described above). +.pp +For drastic cases, +the +.b RefuseLA +(\c +.b X ) +option defines a load average at which +.i sendmail +will refuse +to accept network connections. +Locally generated mail +(including incoming UUCP mail) +is still accepted. +.sh 2 "Delivery Mode" +.pp +There are a number of delivery modes that +.i sendmail +can operate in, +set by the +.b DeliveryMode +(\c +.b d ) +configuration option. +These modes +specify how quickly mail will be delivered. +Legal modes are: +.(b +.ta 4n +i deliver interactively (synchronously) +b deliver in background (asynchronously) +q queue only (don't deliver) +d defer delvery attempts (don't deliver) +.)b +There are tradeoffs. +Mode +.q i +gives the sender the quickest feedback, +but may slow down some mailers and +is hardly ever necessary. +Mode +.q b +delivers promptly but +can cause large numbers of processes +if you have a mailer that takes a long time to deliver a message. +Mode +.q q +minimizes the load on your machine, +but means that delivery may be delayed for up to the queue interval. +Mode +.q d +is identical to mode +.q q +except that it also prevents all the early map lookups from working; +it is intended for ``dial on demand'' sites where DNS lookups +might cost real money. +Some simple error messages +(e.g., host unknown during the SMTP protocol) +will be delayed using this mode. +Mode +.q b +is the usual default. +.pp +If you run in mode +.q q +(queue only), +.q d +(defer), +or +.q b +(deliver in background) +.i sendmail +will not expand aliases and follow .forward files +upon initial receipt of the mail. +This speeds up the response to RCPT commands. +Mode +.q i +cannot be used by the SMTP server. +.sh 2 "Log Level" +.pp +The level of logging can be set for +.i sendmail . +The default using a standard configuration table is level 9. +The levels are as follows: +.nr ii 0.5i +.ip 0 +Minimal logging. +.ip 1 +Serious system failures and potential security problems. +.ip 2 +Lost communications (network problems) and protocol failures. +.ip 3 +Other serious failures, malformed addresses, transient forward/include +errors, connection timeouts. +.ip 4 +Minor failures, out of date alias databases, connection rejections +via check_ rulesets. +.ip 5 +Message collection statistics. +.ip 6 +Creation of error messages, +VRFY and EXPN commands. +.ip 7 +Delivery failures (host or user unknown, etc.). +.ip 8 +Successful deliveries and alias database rebuilds. +.ip 9 +Messages being deferred +(due to a host being down, etc.). +.ip 10 +Database expansion (alias, forward, and userdb lookups). +.ip 11 +NIS errors and end of job processing. +.ip 12 +Logs all SMTP connections. +.ip 13 +Log bad user shells, files with improper permissions, and other +questionable situations. +.ip 14 +Logs refused connections. +.ip 15 +Log all incoming and outgoing SMTP commands. +.ip 20 +Logs attempts to run locked queue files. +These are not errors, +but can be useful to note if your queue appears to be clogged. +.ip 30 +Lost locks (only if using lockf instead of flock). +.lp +Additionally, +values above 64 are reserved for extremely verbose debugging output. +No normal site would ever set these. +.sh 2 "File Modes" +.pp +The modes used for files depend on what functionality you want +and the level of security you require. +In many cases +.i sendmail +does careful checking of the modes +of files and directories +to avoid accidental compromise; +if you want to make it possible to have group-writable support files +you may need to use the +.b DontBlameSendmail +option to turn off some of these checks. +.sh 3 "To suid or not to suid?" +.pp +.i Sendmail +is normally installed +setuid to root. +At the point where it is about to +.i exec \|(2) +a mailer, +it checks to see if the userid is zero (root); +if so, +it resets the userid and groupid to a default +(set by the +.b U= +equate in the mailer line; +if that is not set, the +.b DefaultUser +option is used). +This can be overridden +by setting the +.b S +flag to the mailer +for mailers that are trusted +and must be called as root. +However, +this will cause mail processing +to be accounted +(using +.i sa \|(8)) +to root +rather than to the user sending the mail. +.pp +If you don't make +.i sendmail +setuid to root, it will still run but you lose a lot of functionality +and a lot of privacy, since you'll have to make the queue directory +world readable. +You could also make +.i sendmail +setuid to some pseudo-user +(e.g., create a user called +.q sendmail +and make +.i sendmail +setuid to that) +which will fix the privacy problems +but not the functionality issues. +Also, this isn't a guarantee of security: +for example, +root occasionally sends mail, +and the daemon often runs as root. +Note however that +.i sendmail +must run as root in order to create the SMTP listener socket. +.pp +A middle ground is to make +.i sendmail +setuid to root, +but set the +.b RunAsUser +option. +This causes +.i sendmail +to become the indicated user as soon as it has done the startup +that requires root privileges +(primarily, opening the +.sm SMTP +socket). +If you use +.b RunAsUser , +the queue directory +(normally +.i /var/spool/mqueue ) +should be owned by that user, +and all files and databases +(including user +.i \&.forward +files, +alias files, +:include: files, +and external databases) +must be readable by that user. +.b RunAsUser +is probably best suited for firewall configurations +that don't have regular user logins. +.sh 3 "Turning off security checks" +.pp +.i Sendmail +is very particular about the modes of files that it reads or writes. +For example, by default it will refuse to read most files +that are group writable +on the grounds that they might have been tampered with +by someone other than the owner; +it will even refuse to read files in group writable directories. +.pp +If you are +.i quite +sure that your configuration is safe and you want +.i sendmail +to avoid these security checks, +you can turn off certain checks using the +.b DontBlameSendmail +option. +This option takes one or more names that disable checks. +In the descriptions that follow, +.q "unsafe directory" +means a directory that is writable by anyone other than the owner. +The values are: +.nr ii 0.5i +.ip Safe +No special handling. +.ip AssumeSafeChown +Assume that the +.i chown +system call is restricted to root. +Since some versions of Unix permit regular users +to give away their files to other users on some filesystems, +.i sendmail +often cannot assume that a given file was created by the owner, +particularly when it is in a writable directory. +You can set this flag if you know that file giveaway is restricted +on your system. +.ip ClassFileInUnsafeDirPath +When reading class files (using the +.b F +line in the configuration file), +allow files that are in unsafe directories. +.ip ErrorHeaderInUnsafeDirPath +Allow the file named in the +.b ErrorHeader +option to be in an unsafe directory. +.ip GroupWritableDirPathSafe +Change the definition of +.q "unsafe directory" +to consider group-writable directories to be safe. +World-writable directories are always unsafe. +.ip GroupWritableForwardFileSafe +Accept group-writable +.i \&.forward +files. +.ip GroupWritableIncludeFileSafe +Accept group-writable +.i :include: +files. +.ip GroupWritableAliasFile +Allow group-writable alias files. +.ip HelpFileInUnsafeDirPath +Allow the file named in the +.b HelpFile +option to be in an unsafe directory. +.ip WorldWritableAliasFile +Accept world-writable alias files. +.ip ForwardFileInGroupWritableDirPath +Allow +.i \&.forward +files in group writable directories. +.ip IncludeFileInGroupWritableDirPath +Allow +.i :include: +files in group writable directories. +.ip ForwardFileInUnsafeDirPath +Allow +.i \&.forward +files in unsafe directories. +.ip IncludeFileInUnsafeDirPath +Allow +.i :include: +files in unsafe directories. +.ip ForwardFileInUnsafeDirPathSafe +Allow a +.i \&.forward +file that is in an unsafe directory to include references +to program and files. +.ip IncludeFileInUnsafeDirPathSafe +Allow a +.i :include: +file that is in an unsafe directory to include references +to program and files. +.ip MapInUnsafeDirPath +Allow maps (e.g., +.i hash , +.i btree , +and +.i dbm +files) +in unsafe directories. +.ip LinkedAliasFileInWritableDir +Allow an alias file that is a link in a writable directory. +.ip LinkedClassFileInWritableDir +Allow class files that are links in writable directories. +.ip LinkedForwardFileInWritableDir +Allow +.i \&.forward +files that are links in writable directories. +.ip LinkedIncludeFileInWritableDir +Allow +.i :include: +files that are links in writable directories. +.ip LinkedMapInWritableDir +Allow map files that are links in writable directories. +.ip LinkedServiceSwitchFileInWritableDir +Allow the service switch file to be a link +even if the directory is writable. +.ip FileDeliveryToHardLink +Allow delivery to files that are hard links. +.ip FileDeliveryToSymLink +Allow delivery to files that are symbolic links. +.ip RunProgramInUnsafeDirPath +Go ahead and run programs that are in writable directories. +.ip RunWritableProgram +Go ahead and run programs that are group- or world-writable. +.ip WriteMapToHardLink +Allow writes to maps that are hard links. +.ip WriteMapToSymLink +Allow writes to maps that are symbolic links. +.ip WriteStatsToHardLink +Allow the status file to be a hard link. +.ip WriteStatsToSymLink +Allow the status file to be a symbolic link. +.sh 2 "Connection Caching" +.pp +When processing the queue, +.i sendmail +will try to keep the last few open connections open +to avoid startup and shutdown costs. +This only applies to IPC connections. +.pp +When trying to open a connection +the cache is first searched. +If an open connection is found, it is probed to see if it is still active +by sending a +.sm RSET +command. +It is not an error if this fails; +instead, the connection is closed and reopened. +.pp +Two parameters control the connection cache. +The +.b ConnectionCacheSize +(\c +.b k ) +option defines the number of simultaneous open connections +that will be permitted. +If it is set to zero, +connections will be closed as quickly as possible. +The default is one. +This should be set as appropriate for your system size; +it will limit the amount of system resources that +.i sendmail +will use during queue runs. +Never set this higher than 4. +.pp +The +.b ConnectionCacheTimeout +(\c +.b K ) +option specifies the maximum time that any cached connection +will be permitted to idle. +When the idle time exceeds this value +the connection is closed. +This number should be small +(under ten minutes) +to prevent you from grabbing too many resources +from other hosts. +The default is five minutes. +.sh 2 "Name Server Access" +.pp +Control of host address lookups is set by the +.b hosts +service entry in your service switch file. +If you are on a system that has built-in service switch support +(e.g., Ultrix, Solaris, or DEC OSF/1) +then your system is probably configured properly already. +Otherwise, +.i sendmail +will consult the file +.b /etc/service.switch , +which should be created. +.i Sendmail +only uses two entries: +.b hosts +and +.b aliases , +although system routines may use other services +(notably the +.b passwd +service for user name lookups by +.i getpwname ). +.pp +However, some systems (such as SunOS) +will do DNS lookups +regardless of the setting of the service switch entry. +In particular, the system routine +.i gethostbyname (3) +is used to look up host names, +and many vendor versions try some combination of DNS, NIS, +and file lookup in /etc/hosts +without consulting a service switch. +.i Sendmail +makes no attempt to work around this problem, +and the DNS lookup will be done anyway. +If you do not have a nameserver configured at all, +such as at a UUCP-only site, +.i sendmail +will get a +.q "connection refused" +message when it tries to connect to the name server. +If the +.b hosts +switch entry has the service +.q dns +listed somewhere in the list, +.i sendmail +will interpret this to mean a temporary failure +and will queue the mail for later processing; +otherwise, it ignores the name server data. +.pp +The same technique is used to decide whether to do MX lookups. +If you want MX support, you +.i must +have +.q dns +listed as a service in the +.b hosts +switch entry. +.pp +The +.b ResolverOptions +(\c +.b I ) +option allows you to tweak name server options. +The command line takes a series of flags as documented in +.i resolver (3) +(with the leading +.q RES_ +deleted). +Each can be preceded by an optional `+' or `\(mi'. +For example, the line +.(b +O ResolverOptions=+AAONLY \(miDNSRCH +.)b +turns on the AAONLY (accept authoritative answers only) +and turns off the DNSRCH (search the domain path) options. +Most resolver libraries default DNSRCH, DEFNAMES, and RECURSE +flags on and all others off. +You can also include +.q HasWildcardMX +to specify that there is a wildcard MX record matching your domain; +this turns off MX matching when canonifying names, +which can lead to inappropriate canonifications. +.pp +Version level 1 configurations +turn DNSRCH and DEFNAMES off when doing delivery lookups, +but leave them on everywhere else. +Version 8 of +.i sendmail +ignores them when doing canonification lookups +(that is, when using $[ ... $]), +and always does the search. +If you don't want to do automatic name extension, +don't call $[ ... $]. +.pp +The search rules for $[ ... $] are somewhat different than usual. +If the name being looked up +has at least one dot, it always tries the unmodified name first. +If that fails, it tries the reduced search path, +and lastly tries the unmodified name +(but only for names without a dot, +since names with a dot have already been tried). +This allows names such as +``utc.CS'' +to match the site in Czechoslovakia +rather than the site in your local Computer Science department. +It also prefers A and CNAME records over MX records \*- +that is, if it finds an MX record it makes note of it, +but keeps looking. +This way, if you have a wildcard MX record matching your domain, +it will not assume that all names match. +.pp +To completely turn off all name server access +on systems without service switch support +(such as SunOS) +you will have to recompile with +\-DNAMED_BIND=0 +and remove \-lresolv from the list of libraries to be searched +when linking. +.sh 2 "Moving the Per-User Forward Files" +.pp +Some sites mount each user's home directory +from a local disk on their workstation, +so that local access is fast. +However, the result is that .forward file lookups are slow. +In some cases, +mail can even be delivered on machines inappropriately +because of a file server being down. +The performance can be especially bad if you run the automounter. +.pp +The +.b ForwardPath +(\c +.b J ) +option allows you to set a path of forward files. +For example, the config file line +.(b +O ForwardPath=/var/forward/$u:$z/.forward.$w +.)b +would first look for a file with the same name as the user's login +in /var/forward; +if that is not found (or is inaccessible) +the file +``.forward.\c +.i machinename '' +in the user's home directory is searched. +A truly perverse site could also search by sender +by using $r, $s, or $f. +.pp +If you create a directory such as /var/forward, +it should be mode 1777 +(that is, the sticky bit should be set). +Users should create the files mode 644. +Note that you must use the +forwardfileinunsafedirpath and +forwardfileinunsafedirpathsafe +flags with the DontBlameSendmail option +to allow forward files in a world +writable directory. +.sh 2 "Free Space" +.pp +On systems that have one of the system calls in the +.i statfs (2) +family +(including +.i statvfs +and +.i ustat ), +you can specify a minimum number of free blocks on the queue filesystem +using the +.b MinFreeBlocks +(\c +.b b ) +option. +If there are fewer than the indicated number of blocks free +on the filesystem on which the queue is mounted +the SMTP server will reject mail +with the +452 error code. +This invites the SMTP client to try again later. +.pp +Beware of setting this option too high; +it can cause rejection of email +when that mail would be processed without difficulty. +.sh 2 "Maximum Message Size" +.pp +To avoid overflowing your system with a large message, +the +.b MaxMessageSize +option can be set to set an absolute limit +on the size of any one message. +This will be advertised in the ESMTP dialogue +and checked during message collection. +.sh 2 "Privacy Flags" +.pp +The +.b PrivacyOptions +(\c +.b p ) +option allows you to set certain +``privacy'' +flags. +Actually, many of them don't give you any extra privacy, +rather just insisting that client SMTP servers +use the HELO command +before using certain commands +or adding extra headers to indicate possible spoof attempts. +.pp +The option takes a series of flag names; +the final privacy is the inclusive or of those flags. +For example: +.(b +O PrivacyOptions=needmailhelo, noexpn +.)b +insists that the HELO or EHLO command be used before a MAIL command is accepted +and disables the EXPN command. +.pp +The flags are detailed in section +.\"XREF +5.6. +.sh 2 "Send to Me Too" +.pp +Normally, +.i sendmail +deletes the (envelope) sender from any list expansions. +For example, if +.q matt +sends to a list that contains +.q matt +as one of the members he won't get a copy of the message. +If the +.b \-m +(me too) +command line flag, or if the +.b MeToo +(\c +.b m ) +option is set in the configuration file, +this behaviour is suppressed. +Some sites like to run the +.sm SMTP +daemon with +.b \-m . +.sh 1 "THE WHOLE SCOOP ON THE CONFIGURATION FILE" +.pp +This section describes the configuration file +in detail. +.pp +There is one point that should be made clear immediately: +the syntax of the configuration file +is designed to be reasonably easy to parse, +since this is done every time +.i sendmail +starts up, +rather than easy for a human to read or write. +On the +.q "future project" +list is a +configuration-file compiler. +.pp +The configuration file is organized as a series of lines, +each of which begins with a single character +defining the semantics for the rest of the line. +Lines beginning with a space or a tab +are continuation lines +(although the semantics are not well defined in many places). +Blank lines and lines beginning with a sharp symbol +(`#') +are comments. +.sh 2 "R and S \*- Rewriting Rules" +.pp +The core of address parsing +are the rewriting rules. +These are an ordered production system. +.i Sendmail +scans through the set of rewriting rules +looking for a match on the left hand side +(LHS) +of the rule. +When a rule matches, +the address is replaced by the right hand side +(RHS) +of the rule. +.pp +There are several sets of rewriting rules. +Some of the rewriting sets are used internally +and must have specific semantics. +Other rewriting sets +do not have specifically assigned semantics, +and may be referenced by the mailer definitions +or by other rewriting sets. +.pp +The syntax of these two commands are: +.(b F +.b S \c +.i n +.)b +Sets the current ruleset being collected to +.i n . +If you begin a ruleset more than once +it appends to the old definition. +.(b F +.b R \c +.i lhs +.i rhs +.i comments +.)b +The +fields must be separated +by at least one tab character; +there may be embedded spaces +in the fields. +The +.i lhs +is a pattern that is applied to the input. +If it matches, +the input is rewritten to the +.i rhs . +The +.i comments +are ignored. +.pp +Macro expansions of the form +.b $ \c +.i x +are performed when the configuration file is read. +Expansions of the form +.b $& \c +.i x +are performed at run time using a somewhat less general algorithm. +This is intended only for referencing internally defined macros +such as +.b $h +that are changed at runtime. +.sh 3 "The left hand side" +.pp +The left hand side of rewriting rules contains a pattern. +Normal words are simply matched directly. +Metasyntax is introduced using a dollar sign. +The metasymbols are: +.(b +.ta \w'\fB$=\fP\fIx\fP 'u +\fB$*\fP Match zero or more tokens +\fB$+\fP Match one or more tokens +\fB$\-\fP Match exactly one token +\fB$=\fP\fIx\fP Match any phrase in class \fIx\fP +\fB$~\fP\fIx\fP Match any word not in class \fIx\fP +.)b +If any of these match, +they are assigned to the symbol +.b $ \c +.i n +for replacement on the right hand side, +where +.i n +is the index in the LHS. +For example, +if the LHS: +.(b +$\-:$+ +.)b +is applied to the input: +.(b +UCBARPA:eric +.)b +the rule will match, and the values passed to the RHS will be: +.(b +.ta 4n +$1 UCBARPA +$2 eric +.)b +.pp +Additionally, the LHS can include +.b $@ +to match zero tokens. +This is +.i not +bound to a +.b $ \c +.i n +on the RHS, and is normally only used when it stands alone +in order to match the null input. +.sh 3 "The right hand side" +.pp +When the left hand side of a rewriting rule matches, +the input is deleted and replaced by the right hand side. +Tokens are copied directly from the RHS +unless they begin with a dollar sign. +Metasymbols are: +.(b +.ta \w'$#mailer\0\0\0'u +\fB$\fP\fIn\fP Substitute indefinite token \fIn\fP from LHS +\fB$[\fP\fIname\fP\fB$]\fP Canonicalize \fIname\fP +\fB$(\fP\fImap key\fP \fB$@\fP\fIarguments\fP \fB$:\fP\fIdefault\fP \fB$)\fP + Generalized keyed mapping function +\fB$>\fP\fIn\fP \*(lqCall\*(rq ruleset \fIn\fP +\fB$#\fP\fImailer\fP Resolve to \fImailer\fP +\fB$@\fP\fIhost\fP Specify \fIhost\fP +\fB$:\fP\fIuser\fP Specify \fIuser\fP +.)b +.pp +The +.b $ \c +.i n +syntax substitutes the corresponding value from a +.b $+ , +.b $\- , +.b $* , +.b $= , +or +.b $~ +match on the LHS. +It may be used anywhere. +.pp +A host name enclosed between +.b $[ +and +.b $] +is looked up in the host database(s) +and replaced by the canonical name\**. +.(f +\**This is actually +completely equivalent +to $(host \fIhostname\fP$). +In particular, a +.b $: +default can be used. +.)f +For example, +.q $[ftp$] +might become +.q ftp.CS.Berkeley.EDU +and +.q $[[128.32.130.2]$] +would become +.q vangogh.CS.Berkeley.EDU. +.i Sendmail +recognizes its numeric IP address +without calling the name server +and replaces it with its canonical name. +.pp +The +.b $( +\&... +.b $) +syntax is a more general form of lookup; +it uses a named map instead of an implicit map. +If no lookup is found, the indicated +.i default +is inserted; +if no default is specified and no lookup matches, +the value is left unchanged. +The +.i arguments +are passed to the map for possible use. +.pp +The +.b $> \c +.i n +syntax +causes the remainder of the line to be substituted as usual +and then passed as the argument to ruleset +.i n . +The final value of ruleset +.i n +then becomes +the substitution for this rule. +The +.b $> +syntax expands everything after the ruleset name +to the end of the replacement string +and then passes that as the initial input to the ruleset. +Recursive calls are allowed. +For example, +.(b +$>0 $>3 $1 +.)b +expands $1, passes that to ruleset 3, and then passes the result +of ruleset 3 to ruleset 0. +.pp +The +.b $# +syntax should +.i only +be used in ruleset zero +or a subroutine of ruleset zero. +It causes evaluation of the ruleset to terminate immediately, +and signals to +.i sendmail +that the address has completely resolved. +The complete syntax is: +.(b +\fB$#\fP\fImailer\fP \fB$@\fP\fIhost\fP \fB$:\fP\fIuser\fP +.)b +This specifies the +{mailer, host, user} +3-tuple necessary to direct the mailer. +If the mailer is local +the host part may be omitted\**. +.(f +\**You may want to use it for special +.q "per user" +extensions. +For example, in the address +.q jgm+foo@CMU.EDU ; +the +.q +foo +part is not part of the user name, +and is passed to the local mailer for local use. +.)f +The +.i mailer +must be a single word, +but the +.i host +and +.i user +may be multi-part. +If the +.i mailer +is the builtin IPC mailer, +the +.i host +may be a colon-separated list of hosts +that are searched in order for the first working address +(exactly like MX records). +The +.i user +is later rewritten by the mailer-specific envelope rewriting set +and assigned to the +.b $u +macro. +As a special case, if the mailer specified has the +.b F=@ +flag specified +and the first character of the +.b $: +value is +.q @ , +the +.q @ +is stripped off, and a flag is set in the address descriptor +that causes sendmail to not do ruleset 5 processing. +.pp +Normally, a rule that matches is retried, +that is, +the rule loops until it fails. +A RHS may also be preceded by a +.b $@ +or a +.b $: +to change this behavior. +A +.b $@ +prefix causes the ruleset to return with the remainder of the RHS +as the value. +A +.b $: +prefix causes the rule to terminate immediately, +but the ruleset to continue; +this can be used to avoid continued application of a rule. +The prefix is stripped before continuing. +.pp +The +.b $@ +and +.b $: +prefixes may precede a +.b $> +spec; +for example: +.(b +.ta 8n +R$+ $: $>7 $1 +.)b +matches anything, +passes that to ruleset seven, +and continues; +the +.b $: +is necessary to avoid an infinite loop. +.pp +Substitution occurs in the order described, +that is, +parameters from the LHS are substituted, +hostnames are canonicalized, +.q subroutines +are called, +and finally +.b $# , +.b $@ , +and +.b $: +are processed. +.sh 3 "Semantics of rewriting rule sets" +.pp +There are six rewriting sets +that have specific semantics. +Five of these are related as depicted by figure 1. +.(z +.hl +.ie n \{\ +.(c + +---+ + -->| 0 |-->resolved address + / +---+ + / +---+ +---+ + / ---->| 1 |-->| S |-- + +---+ / +---+ / +---+ +---+ \e +---+ +addr-->| 3 |-->| D |-- --->| 4 |-->msg + +---+ +---+ \e +---+ +---+ / +---+ + --->| 2 |-->| R |-- + +---+ +---+ +.)c + +.\} +.el .ie !"\*(.T"" \ +\{\ +.PS +boxwid = 0.3i +boxht = 0.3i +movewid = 0.3i +moveht = 0.3i +linewid = 0.3i +lineht = 0.3i + + box invis "addr"; arrow +Box3: box "3" +A1: arrow +BoxD: box "D"; line; L1: Here +C: [ + C1: arrow; box "1"; arrow; box "S"; line; E1: Here + move to C1 down 0.5; right + C2: arrow; box "2"; arrow; box "R"; line; E2: Here + ] with .w at L1 + (0.5, 0) + move to C.e right 0.5 +L4: arrow; box "4"; arrow; box invis "msg" + line from L1 to C.C1 + line from L1 to C.C2 + line from C.E1 to L4 + line from C.E2 to L4 + move to BoxD.n up 0.6; right +Box0: arrow; box "0" + arrow; box invis "resolved address" width 1.3 + line from 1/3 of the way between A1 and BoxD.w to Box0 +.PE +.\} +.el .sp 2i +.ce +Figure 1 \*- Rewriting set semantics +.(c +D \*- sender domain addition +S \*- mailer-specific sender rewriting +R \*- mailer-specific recipient rewriting +.)c +.hl +.)z +.pp +Ruleset three +should turn the address into +.q "canonical form." +This form should have the basic syntax: +.(b +local-part@host-domain-spec +.)b +Ruleset three +is applied by +.i sendmail +before doing anything with any address. +.pp +If no +.q @ +sign is specified, +then the +host-domain-spec +.i may +be appended (box +.q D +in Figure 1) +from the +sender address +(if the +.b C +flag is set in the mailer definition +corresponding to the +.i sending +mailer). +.pp +Ruleset zero +is applied after ruleset three +to addresses that are going to actually specify recipients. +It must resolve to a +.i "{mailer, host, user}" +triple. +The +.i mailer +must be defined in the mailer definitions +from the configuration file. +The +.i host +is defined into the +.b $h +macro +for use in the argv expansion of the specified mailer. +.pp +Rulesets one and two +are applied to all sender and recipient addresses respectively. +They are applied before any specification +in the mailer definition. +They must never resolve. +.pp +Ruleset four is applied to all addresses +in the message. +It is typically used +to translate internal to external form. +.pp +In addition, +ruleset 5 is applied to all local addresses +(specifically, those that resolve to a mailer with the `F=5' +flag set) +that do not have aliases. +This allows a last minute hook for local names. +.sh 3 "Ruleset hooks" +.pp +A few extra rulesets are defined as +.q hooks +that can be defined to get special features. +They are all named rulesets. +The +.q check_* +forms all give accept/reject status; +falling off the end or returning normally is an accept, +and resolving to +.b $#error +is a reject. +Many of these can also resolve to the special mailer +.b $#discard ; +this accepts the message as though it were successful +but then discards it without delivery. +.sh 4 "check_relay" +.pp +The +.i check_relay +ruleset is called after a connection is accepted. +It is passed +.(b +client.host.name $| client.host.address +.)b +where +.b $| +is a metacharacter separating the two parts. +This ruleset can reject connections from various locations. +.sh 4 "check_mail" +.pp +The +.i check_mail +ruleset is passed the user name parameter of the +.sm "SMTP MAIL" +command. +It can accept or reject the address. +.sh 4 "check_rcpt" +.pp +The +.i check_rcpt +ruleset is passed the user name parameter of the +.sm "SMTP RCPT" +command. +It can accept or reject the address. +.sh 4 "check_compat" +.pp +The +.i check_compat +ruleset is passed +.(b +sender-address $| recipient-address +.)b +where +.b $| +is a metacharacter separating the addresses. +It can accept or reject mail transfer between these two addresses +much like the +.i checkcompat() +function. +.sh 3 "IPC mailers" +.pp +Some special processing occurs +if the ruleset zero resolves to an IPC mailer +(that is, a mailer that has +.q [IPC] +listed as the Path in the +.b M +configuration line. +The host name passed after +.q $@ +has MX expansion performed; +this looks the name up in DNS to find alternate delivery sites. +.pp +The host name can also be provided as a dotted quad in square brackets; +for example: +.(b +[128.32.149.78] +.)b +This causes direct conversion of the numeric value +to an IP host address. +.pp +The host name passed in after the +.q $@ +may also be a colon-separated list of hosts. +Each is separately MX expanded and the results are concatenated +to make (essentially) one long MX list. +The intent here is to create +.q fake +MX records that are not published in DNS +for private internal networks. +.pp +As a final special case, the host name can be passed in +as a text string +in square brackets: +.(b +[ucbvax.berkeley.edu] +.)b +This form avoids the MX mapping. +.b N.B.: +.i +This is intended only for situations where you have a network firewall +or other host that will do special processing for all your mail, +so that your MX record points to a gateway machine; +this machine could then do direct delivery to machines +within your local domain. +Use of this feature directly violates RFC 1123 section 5.3.5: +it should not be used lightly. +.r +.sh 2 "D \*- Define Macro" +.pp +Macros are named with a single character +or with a word in {braces}. +Single character names may be selected from the entire ASCII set, +but user-defined macros +should be selected from the set of upper case letters only. +Lower case letters +and special symbols +are used internally. +Long names beginning with a lower case letter or a punctuation character +are reserved for use by sendmail, +so user-defined long macro names should begin with an upper case letter. +.pp +The syntax for macro definitions is: +.(b F +.b D \c +.i x\|val +.)b +where +.i x +is the name of the macro +(which may be a single character +or a word in braces) +and +.i val +is the value it should have. +There should be no spaces given +that do not actually belong in the macro value. +.pp +Macros are interpolated +using the construct +.b $ \c +.i x , +where +.i x +is the name of the macro to be interpolated. +This interpolation is done when the configuration file is read, +except in +.b M +lines. +The special construct +.b $& \c +.i x +can be used in +.b R +lines to get deferred interpolation. +.pp +Conditionals can be specified using the syntax: +.(b +$?x text1 $| text2 $. +.)b +This interpolates +.i text1 +if the macro +.b $x +is set, +and +.i text2 +otherwise. +The +.q else +(\c +.b $| ) +clause may be omitted. +.pp +Lower case macro names are reserved to have +special semantics, +used to pass information in or out of +.i sendmail , +and special characters are reserved to +provide conditionals, etc. +Upper case names +(that is, +.b $A +through +.b $Z ) +are specifically reserved for configuration file authors. +.pp +The following macros are defined and/or used internally by +.i sendmail +for interpolation into argv's for mailers +or for other contexts. +The ones marked \(dg are information passed into sendmail\**, +.(f +\**As of version 8.6, +all of these macros have reasonable defaults. +Previous versions required that they be defined. +.)f +the ones marked \(dd are information passed both in and out of sendmail, +and the unmarked macros are passed out of sendmail +but are not otherwise used internally. +These macros are: +.nr ii 5n +.ip $a +The origination date in RFC 822 format. +This is extracted from the Date: line. +.ip $b +The current date in RFC 822 format. +.ip $c +The hop count. +This is a count of the number of Received: lines +plus the value of the +.b \-h +command line flag. +.ip $d +The current date in UNIX (ctime) format. +.ip $e\(dg +(Obsolete; use SmtpGreetingMessage option instead.) +The SMTP entry message. +This is printed out when SMTP starts up. +The first word must be the +.b $j +macro as specified by RFC821. +Defaults to +.q "$j Sendmail $v ready at $b" . +Commonly redefined to include the configuration version number, e.g., +.q "$j Sendmail $v/$Z ready at $b" +.ip $f +The envelope sender (from) address. +.ip $g +The sender address relative to the recipient. +For example, if +.b $f +is +.q foo , +.b $g +will be +.q host!foo , +.q foo@host.domain , +or whatever is appropriate for the receiving mailer. +.ip $h +The recipient host. +This is set in ruleset 0 from the $# field of a parsed address. +.ip $i +The queue id, +e.g., +.q HAA12345 . +.ip $j\(dd +The \*(lqofficial\*(rq domain name for this site. +This is fully qualified if the full qualification can be found. +It +.i must +be redefined to be the fully qualified domain name +if your system is not configured so that information can find +it automatically. +.ip $k +The UUCP node name (from the uname system call). +.ip $l\(dg +(Obsolete; use UnixFromLine option instead.) +The format of the UNIX from line. +Unless you have changed the UNIX mailbox format, +you should not change the default, +which is +.q "From $g $d" . +.ip $m +The domain part of the \fIgethostname\fP return value. +Under normal circumstances, +.b $j +is equivalent to +.b $w.$m . +.ip $n\(dg +The name of the daemon (for error messages). +Defaults to +.q MAILER-DAEMON . +.ip $o\(dg +(Obsolete: use OperatorChars option instead.) +The set of \*(lqoperators\*(rq in addresses. +A list of characters +which will be considered tokens +and which will separate tokens +when doing parsing. +For example, if +.q @ +were in the +.b $o +macro, then the input +.q a@b +would be scanned as three tokens: +.q a, +.q @, +and +.q b. +Defaults to +.q ".:@[]" , +which is the minimum set necessary to do RFC 822 parsing; +a richer set of operators is +.q ".:%@!/[]" , +which adds support for UUCP, the %-hack, and X.400 addresses. +.ip $p +Sendmail's process id. +.ip $q\(dg +Default format of sender address. +The +.b $q +macro specifies how an address should appear in a message +when it is defaulted. +Defaults to +.q "<$g>" . +It is commonly redefined to be +.q "$?x$x <$g>$|$g$." +or +.q "$g$?x ($x)$." , +corresponding to the following two formats: +.(b +Eric Allman <eric@CS.Berkeley.EDU> +eric@CS.Berkeley.EDU (Eric Allman) +.)b +.i Sendmail +properly quotes names that have special characters +if the first form is used. +.ip $r +Protocol used to receive the message. +Set from the +.b \-p +command line flag or by the SMTP server code. +.ip $s +Sender's host name. +Set from the +.b \-p +command line flag or by the SMTP server code. +.ip $t +A numeric representation of the current time. +.ip $u +The recipient user. +.ip $v +The version number of the +.i sendmail +binary. +.ip $w\(dd +The hostname of this site. +This is the root name of this host (but see below for caveats). +.ip $x +The full name of the sender. +.ip $z +The home directory of the recipient. +.ip $_ +The validated sender address. +.ip ${bodytype} +The message body type +(7BIT or 8BITMIME), +as determined from the envelope. +.ip ${client_addr} +The IP address of the SMTP client. +Defined in the SMTP server only. +.ip ${client_name} +The host name of the SMTP client. +Defined in the SMTP server only. +.ip ${client_port} +The port number of the SMTP client. +Defined in the SMTP server only. +.ip ${envid} +The envelope id passed to sendmail as part of the envelope. +.ip ${opMode} +The current operation mode (from the +.b \-b +flag). +.ip ${deliveryMode} +The current delivery mode +(from the +.b DeliveryMode +option). +.pp +There are three types of dates that can be used. +The +.b $a +and +.b $b +macros are in RFC 822 format; +.b $a +is the time as extracted from the +.q Date: +line of the message +(if there was one), +and +.b $b +is the current date and time +(used for postmarks). +If no +.q Date: +line is found in the incoming message, +.b $a +is set to the current time also. +The +.b $d +macro is equivalent to the +.b $b +macro in UNIX +(ctime) +format. +.pp +The macros +.b $w , +.b $j , +and +.b $m +are set to the identity of this host. +.i Sendmail +tries to find the fully qualified name of the host +if at all possible; +it does this by calling +.i gethostname (2) +to get the current hostname +and then passing that to +.i gethostbyname (3) +which is supposed to return the canonical version of that host name.\** +.(f +\**For example, on some systems +.i gethostname +might return +.q foo +which would be mapped to +.q foo.bar.com +by +.i gethostbyname . +.)f +Assuming this is successful, +.b $j +is set to the fully qualified name +and +.b $m +is set to the domain part of the name +(everything after the first dot). +The +.b $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 +.b $j . +If the canonification is not successful, +it is imperative that the config file set +.b $j +to the fully qualified domain name\**. +.(f +\**Older versions of sendmail didn't pre-define +.b $j +at all, so up until 8.6, +config files +.i always +had to define +.b $j . +.)f +.pp +The +.b $f +macro is the id of the sender +as originally determined; +when mailing to a specific host +the +.b $g +macro is set to the address of the sender +.ul +relative to the recipient. +For example, +if I send to +.q bollard@matisse.CS.Berkeley.EDU +from the machine +.q vangogh.CS.Berkeley.EDU +the +.b $f +macro will be +.q eric +and the +.b $g +macro will be +.q eric@vangogh.CS.Berkeley.EDU. +.pp +The +.b $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 +.i sendmail . +It can be defined in the +.sm NAME +environment variable. +The third choice is the value of the +.q Full-Name: +line in the header if it exists, +and the fourth choice is the comment field +of a +.q From: +line. +If all of these fail, +and if the message is being originated locally, +the full name is looked up in the +.i /etc/passwd +file. +.pp +When sending, +the +.b $h , +.b $u , +and +.b $z +macros get set to the host, user, and home directory +(if local) +of the recipient. +The first two are set from the +.b $@ +and +.b $: +part of the rewriting rules, respectively. +.pp +The +.b $p +and +.b $t +macros are used to create unique strings +(e.g., for the +.q Message-Id: +field). +The +.b $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 +.b $v +macro is set to be the version number of +.i sendmail ; +this is normally put in timestamps +and has been proven extremely useful for debugging. +.pp +The +.b $c +field is set to the +.q "hop count," +i.e., the number of times this message has been processed. +This can be determined +by the +.b \-h +flag on the command line +or by counting the timestamps in the message. +.pp +The +.b $r +and +.b $s +fields are set to the protocol used to communicate with +.i sendmail +and the sending hostname. +They can be set together using the +.b \-p +command line flag or separately using the +.b \-M +or +.b \-oM +flags. +.pp +The +.b $_ +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. +.pp +The +.b ${client_name} , +.b ${client_addr} , +and +.b ${client_port} +macros +are set to the name, address, and port number of the SMTP client +who is invoking +.i sendmail +as a server. +These can be used in the +.i check_* +rulesets (using the +.b $& +deferred evaluation form, of course!). +.sh 2 "C and F \*- Define Classes" +.pp +Classes of phrases may be defined +to match on the left hand side of rewriting rules, +where a +.q phrase +is a sequence of characters that does not contain space characters. +For example +a class of all local names for this site +might be created +so that attempts to send to oneself +can be eliminated. +These can either be defined directly in the configuration file +or read in from another file. +Classes are named as a single letter or a word in {braces}. +Class names beginning with lower case letters +and special characters are reserved for system use. +Classes defined in config files may be given names +from the set of upper case letters for short names +or beginning with an upper case letter for long names. +.pp +The syntax is: +.(b F +.b C \c +.i c\|phrase1 +.i phrase2... +.br +.b F \c +.i c\|file +.)b +The first form defines the class +.i c +to match any of the named words. +It is permissible to split them among multiple lines; +for example, the two forms: +.(b +CHmonet ucbmonet +.)b +and +.(b +CHmonet +CHucbmonet +.)b +are equivalent. +The ``F'' form +reads the elements of the class +.i c +from the named +.i file . +.pp +Elements of classes can be accessed in rules using +.b $= +or +.b $~ . +The +.b $~ +(match entries not in class) +only matches a single word; +multi-word entries in the class are ignored in this context. +.pp +Some classes have internal meaning to +.i sendmail : +.nr ii 0.5i +.\".ip $=b +.\"A set of Content-Types that will not have the newline character +.\"translated to CR-LF before encoding into base64 MIME. +.\"The class can have major times +.\"(e.g., +.\".q image ) +.\"or full types +.\"(such as +.\".q application/octet-stream ). +.\"The class is initialized with +.\".q application/octet-stream , +.\".q image , +.\".q audio , +.\"and +.\".q video . +.ip $=e +contains the Content-Transfer-Encodings that can be 8\(->7 bit encoded. +It is predefined to contain +.q 7bit , +.q 8bit , +and +.q binary . +.ip $=k +set to be the same as +.b $k , +that is, the UUCP node name. +.ip $=m +set to the set of domains by which this host is known, +initially just +.b $m . +.ip $=n +can be set to the set of MIME body types +that can never be eight to seven bit encoded. +It defaults to +.q multipart/signed . +Message types +.q message/* +and +.q multipart/* +are never encoded directly. +Multipart messages are always handled recursively. +The handling of message/* messages +are controlled by class +.b $=s . +.ip $=q +A set of Content-Types that will never be encoded as base64 +(if they have to be encoded, they will be encoded as quoted-printable). +It can have primary types +(e.g., +.q text ) +or full types +(such as +.q text/plain ). +The class is initialized to have +.q text/plain +only. +.ip $=s +contains the set of subtypes of message that can be treated recursively. +By default it contains only +.q rfc822 . +Other +.q message/* +types cannot be 8\(->7 bit encoded. +If a message containing eight bit data is sent to a seven bit host, +and that message cannot be encoded into seven bits, +it will be stripped to 7 bits. +.ip $=t +set to the set of trusted users by the +.b T +configuration line. +If you want to read trusted users from a file, use +.b Ft \c +.i /file/name . +.ip $=w +set to be the set of all names +this host is known by. +This can be used to match local hostnames. +.pp +.i Sendmail +can be compiled to allow a +.i scanf (3) +string on the +.b F +line. +This lets you do simplistic parsing of text files. +For example, to read all the user names in your system +.i /etc/passwd +file into a class, use +.(b +FL/etc/passwd %[^:] +.)b +which reads every line up to the first colon. +.sh 2 "M \*- Define Mailer" +.pp +Programs and interfaces to mailers +are defined in this line. +The format is: +.(b F +.b M \c +.i name , +{\c +.i field =\c +.i value \|}* +.)b +where +.i name +is the name of the mailer +(used internally only) +and the +.q field=name +pairs define attributes of the mailer. +Fields are: +.(b +.ta 1i +Path The pathname of the mailer +Flags Special flags for this mailer +Sender Rewriting set(s) for sender addresses +Recipient Rewriting set(s) for recipient addresses +Argv An argument vector to pass to this mailer +Eol The end-of-line string for this mailer +Maxsize The maximum message length to this mailer +Linelimit The maximum line length in the message body +Directory The working directory for the mailer +Userid The default user and group id to run as +Nice The nice(2) increment for the mailer +Charset The default character set for 8-bit characters +Type The MTS type information (used for error messages) +.)b +Only the first character of the field name is checked. +.pp +The following flags may be set in the mailer description. +Any other flags may be used freely +to conditionally assign headers to messages +destined for particular mailers. +Flags marked with \(dg +are not interpreted by the +.i sendmail +binary; +these are the conventionally used to correlate to the flags portion +of the +.b H +line. +Flags marked with \(dd +apply to the mailers for the sender address +rather than the usual recipient mailers. +.nr ii 4n +.ip a +Run Extended SMTP (ESMTP) protocol (defined in RFCs 1869, 1652, and 1870). +This flag defaults on if the SMTP greeting message includes the word +.q ESMTP . +.ip A +Look up the user part of the address in the alias database. +Normally this is only set for local mailers. +.ip b +Force a blank line on the end of a message. +This is intended to work around some stupid versions of +/bin/mail +that require a blank line, but do not provide it themselves. +It would not normally be used on network mail. +.ip c +Do not include comments in addresses. +This should only be used if you have to work around +a remote mailer that gets confused by comments. +This strips addresses of the form +.q "Phrase <address>" +or +.q "address (Comment)" +down to just +.q address . +.ip C\(dd +If mail is +.i received +from a mailer with this flag set, +any addresses in the header that do not have an at sign +(\c +.q @ ) +after being rewritten by ruleset three +will have the +.q @domain +clause from the sender envelope address +tacked on. +This allows mail with headers of the form: +.(b +From: usera@hosta +To: userb@hostb, userc +.)b +to be rewritten as: +.(b +From: usera@hosta +To: userb@hostb, userc@hosta +.)b +automatically. +However, it doesn't really work reliably. +.ip d +Do not include angle brackets around route-address syntax addresses. +This is useful on mailers that are going to pass addresses to a shell +that might interpret angle brackets as I/O redirection. +.ip D\(dg +This mailer wants a +.q Date: +header line. +.ip e +This mailer is expensive to connect to, +so try to avoid connecting normally; +any necessary connection will occur during a queue run. +.ip E +Escape lines beginning with +.q From\0 +in the message with a `>' sign. +.ip f +The mailer wants a +.b \-f +.i from +flag, +but only if this is a network forward operation +(i.e., +the mailer will give an error +if the executing user +does not have special permissions). +.ip F\(dg +This mailer wants a +.q From: +header line. +.ip g +Normally, +.i sendmail +sends internally generated email (e.g., error messages) +using the null return address +as required by RFC 1123. +However, some mailers don't accept a null return address. +If necessary, +you can set the +.b g +flag to prevent +.i sendmail +from obeying the standards; +error messages will be sent as from the MAILER-DAEMON +(actually, the value of the +.b $n +macro). +.ip h +Upper case should be preserved in host names +for this mailer. +.ip i +Do User Database rewriting on envelope sender address. +.ip I +This mailer will be speaking SMTP +to another +.i sendmail +\*- +as such it can use special protocol features. +This option is not required +(i.e., +if this option is omitted the transmission will still operate successfully, +although perhaps not as efficiently as possible). +.ip j +Do User Database rewriting on recipients as well as senders. +.ip k +Normally when +.i sendmail +connects to a host via SMTP, +it checks to make sure that this isn't accidently the same host name +as might happen if +.i sendmail +is misconfigured or if a long-haul network interface is set in loopback mode. +This flag disables the loopback check. +It should only be used under very unusual circumstances. +.ip K +Currently unimplemented. +Reserved for chunking. +.ip l +This mailer is local +(i.e., +final delivery will be performed). +.ip L +Limit the line lengths as specified in RFC821. +This deprecated option should be replaced by the +.b L= +mail declaration. +For historic reasons, the +.b L +flag also sets the +.b 7 +flag. +.ip m +This mailer can send to multiple users +on the same host +in one transaction. +When a +.b $u +macro occurs in the +.i argv +part of the mailer definition, +that field will be repeated as necessary +for all qualifying users. +.ip M\(dg +This mailer wants a +.q Message-Id: +header line. +.ip n +Do not insert a UNIX-style +.q From +line on the front of the message. +.ip o +Always run as the owner of the recipient mailbox. +Normally +.i sendmail +runs as the sender for locally generated mail +or as +.q daemon +(actually, the user specified in the +.b u +option) +when delivering network mail. +The normal behaviour is required by most local mailers, +which will not allow the envelope sender address +to be set unless the mailer is running as daemon. +This flag is ignored if the +.b S +flag is set. +.ip p +Use the route-addr style reverse-path in the SMTP +.q "MAIL FROM:" +command +rather than just the return address; +although this is required in RFC821 section 3.1, +many hosts do not process reverse-paths properly. +Reverse-paths are officially discouraged by RFC 1123. +.ip P\(dg +This mailer wants a +.q Return-Path: +line. +.ip q +When an address that resolves to this mailer is verified +(SMTP VRFY command), +generate 250 responses instead of 252 responses. +This will imply that the address is local. +.ip r +Same as +.b f , +but sends a +.b \-r +flag. +.ip R +Open SMTP connections from a +.q secure +port. +Secure ports aren't +(secure, that is) +except on UNIX machines, +so it is unclear that this adds anything. +.ip s +Strip quote characters (" and \e) off of the address +before calling the mailer. +.ip S +Don't reset the userid +before calling the mailer. +This would be used in a secure environment +where +.i sendmail +ran as root. +This could be used to avoid forged addresses. +If the +.b U= +field is also specified, +this flag causes the user id to always be set to that user and group +(instead of leaving it as root). +.ip u +Upper case should be preserved in user names +for this mailer. +.ip U +This mailer wants UUCP-style +.q From +lines with the ugly +.q "remote from <host>" +on the end. +.ip w +The user must have a valid account on this machine, +i.e., +getpwnam +must succeed. +If not, +the mail is bounced. +This is required to get +.q \&.forward +capability. +.ip x\(dg +This mailer wants a +.q Full-Name: +header line. +.ip X +This mailer want to use the hidden dot algorithm +as specified in RFC821; +basically, +any line beginning with a dot +will have an extra dot prepended +(to be stripped at the other end). +This insures that lines in the message containing a dot +will not terminate the message prematurely. +.ip z +Run Local Mail Transfer Protocol (LMTP) +between +.i sendmail +and the local mailer. +This is a variant on SMTP +defined in RFC 2033 +that is specifically designed for delivery to a local mailbox. +.ip 0 +Don't look up MX records for hosts sent via SMTP. +.ip 3 +Extend the list of characters converted to =XX notation +when converting to Quoted-Printable +to include those that don't map cleanly between ASCII and EBCDIC. +Useful if you have IBM mainframes on site. +.ip 5 +If no aliases are found for this address, +pass the address through ruleset 5 for possible alternate resolution. +This is intended to forward the mail to an alternate delivery spot. +.ip 7 +Strip all output to seven bits. +This is the default if the +.b L +flag is set. +Note that clearing this option is not +sufficient to get full eight bit data passed through +.i sendmail . +If the +.b 7 +option is set, this is essentially always set, +since the eighth bit was stripped on input. +Note that this option will only impact messages +that didn't have 8\(->7 bit MIME conversions performed. +.ip 8 +If set, +it is acceptable to send eight bit data to this mailer; +the usual attempt to do 8\(->7 bit MIME conversions will be bypassed. +.ip 9 +If set, +do +.i limited +7\(->8 bit MIME conversions. +These conversions are limited to text/plain data. +.ip : +Check addresses to see if they begin +.q :include: ; +if they do, convert them to the +.q *include* +mailer. +.ip | +Check addresses to see if they begin with a `|'; +if they do, convert them to the +.q prog +mailer. +.ip / +Check addresses to see if they begin with a `/'; +if they do, convert them to the +.q *file* +mailer. +.ip @ +Look up addresses in the user database. +.pp +Configuration files prior to level 6 +assume the `A', `w', `5', `:', `|', `/', and `@' options +on the mailer named +.q local . +.pp +The mailer with the special name +.q error +can be used to generate a user error. +The (optional) host field is an exit status to be returned, +and the user field is a message to be printed. +The exit status may be numeric or one of the values +USAGE, NOUSER, NOHOST, UNAVAILABLE, SOFTWARE, TEMPFAIL, PROTOCOL, or CONFIG +to return the corresponding EX_ exit code, +or an enhanced error code as described in RFC 1893, +.ul +Enhanced Mail System Status Codes. +For example, the entry: +.(b +$#error $@ NOHOST $: Host unknown in this domain +.)b +on the RHS of a rule +will cause the specified error to be generated +and the +.q "Host unknown" +exit status to be returned +if the LHS matches. +This mailer is only functional in rulesets 0, 5, +or one of the check_* rulesets. +.pp +The mailer with the special name +.q discard +causes any mail sent to it to be discarded +but otherwise treated as though it were successfully delivered. +.pp +The mailer named +.q local +.i must +be defined in every configuration file. +This is used to deliver local mail, +and is treated specially in several ways. +Additionally, three other mailers named +.q prog , +.q *file* , +and +.q *include* +may be defined to tune the delivery of messages to programs, +files, +and :include: lists respectively. +They default to: +.(b +Mprog, P=/bin/sh, F=lsoDq9, T=DNS/RFC822/X-Unix, A=sh \-c $u +M*file*, P=[FILE], F=lsDFMPEouq9, T=DNS/RFC822/X-Unix, A=FILE $u +M*include*, P=/dev/null, F=su, A=INCLUDE $u +.)b +.pp +The Sender and Recipient rewriting sets +may either be a simple ruleset id +or may be two ids separated by a slash; +if so, the first rewriting set is applied to envelope +addresses +and the second is applied to headers. +.pp +The Directory +is actually a colon-separated path of directories to try. +For example, the definition +.q D=$z:/ +first tries to execute in the recipient's home directory; +if that is not available, +it tries to execute in the root of the filesystem. +This is intended to be used only on the +.q prog +mailer, +since some shells (such as +.i csh ) +refuse to execute if they cannot read the home directory. +Since the queue directory is not normally readable by unprivileged users +.i csh +scripts as recipients can fail. +.pp +The Userid +specifies the default user and group id to run as, +overriding the +.b DefaultUser +option (q.v.). +If the +.b S +mailer flag is also specified, +this is the user and group to run as in all circumstances. +This may be given as +.i user:group +to set both the user and group id; +either may be an integer or a symbolic name to be looked up +in the +.i passwd +and +.i group +files respectively. +If only a symbolic user name is specified, +the group id in the +.i passwd +file for that user is used as the group id. +.pp +The Charset field +is used when converting a message to MIME; +this is the character set used in the +Content-Type: header. +If this is not set, the +.b DefaultCharset +option is used, +and if that is not set, the value +.q unknown-8bit +is used. +.b WARNING: +this field applies to the sender's mailer, +not the recipient's mailer. +For example, if the envelope sender address +lists an address on the local network +and the recipient is on an external network, +the character set will be set from the Charset= field +for the local network mailer, +not that of the external network mailer. +.pp +The Type= field +sets the type information +used in MIME error messages +as defined by +RFC 1894. +It is actually three values separated by slashes: +the MTA-type (that is, the description of how hosts are named), +the address type (the description of e-mail addresses), +and the diagnostic type (the description of error diagnostic codes). +Each of these must be a registered value +or begin with +.q X\- . +The default is +.q dns/rfc822/smtp . +.sh 2 "H \*- Define Header" +.pp +The format of the header lines that +.i sendmail +inserts into the message +are defined by the +.b H +line. +The syntax of this line is: +.(b F +.b H [\c +.b ? \c +.i mflags \c +.b ? ]\c +.i hname \c +.b : +.i htemplate +.)b +Continuation lines in this spec +are reflected directly into the outgoing message. +The +.i htemplate +is macro-expanded before insertion into the message. +If the +.i mflags +(surrounded by question marks) +are specified, +at least one of the specified flags +must be stated in the mailer definition +for this header to be automatically output. +If one of these headers is in the input +it is reflected to the output +regardless of these flags. +.pp +Some headers have special semantics +that will be described later. +.pp +A secondary syntax allows validation of headers as they are being read. +To enable validation, use: +.(b +.b H \c +.i Header \c +.b ": $>" \c +.i Ruleset +.)b +The indicated +.i Ruleset +is called for the specified +.i Header , +and can return +.b $#error +to reject the message or +.b $#discard +to discard the message +(as with the other +.b check_ * +rulesets). +The header is treated as a structured field, +that is, +comments (in parentheses) are deleted before processing. +.pp +For example, the configuration lines: +.(b +HMessage-Id: $>CheckMessageId + +SCheckMessageId +R< $+ @ $+ > $@ OK +R$* $#error $: Illegal Message-Id header +.)b +would refuse any message that had a Message-Id: header of any of the +following forms: +.(b +Message-Id: <> +Message-Id: some text +Message-Id: <legal text@domain> extra crud +.)b +.sh 2 "O \*- Set Option" +.pp +There are a number of +global +options that +can be set from a configuration file. +Options are represented by full words; +some are also representable as single characters +for back compatibility. +The syntax of this line is: +.(b F +.b O \0 +.i option \c +.b = \c +.i value +.)b +This sets option +.i option +to be +.i value . +Note that there +.i must +be a space between the letter `O' and the name of the option. +An older version is: +.(b F +.b O \c +.i o\|value +.)b +where the option +.i o +is a single character. +Depending on the option, +.i value +may be a string, an integer, +a boolean +(with legal values +.q t , +.q T , +.q f , +or +.q F ; +the default is TRUE), +or +a time interval. +.pp +The options supported (with the old, one character names in brackets) are: +.nr ii 1i +.ip "AliasFile=\fIspec, spec, ...\fP" +[A] +Specify possible alias file(s). +Each +.i spec +should be in the format +``\c +.i class \c +.b : +.i file '' +where +.i class \c +.b : +is optional and defaults to ``implicit''. +Depending on how +.i sendmail +is compiled, valid classes are +.q implicit +(search through a compiled-in list of alias file types, +for back compatibility), +.q hash +(if +.sm NEWDB +is specified), +.q dbm +(if +.sm NDBM +is specified), +.q stab +(internal symbol table \*- not normally used +unless you have no other database lookup), +or +.q nis +(if +.sm NIS +is specified). +If a list of +.i spec s +are provided, +.i sendmail +searches them in order. +.ip AliasWait=\fItimeout\fP +[a] +If set, +wait up to +.i timeout +(units default to minutes) +for an +.q @:@ +entry to exist in the alias database +before starting up. +If it does not appear in the +.i timeout +interval +rebuild the database +(if the +.b AutoRebuildAliases +option is also set) +or issue a warning. +.ip AllowBogusHELO +[no short name] +If set, allow HELO SMTP commands that don't include a host name. +Setting this violates RFC 1123 section 5.2.5, +but is necessary to interoperate with several SMTP clients. +If there is a value, it is still checked for legitimacy. +.ip AutoRebuildAliases +[D] +If set, +rebuild the alias database if necessary and possible. +If this option is not set, +.i sendmail +will never rebuild the alias database +unless explicitly requested +using +.b \-bi . +Not recommended \(em can cause thrashing. +.ip BlankSub=\fIc\fP +[B] +Set the blank substitution character to +.i c . +Unquoted spaces in addresses are replaced by this character. +Defaults to space (i.e., no change is made). +.ip CheckAliases +[n] +Validate the RHS of aliases when rebuilding the alias database. +.ip CheckpointInterval=\fIN\fP +[C] +Checkpoints the queue every +.i N +(default 10) +addresses sent. +If your system crashes during delivery to a large list, +this prevents retransmission to any but the last +.I N +recipients. +.ip ClassFactor=\fIfact\fP +[z] +The indicated +.i fact or +is multiplied by the message class +(determined by the Precedence: field in the user header +and the +.b P +lines in the configuration file) +and subtracted from the priority. +Thus, messages with a higher Priority: will be favored. +Defaults to 1800. +.ip ColonOkInAddr +[no short name] +If set, colons are acceptable in e-mail addresses +(e.g., +.q host:user ). +If not set, colons indicate the beginning of a RFC 822 group construct +(\c +.q "groupname: member1, member2, ... memberN;" ). +Doubled colons are always acceptable +(\c +.q nodename::user ) +and proper route-addr nesting is understood +(\c +.q <@relay:user@host> ). +Furthermore, this option defaults on if the configuration version level +is less than 6 (for back compatibility). +However, it must be off for full compatibility with RFC 822. +.ip ConnectionCacheSize=\fIN\fP +[k] +The maximum number of open connections that will be cached at a time. +The default is one. +This delays closing the current connection until +either this invocation of +.i sendmail +needs to connect to another host +or it terminates. +Setting it to zero defaults to the old behavior, +that is, connections are closed immediately. +Since this consumes file descriptors, +the connection cache should be kept small: +4 is probably a practical maximum. +.ip ConnectionCacheTimeout=\fItimeout\fP +[K] +The maximum amount of time a cached connection will be permitted to idle +without activity. +If this time is exceeded, +the connection is immediately closed. +This value should be small (on the order of ten minutes). +Before +.i sendmail +uses a cached connection, +it always sends a RSET command +to check the connection; +if this fails, it reopens the connection. +This keeps your end from failing if the other end times out. +The point of this option is to be a good network neighbor +and avoid using up excessive resources +on the other end. +The default is five minutes. +.ip ConnectionRateThrottle=\fIN\fP +[no short name] +If set to a positive value, +allow no more than +.i N +incoming daemon connections in a one second period. +This is intended to flatten out peaks +and allow the load average checking to cut in. +Defaults to zero (no limits). +.ip DaemonPortOptions=\fIoptions\fP +[O] +Set server SMTP options. +The options are +.i key=value +pairs. +Known keys are: +.(b +.ta 1i +Port Name/number of listening port (defaults to "smtp") +Addr Address mask (defaults INADDR_ANY) +Family Address family (defaults to INET) +Listen Size of listen queue (defaults to 10) +SndBufSize Size of TCP send buffer +RcvBufSize Size of TCP receive buffer +.)b +The +.i Addr ess +mask may be a numeric address in dot notation +or a network name. +.ip DefaultCharSet=\fIcharset\fP +[no short name] +When a message that has 8-bit characters but is not in MIME format +is converted to MIME +(see the EightBitMode option) +a character set must be included in the Content-Type: header. +This character set is normally set from the Charset= field +of the mailer descriptor. +If that is not set, the value of this option is used. +If this option is not set, the value +.q unknown-8bit +is used. +.ip DefaultUser=\fIuser:group\fP +[u] +Set the default userid for mailers to +.i user:group . +If +.i group +is omitted and +.i user +is a user name +(as opposed to a numeric user id) +the default group listed in the /etc/passwd file for that user is used +as the default group. +Both +.i user +and +.i group +may be numeric. +Mailers without the +.i S +flag in the mailer definition +will run as this user. +Defaults to 1:1. +The value can also be given as a symbolic user name.\** +.(f +\**The old +.b g +option has been combined into the +.b DefaultUser +option. +.)f +.ip DeliveryMode=\fIx\fP +[d] +Deliver in mode +.i x . +Legal modes are: +.(b +.ta 4n +i Deliver interactively (synchronously) +b Deliver in background (asynchronously) +q Just queue the message (deliver during queue run) +d Defer delivery and all map lookups (deliver during queue run) +.)b +Defaults to ``b'' if no option is specified, +``i'' if it is specified but given no argument +(i.e., ``Od'' is equivalent to ``Odi''). +The +.b \-v +command line flag sets this to +.b i . +.ip DialDelay=\fIsleeptime\fP +[no short name] +Dial-on-demand network connections can see timeouts +if a connection is opened before the call is set up. +If this is set to an interval and a connection times out +on the first connection being attempted +.i sendmail +will sleep for this amount of time and try again. +This should give your system time to establish the connection +to your service provider. +Units default to seconds, so +.q DialDelay=5 +uses a five second delay. +Defaults to zero +(no retry). +.ip DontBlameSendmail=\fIoption,option,...\fP +[no short name] +In order to avoid possible cracking attempts +caused by world- and group-writable files and directories, +.i sendmail +does paranoid checking when opening most of its support files. +If for some reason you absolutely must run with, +for example, +a group-writable +.i /etc +directory, +then you will have to turn off this checking +(at the cost of making your system more vulnerable to attack). +The arguments are individual options that turn off checking: +.(b +Safe +AssumeSafeChown +ClassFileInUnsafeDirPath +ErrorHeaderInUnsafeDirPath +FileDeliveryToHardLink +FileDeliveryToSymLink +ForwardFileInUnsafeDirPath +ForwardFileInUnsafeDirPathSafe +ForwardFileIngroupWritableDirPath +GroupWritableAliasFile +GroupWritableDirPathSafe +GroupWritableForwardFileSafe +GroupWritableIncludeFileSafe +HelpFileinUnsafeDirPath +IncludeFileInUnsafeDirPath +IncludeFileInUnsafeDirPathSafe +IncludeFileIngroupWritableDirPath +LinkedAliasFileInWritableDir +LinkedClassFileInWritableDir +LinkedForwardFileInWritableDir +LinkedIncludeFileInWritableDir +LinkedMapInWritableDir +LinkedServiceSwitchFileInWritableDir +MapInUnsafeDirPath +RunProgramInUnsafeDirPath +RunWritableProgram +WorldWritableAliasFile +WriteMapToHardLink +WriteMapToSymLink +WriteStatsToHardLink +WriteStatsToSymLink +.)b +.b Safe +is the default. +The details of these flags are described above. +.\"XXX should have more here!!! XXX +.b "Use of this option is not recommended." +.ip DontExpandCnames +[no short name] +The standards say that all host addresses used in a mail message +must be fully canonical. +For example, if your host is named +.q Cruft.Foo.ORG +and also has an alias of +.q FTP.Foo.ORG , +the former name must be used at all times. +This is enforced during host name canonification +($[ ... $] lookups). +If this option is set, the protocols are ignored and the +.q wrong +thing is done. +However, the IETF is moving toward changing this standard, +so the behaviour may become acceptable. +Please note that hosts downstream may still rewrite the address +to be the true canonical name however. +.ip DontInitGroups +[no short name] +If set, +.i sendmail +will avoid using the initgroups(3) call. +If you are running NIS, +this causes a sequential scan of the groups.byname map, +which can cause your NIS server to be badly overloaded in a large domain. +The cost of this is that the only group found for users +will be their primary group (the one in the password file), +which will make file access permissions somewhat more restrictive. +Has no effect on systems that don't have group lists. +.ip DontProbeInterfaces +[no short name] +.i Sendmail +normally finds the names of all interfaces active on your machine +when it starts up +and adds their name to the +.b $=w +class of known host aliases. +If you have a large number of virtual interfaces +or if your DNS inverse lookups are slow +this can be time consuming. +This option turns off that probing. +However, you will need to be certain to include all variant names +in the +.b $=w +class by some other mechanism. +.ip DontPruneRoutes +[R] +Normally, +.i sendmail +tries to eliminate any unnecessary explicit routes +when sending an error message +(as discussed in RFC 1123 \(sc 5.2.6). +For example, +when sending an error message to +.(b +<@known1,@known2,@known3:user@unknown> +.)b +.i sendmail +will strip off the +.q @known1,@known2 +in order to make the route as direct as possible. +However, if the +.b R +option is set, this will be disabled, +and the mail will be sent to the first address in the route, +even if later addresses are known. +This may be useful if you are caught behind a firewall. +.ip DoubleBounceAddress=\fIerror-address\fP +[no short name] +If an error occurs when sending an error message, +send the error report +(termed a +.q "double bounce" +because it is an error +.q bounce +that occurs when trying to send another error +.q bounce ) +to the indicated address. +If not set, defaults to +.q postmaster . +.ip EightBitMode=\fIaction\fP +[8] +Set handling of eight-bit data. +There are two kinds of eight-bit data: +that declared as such using the +.b BODY=8BITMIME +ESMTP declaration or the +.b \-B8BITMIME +command line flag, +and undeclared 8-bit data, that is, +input that just happens to be eight bits. +There are three basic operations that can happen: +undeclared 8-bit data can be automatically converted to 8BITMIME, +undeclared 8-bit data can be passed as-is without conversion to MIME +(``just send 8''), +and declared 8-bit data can be converted to 7-bits +for transmission to a non-8BITMIME mailer. +The possible +.i action s +are: +.(b +.\" r Reject undeclared 8-bit data; +.\" don't convert 8BITMIME\(->7BIT (``reject'') + s Reject undeclared 8-bit data (``strict'') +.\" do convert 8BITMIME\(->7BIT (``strict'') +.\" c Convert undeclared 8-bit data to MIME; +.\" don't convert 8BITMIME\(->7BIT (``convert'') + m Convert undeclared 8-bit data to MIME (``mime'') +.\" do convert 8BITMIME\(->7BIT (``mime'') +.\" j Pass undeclared 8-bit data; +.\" don't convert 8BITMIME\(->7BIT (``just send 8'') + p Pass undeclared 8-bit data (``pass'') +.\" do convert 8BITMIME\(->7BIT (``pass'') +.\" a Adaptive algorithm: see below +.)b +.\"The adaptive algorithm is to accept 8-bit data, +.\"converting it to 8BITMIME only if the receiver understands that, +.\"otherwise just passing it as undeclared 8-bit data; +.\"8BITMIME\(->7BIT conversions are done. +In all cases properly declared 8BITMIME data will be converted to 7BIT +as needed. +.ip ErrorHeader=\fIfile-or-message\fP +[E] +Prepend error messages with the indicated message. +If it begins with a slash, +it is assumed to be the pathname of a file +containing a message (this is the recommended setting). +Otherwise, it is a literal message. +The error file might contain the name, email address, and/or phone number +of a local postmaster who could provide assistance +in to end users. +If the option is missing or null, +or if it names a file which does not exist or which is not readable, +no message is printed. +.ip ErrorMode=\fIx\fP +[e] +Dispose of errors using mode +.i x . +The values for +.i x +are: +.(b +p Print error messages (default) +q No messages, just give exit status +m Mail back errors +w Write back errors (mail if user not logged in) +e Mail back errors and give zero exit stat always +.)b +.ip FallbackMXhost=\fIfallbackhost\fP +[V] +If specified, the +.i fallbackhost +acts like a very low priority MX +on every host. +This is intended to be used by sites with poor network connectivity. +.ip ForkEachJob +[Y] +If set, +deliver each job that is run from the queue in a separate process. +Use this option if you are short of memory, +since the default tends to consume considerable amounts of memory +while the queue is being processed. +.ip ForwardPath=\fIpath\fP +[J] +Set the path for searching for users' .forward files. +The default is +.q $z/.forward . +Some sites that use the automounter may prefer to change this to +.q /var/forward/$u +to search a file with the same name as the user in a system directory. +It can also be set to a sequence of paths separated by colons; +.i sendmail +stops at the first file it can successfully and safely open. +For example, +.q /var/forward/$u:$z/.forward +will search first in /var/forward/\c +.i username +and then in +.i ~username /.forward +(but only if the first file does not exist). +.ip HelpFile=\fIfile\fP +[H] +Specify the help file +for SMTP. +.ip HoldExpensive +[c] +If an outgoing mailer is marked as being expensive, +don't connect immediately. +This requires that queueing be compiled in, +since it will depend on a queue run process to +actually send the mail. +.ip HostsFile=\fIpath\fP +[no short name] +The path to the hosts database, +normally +.q /etc/hosts . +This option is only consulted when sendmail +is canonifying addresses, +and then only when +.q files +is in the +.q hosts +service switch entry. +In particular, this file is +.i never +used when looking up host addresses; +that is under the control of the system +.i gethostbyname (3) +routine. +.ip HostStatusDirectory=\fIpath\fP +[no short name] +The location of the long term host status information. +When set, +information about the status of hosts +(e.g., host down or not accepting connections) +will be shared between all +.i sendmail +processes; +normally, this information is only held within a single queue run. +This option requires a connection cache of at least 1 to function. +If the option begins with a leading `/', +it is an absolute pathname; +otherwise, +it is relative to the mail queue directory. +A suggested value for sites desiring persistent host status is +.q \&.hoststat +(i.e., a subdirectory of the queue directory). +.ip IgnoreDots +[i] +Ignore dots in incoming messages. +This is always disabled (that is, dots are always accepted) +when reading SMTP mail. +.ip LogLevel=\fIn\fP +[L] +Set the log level to +.i n . +Defaults to 9. +.ip M\fIx\|value\fP +[no long version] +Set the macro +.i x +to +.i value . +This is intended only for use from the command line. +The +.b \-M +flag is preferred. +.ip MatchGECOS +[G] +Allow fuzzy matching on the GECOS field. +If this flag is set, +and the usual user name lookups fail +(that is, there is no alias with this name and a +.i getpwnam +fails), +sequentially search the password file +for a matching entry in the GECOS field. +This also requires that MATCHGECOS +be turned on during compilation. +This option is not recommended. +.ip MaxDaemonChildren=\fIN\fP +[no short name] +If set, +.i sendmail +will refuse connections when it has more than +.i N +children processing incoming mail. +This does not limit the number of outgoing connections. +If not set, there is no limit to the number of children -- +that is, the system load averaging controls this. +.ip MaxHopCount=\fIN\fP +[h] +The maximum hop count. +Messages that have been processed more than +.i N +times are assumed to be in a loop and are rejected. +Defaults to 25. +.ip MaxHostStatAge=\fIage\fP +[no short name] +Not yet implemented. +This option specifies how long host status information will be retained. +For example, if a host is found to be down, +connections to that host will not be retried for this interval. +The units default to minutes. +.ip MaxMessageSize=\fIN\fP +[no short name] +Specify the maximum message size +to be advertised in the ESMTP EHLO response. +Messages larger than this will be rejected. +.ip MaxQueueRunSize=\fIN\fP +[no short name] +The maximum number of jobs that will be processed +in a single queue run. +If not set, there is no limit on the size. +If you have very large queues or a very short queue run interval +this could be unstable. +However, since the first +.i N +jobs in queue directory order are run (rather than the +.i N +highest priority jobs) +this should be set as high as possible to avoid +.q losing +jobs that happen to fall late in the queue directory. +.ip MaxRecipientsPerMessage=\fIN\fP +[no short name] +The maximum number of recipients that will be accepted per message +in an SMTP transaction. +Note: setting this too low can interfere with sending mail from +MUAs that use SMTP for initial submission. +If not set, there is no limit on the number of recipients per envelope. +.ip MeToo +[m] +Send to me too, +even if I am in an alias expansion. +.ip MinFreeBlocks=\fIN\fP +[b] +Insist on at least +.i N +blocks free on the filesystem that holds the queue files +before accepting email via SMTP. +If there is insufficient space +.i sendmail +gives a 452 response +to the MAIL command. +This invites the sender to try again later. +.ip MinQueueAge=\fPage\fP +[no short name] +Don't process any queued jobs +that have been in the queue less than the indicated time interval. +This is intended to allow you to get responsiveness +by processing the queue fairly frequently +without thrashing your system by trying jobs too often. +The default units are minutes. +.ip MustQuoteChars=\fIs\fP +[no short name] +Sets the list of characters that must be quoted if used in a full name +that is in the phrase part of a ``phrase <address>'' syntax. +The default is ``\'.''. +The characters ``@,;:\e()[]'' are always added to this list. +.ip NoRecipientAction +[no short name] +The action to take when you receive a message that has no valid +recipient headers (To:, Cc:, Bcc:, or Apparently-To: \(em +the last included for back compatibility with old +.i sendmail s). +It can be +.b None +to pass the message on unmodified, +which violates the protocol, +.b Add-To +to add a To: header with any recipients it can find in the envelope +(which might expose Bcc: recipients), +.b Add-Apparently-To +to add an Apparently-To: header +(this is only for back-compatibility +and is officially deprecated), +.b Add-To-Undisclosed +to add a header +.q "To: undisclosed-recipients:;" +to make the header legal without disclosing anything, +or +.b Add-Bcc +to add an empty Bcc: header. +.ip OldStyleHeaders +[o] +Assume that the headers may be in old format, +i.e., +spaces delimit names. +This actually turns on +an adaptive algorithm: +if any recipient address contains a comma, parenthesis, +or angle bracket, +it will be assumed that commas already exist. +If this flag is not on, +only commas delimit names. +Headers are always output with commas between the names. +Defaults to off. +.ip OperatorChars=\fIcharlist\fP +[$o macro] +The list of characters that are considered to be +.q operators , +that is, characters that delimit tokens. +All operator characters are tokens by themselves; +sequences of non-operator characters are also tokens. +White space characters separate tokens +but are not tokens themselves \(em for example, +.q AAA.BBB +has three tokens, but +.q "AAA BBB" +has two. +If not set, OperatorChars defaults to +.q \&.\|:\|@\|[\|] ; +additionally, the characters +.q (\|)\|<\|>\|,\|; +are always operators. +.ip PostmasterCopy=\fIpostmaster\fP +[P] +If set, +copies of error messages will be sent to the named +.i postmaster . +Only the header of the failed message is sent. +Since most errors are user problems, +this is probably not a good idea on large sites, +and arguably contains all sorts of privacy violations, +but it seems to be popular with certain operating systems vendors. +Defaults to no postmaster copies. +.ip PrivacyOptions=\fI\|opt,opt,...\fP +[p] +Set the privacy +.i opt ions. +``Privacy'' is really a misnomer; +many of these are just a way of insisting on stricter adherence +to the SMTP protocol. +The +.i opt ions +can be selected from: +.(b +.ta \w'needvrfyhelo'u+3n +public Allow open access +needmailhelo Insist on HELO or EHLO command before MAIL +needexpnhelo Insist on HELO or EHLO command before EXPN +noexpn Disallow EXPN entirely +needvrfyhelo Insist on HELO or EHLO command before VRFY +novrfy Disallow VRFY entirely +noetrn Disallow ETRN entirely +noverb Disallow VERB entirely +restrictmailq Restrict mailq command +restrictqrun Restrict \-q command line flag +noreceipts Don't return success DSNs\** +goaway Disallow essentially all SMTP status queries +authwarnings Put X-Authentication-Warning: headers in messages +.)b +.(f +\**N.B.: +the +.b noreceipts +flag causes +.i sendmail +to violate RFC 1891, +which requires that return receipts be provided +if Delivery Status Notifications are supported. +.)f +The +.q goaway +pseudo-flag sets all flags except +.q restrictmailq +and +.q restrictqrun . +If mailq is restricted, +only people in the same group as the queue directory +can print the queue. +If queue runs are restricted, +only root and the owner of the queue directory +can run the queue. +Authentication Warnings add warnings about various conditions +that may indicate attempts to spoof the mail system, +such as using an non-standard queue directory. +.ip QueueDirectory=\fIdir\fP +[Q] +Use the named +.i dir +as the queue directory. +.ip QueueFactor=\fIfactor\fP +[q] +Use +.i factor +as the multiplier in the map function +to decide when to just queue up jobs rather than run them. +This value is divided by the difference between the current load average +and the load average limit +(\c +.b QueueLA +option) +to determine the maximum message priority +that will be sent. +Defaults to 600000. +.ip QueueLA=\fILA\fP +[x] +When the system load average exceeds +.i LA , +just queue messages +(i.e., don't try to send them). +Defaults to 8. +.ip QueueSortOrder=\fIalgorithm\fP +[no short name] +Sets the +.i algorithm +used for sorting the queue. +Only the first character of the value is used. +Legal values are +.q host +(to order by the name of the first host name of the first recipient), +.q time +(to order by the submission time), +and +.q priority +(to order by message priority). +Host ordering makes better use of the connection cache, +but may tend to process low priority messages +that go to a single host +over high priority messages that go to several hosts; +it probably shouldn't be used on slow network links. +Time ordering is almost always a bad idea, +since it allows large, bulk mail to go out +before smaller, personal mail, +but may have applicability on some hosts with very fast connections. +Priority ordering is the default. +.ip QueueTimeout=\fItimeout\fP +[T] +A synonym for +.q Timeout.queuereturn . +Use that form instead of the +.q QueueTimeout +form. +.ip ResolverOptions=\fIoptions\fP +[I] +Set resolver options. +Values can be set using +.b + \c +.i flag +and cleared using +.b \- \c +.i flag ; +the +.i flag s +can be +.q debug , +.q aaonly , +.q usevc , +.q primary , +.q igntc , +.q recurse , +.q defnames , +.q stayopen , +or +.q dnsrch . +The string +.q HasWildcardMX +(without a +.b + +or +.b \- ) +can be specified to turn off matching against MX records +when doing name canonifications. +.b N.B. +Prior to 8.7, +this option indicated that the name server be responding +in order to accept addresses. +This has been replaced by checking to see +if the +.q dns +method is listed in the service switch entry for the +.q hosts +service. +.ip RunAsUser=\fIuser\fP +[no short name] +The +.i user +parameter may be a user name +(looked up in +.i /etc/passwd ) +or a numeric user id; +either form can have +.q ":group" +attached +(where group can be numeric or symbolic). +If set to a non-zero (non-root) value, +.i sendmail +will change to this user id shortly after startup\**. +.(f +\**When running as a daemon, +it changes to this user after accepting a connection +but before reading any +.sm SMTP +commands. +.)f +This avoids a certain class of security problems. +However, this means that all +.q \&.forward +and +.q :include: +files must be readable by the indicated +.i user , +and on systems that don't support the saved uid bit properly, +all files to be written must be writable by +.i user +and all programs will be executed by +.i user . +It is also incompatible with the +.b SafeFileEnvironment +option. +In other words, it may not actually add much to security on an average system, +and may in fact detract from security +(because other file permissions must be loosened). +However, it should be useful on firewalls and other +places where users don't have accounts and the aliases file is +well constrained. +.ip RecipientFactor=\fIfact\fP +[y] +The indicated +.i fact or +is added to the priority (thus +.i lowering +the priority of the job) +for each recipient, +i.e., this value penalizes jobs with large numbers of recipients. +Defaults to 30000. +.ip RefuseLA=\fILA\fP +[X] +When the system load average exceeds +.i LA , +refuse incoming SMTP connections. +Defaults to 12. +.ip RetryFactor=\fIfact\fP +[Z] +The +.i fact or +is added to the priority +every time a job is processed. +Thus, +each time a job is processed, +its priority will be decreased by the indicated value. +In most environments this should be positive, +since hosts that are down are all too often down for a long time. +Defaults to 90000. +.ip SafeFileEnvironment=\fIdir\fP +[no short name] +If this option is set, +.i sendmail +will do a +.i chroot (2) +call into the indicated +.i dir ectory +before doing any file writes. +If the file name specified by the user begins with +.i dir , +that partial path name will be stripped off before writing, +so (for example) +if the SafeFileEnvironment variable is set to +.q /safe +then aliases of +.q /safe/logs/file +and +.q /logs/file +actually indicate the same file. +Additionally, if this option is set, +.i sendmail +refuses to deliver to symbolic links. +.ip SaveFromLine +[f] +Save +Unix-style +.q From +lines at the front of headers. +Normally they are assumed redundant +and discarded. +.ip SendMIMEErrors +[j] +If set, send error messages in MIME format +(see RFC2045 and RFC1344 for details). +If disabled, +.i sendmail +will not return the DSN keyword in response to an EHLO +and will not do Delivery Status Notification processing as described in +RFC1891. +.ip ServiceSwitchFile=\fIfilename\fP +[no short name] +If your host operating system has a service switch abstraction +(e.g., /etc/nsswitch.conf on Solaris +or /etc/svc.conf on Ultrix and DEC OSF/1) +that service will be consulted and this option is ignored. +Otherwise, this is the name of a file +that provides the list of methods used to implement particular services. +The syntax is a series of lines, +each of which is a sequence of words. +The first word is the service name, +and following words are service types. +The services that +.i sendmail +consults directly are +.q aliases +and +.q hosts. +Service types can be +.q dns , +.q nis , +.q nisplus , +or +.q files +(with the caveat that the appropriate support +must be compiled in +before the service can be referenced). +If ServiceSwitchFile is not specified, it defaults to /etc/service.switch. +If that file does not exist, the default switch is: +.(b +aliases files +hosts dns nis files +.)b +The default file is +.q /etc/service.switch . +.ip SevenBitInput +[7] +Strip input to seven bits for compatibility with old systems. +This shouldn't be necessary. +.ip SingleLineFromHeader +[no short name] +If set, From: lines that have embedded newlines are unwrapped +onto one line. +This is to get around a botch in Lotus Notes +that apparently cannot understand legally wrapped RFC822 headers. +.ip SingleThreadDelivery +[no short name] +If set, a client machine will never try to open two SMTP connections +to a single server machine at the same time, +even in different processes. +That is, if another +.i sendmail +is already talking to some host a new +.i sendmail +will not open another connection. +This property is of mixed value; +although this reduces the load on the other machine, +it can cause mail to be delayed +(for example, if one +.i sendmail +is delivering a huge message, other +.i sendmail s +won't be able to send even small messages). +Also, it requires another file descriptor +(for the lock file) +per connection, so you may have to reduce the +.b ConnectionCacheSize +option to avoid running out of per-process file descriptors. +Requires the +.b HostStatusDirectory +option. +.ip SmtpGreetingMessage=\fImessage\fP +[$e macro] +The message printed when the SMTP server starts up. +Defaults to +.q "$j Sendmail $v ready at $b". +.ip StatusFile=\fIfile\fP +[S] +Log summary statistics in the named +.i file . +If not set, +no summary statistics are saved. +This file does not grow in size. +It can be printed using the +.i mailstats (8) +program. +.ip SuperSafe +[s] +Be super-safe when running things, +i.e., +always instantiate the queue file, +even if you are going to attempt immediate delivery. +.i Sendmail +always instantiates the queue file +before returning control to the client +under any circumstances. +This should really +.i always +be set. +.ip TempFileMode=\fImode\fP +[F] +The file mode for queue files. +It is interpreted in octal by default. +Defaults to 0600. +.ip Timeout.\fItype\fP=\|\fItimeout\fP +[r; subsumes old T option as well] +Set timeout values. +The actual timeout is indicated by the +.i type . +The recognized timeouts and their default values, and their +minimum values specified in RFC 1123 section 5.3.2 are: +.(b +.ta \w'datafinal'u+3n +initial wait for initial greeting message [5m, 5m] +helo reply to HELO or EHLO command [5m, none] +mail reply to MAIL command [10m, 5m] +rcpt reply to RCPT command [1h, 5m] +datainit reply to DATA command [5m, 2m] +datablock data block read [1h, 3m] +datafinal reply to final ``.'' in data [1h, 10m] +rset reply to RSET command [5m, none] +quit reply to QUIT command [2m, none] +misc reply to NOOP and VERB commands [2m, none] +ident IDENT protocol timeout [30s, none] +fileopen\(dg timeout on opening .forward and :include: files [60s, none] +command\(dg command read [1h, 5m] +queuereturn\(dg how long until a message is returned [5d, 5d] +queuewarn\(dg how long until a warning is sent [none, none] +hoststatus\(dg how long until host status is ``stale'' [30m, none] +.)b +All but those marked with a dagger (\(dg) +apply to client SMTP. +If the message is submitted using the +.sm NOTIFY +.sm SMTP +extension, +warning messages will only be sent if +.sm NOTIFY=DELAY +is specified. +The queuereturn and queuewarn timeouts +can be further qualified with a tag based on the Precedence: field +in the message; +they must be one of +.q urgent +(indicating a positive non-zero precedence) +.q normal +(indicating a zero precedence), or +.q non-urgent +(indicating negative precedences). +For example, setting +.q Timeout.queuewarn.urgent=1h +sets the warning timeout for urgent messages only +to one hour. +The default if no precedence is indicated +is to set the timeout for all precedences. +.ip TimeZoneSpec=\fItzinfo\fP +[t] +Set the local time zone info to +.i tzinfo +\*- for example, +.q PST8PDT . +Actually, if this is not set, +the TZ environment variable is cleared (so the system default is used); +if set but null, the user's TZ variable is used, +and if set and non-null the TZ variable is set to this value. +.ip TryNullMXList +[w] +If this system is the +.q best +(that is, lowest preference) +MX for a given host, +its configuration rules should normally detect this situation +and treat that condition specially +by forwarding the mail to a UUCP feed, +treating it as local, +or whatever. +However, in some cases (such as Internet firewalls) +you may want to try to connect directly to that host +as though it had no MX records at all. +Setting this option causes +.i sendmail +to try this. +The downside is that errors in your configuration +are likely to be diagnosed as +.q "host unknown" +or +.q "message timed out" +instead of something more meaningful. +This option is disrecommended. +.ip UnixFromLine=\fIfromline\fP +[$l macro] +Defines the format used when +.i sendmail +must add a UNIX-style From_ line +(that is, a line beginning +.q From<space>user ). +Defaults to +.q "From $g $d" . +Don't change this unless your system uses a different UNIX mailbox format +(very unlikely). +.ip UnsafeGroupWrites +[no short name] +If set, +:include: and .forward files that are group writable are considered +.q unsafe , +that is, +they cannot reference programs or write directly to files. +World writable :include: and .forward files +are always unsafe.. +.ip UseErrorsTo +[l] +If there is an +.q Errors-To: +header, send error messages to the addresses listed there. +They normally go to the envelope sender. +Use of this option causes +.i sendmail +to violate RFC 1123. +This option is disrecommended and deprecated. +.ip UserDatabaseSpec=\fIudbspec\fP +[U] +The user database specification. +.ip UserSubmission +[no short name] +This is an initial submission directly from a Mail User Agent. +This can be set in the configuration file if you have +MUAs that don't pass the +.b \-U +flag or use the +XUSR +ESMTP extension, +but some relayed mail may get inappropriately rewritten if you do. +.ip Verbose +[v] +Run in verbose mode. +If this is set, +.i sendmail +adjusts options +.b HoldExpensive +(old +.b c ) +and +.b DeliveryMode +(old +.b d ) +so that all mail is delivered completely +in a single job +so that you can see the entire delivery process. +Option +.b Verbose +should +.i never +be set in the configuration file; +it is intended for command line use only. +.lp +All options can be specified on the command line using the +\-O or \-o flag, +but most will cause +.i sendmail +to relinquish its setuid permissions. +The options that will not cause this are +MinFreeBlocks [b], +DeliveryMode [d], +ErrorMode [e], +IgnoreDots [i], +LogLevel [L], +MeToo [m], +OldStyleHeaders [o], +PrivacyOptions [p], +Timeouts [r], +SuperSafe [s], +Verbose [v], +CheckpointInterval [C], +and +SevenBitInput [7]. +Also, M (define macro) when defining the r or s macros +is also considered +.q safe . +.sh 2 "P \*- Precedence Definitions" +.pp +Values for the +.q "Precedence:" +field may be defined using the +.b P +control line. +The syntax of this field is: +.(b +\fBP\fP\fIname\fP\fB=\fP\fInum\fP +.)b +When the +.i name +is found in a +.q Precedence: +field, +the message class is set to +.i num . +Higher numbers mean higher precedence. +Numbers less than zero +have the special property +that if an error occurs during processing +the body of the message will not be returned; +this is expected to be used for +.q "bulk" +mail such as through mailing lists. +The default precedence is zero. +For example, +our list of precedences is: +.(b +Pfirst-class=0 +Pspecial-delivery=100 +Plist=\-30 +Pbulk=\-60 +Pjunk=\-100 +.)b +People writing mailing list exploders +are encouraged to use +.q "Precedence: list" . +Older versions of +.i sendmail +(which discarded all error returns for negative precedences) +didn't recognize this name, giving it a default precedence of zero. +This allows list maintainers to see error returns +on both old and new versions of +.i sendmail . +.sh 2 "V \*- Configuration Version Level" +.pp +To provide compatibility with old configuration files, +the +.b V +line has been added to define some very basic semantics +of the configuration file. +These are not intended to be long term supports; +rather, they describe compatibility features +which will probably be removed in future releases. +.pp +.b N.B.: +these version +.i levels +have nothing +to do with the version +.i number +on the files. +For example, +as of this writing +version 8 config files +(specifically, 8.9) +used version level 7 configurations. +.pp +.q Old +configuration files are defined as version level one. +Version level two files make the following changes: +.np +Host name canonification ($[ ... $]) +appends a dot if the name is recognized; +this gives the config file a way of finding out if anything matched. +(Actually, this just initializes the +.q host +map with the +.q \-a. +flag \*- you can reset it to anything you prefer +by declaring the map explicitly.) +.np +Default host name extension is consistent throughout processing; +version level one configurations turned off domain extension +(that is, adding the local domain name) +during certain points in processing. +Version level two configurations are expected to include a trailing dot +to indicate that the name is already canonical. +.np +Local names that are not aliases +are passed through a new distinguished ruleset five; +this can be used to append a local relay. +This behaviour can be prevented by resolving the local name +with an initial `@'. +That is, something that resolves to a local mailer and a user name of +.q vikki +will be passed through ruleset five, +but a user name of +.q @vikki +will have the `@' stripped, +will not be passed through ruleset five, +but will otherwise be treated the same as the prior example. +The expectation is that this might be used to implement a policy +where mail sent to +.q vikki +was handled by a central hub, +but mail sent to +.q vikki@localhost +was delivered directly. +.pp +Version level three files +allow # initiated comments on all lines. +Exceptions are backslash escaped # marks +and the $# syntax. +.pp +Version level four configurations +are completely equivalent to level three +for historical reasons. +.pp +Version level five configuration files +change the default definition of +.b $w +to be just the first component of the hostname. +.pp +Version level six configuration files +change many of the local processing options +(such as aliasing and matching the beginning of the address for +`|' characters) +to be mailer flags; +this allows fine-grained control over the special local processing. +Level six configuration files may also use long option names. +The +.b ColonOkInAddr +option (to allow colons in the local-part of addresses) +defaults +.b on +for lower numbered configuration files; +the configuration file requires some additional intelligence +to properly handle the RFC 822 group construct. +.pp +Version level seven configuration files +used new option names to replace old macros +(\c +.b $e +became +.b SmtpGreeetingMessage , +.b $l +became +.b UnixFromLine , +and +.b $o +became +.b OperatorChars . +Also, prior to version seven, +the +.b F=q +flag (use 250 instead of 252 return value for +.sm "SMTP VRFY" +commands) +was assumed. +.pp +The +.b V +line may have an optional +.b / \c +.i vendor +to indicate that this configuration file uses modifications +specific to a particular vendor\**. +.(f +\**And of course, vendors are encouraged to add themselves +to the list of recognized vendors by editing the routine +.i setvendor +in +.i conf.c . +Please send e-mail to sendmail@Sendmail.ORG +to register your vendor dialect. +.)f +You may use +.q /Berkeley +to emphasize that this configuration file +uses the Berkeley dialect of +.i sendmail . +.sh 2 "K \*- Key File Declaration" +.pp +Special maps can be defined using the line: +.(b +Kmapname mapclass arguments +.)b +The +.i mapname +is the handle by which this map is referenced in the rewriting rules. +The +.i mapclass +is the name of a type of map; +these are compiled in to +.i sendmail . +The +.i arguments +are interpreted depending on the class; +typically, +there would be a single argument naming the file containing the map. +.pp +Maps are referenced using the syntax: +.(b +$( \fImap\fP \fIkey\fP $@ \fIarguments\fP $: \fIdefault\fP $) +.)b +where either or both of the +.i arguments +or +.i default +portion may be omitted. +The +.i "$@ arguments" +may appear more than once. +The indicated +.i key +and +.i arguments +are passed to the appropriate mapping function. +If it returns a value, it replaces the input. +If it does not return a value and the +.i default +is specified, the +.i default +replaces the input. +Otherwise, the input is unchanged. +.pp +The +.i arguments +are passed to the map for arbitrary use. +Most map classes can interpolate these arguments +into their values using the syntax +.q %\fIn\fP +(where +.i n +is a digit) +to indicate the corresponding +.i argument . +Argument +.q %0 +indicates the database key. +For example, the rule +.(b +.ta 1.5i +R$\- ! $+ $: $(uucp $1 $@ $2 $: %1 @ %0 . UUCP $) +.)b +Looks up the UUCP name in a (user defined) UUCP map; +if not found it turns it into +.q \&.UUCP +form. +The database might contain records like: +.(b +decvax %1@%0.DEC.COM +research %1@%0.ATT.COM +.)b +Note that +.i default +clauses never do this mapping. +.pp +The built in map with both name and class +.q host +is the host name canonicalization lookup. +Thus, +the syntax: +.(b +$(host \fIhostname\fP$) +.)b +is equivalent to: +.(b +$[\fIhostname\fP$] +.)b +.pp +There are many defined classes. +.ip dbm +Database lookups using the ndbm(3) library. +.i Sendmail +must be compiled with +.b NDBM +defined. +.ip btree +Database lookups using the btree interface to the Berkeley DB +library. +.i Sendmail +must be compiled with +.b NEWDB +defined. +.ip hash +Database lookups using the hash interface to the Berkeley DB +library. +.i Sendmail +must be compiled with +.b NEWDB +defined. +.ip nis +NIS lookups. +.i Sendmail +must be compiled with +.b NIS +defined. +.ip nisplus +NIS+ lookups. +.i Sendmail +must be compiled with +.b NISPLUS +defined. +The argument is the name of the table to use for lookups, +and the +.b \-k +and +.b \-v +flags may be used to set the key and value columns respectively. +.ip hesiod +Hesiod lookups. +.i Sendmail +must be compiled with +.b HESIOD +defined. +.ip ldapx +LDAP X500 directory lookups. +.i Sendmail +must be compiled with +.b LDAPMAP +defined. +The map supports most of the standard arguments +and most of the command line arguments of the +.i ldapsearch +program. +.ip netinfo +NeXT NetInfo lookups. +.i Sendmail +must be compiled with +.b NETINFO +defined. +.ip text +Text file lookups. +The format of the text file is defined by the +.b \-k +(key field number), +.b \-v +(value field number), +and +.b \-z +(field delimiter) +flags. +.ip stab +Internal symbol table lookups. +Used internally for aliasing. +.ip implicit +Really should be called +.q alias +\(em this is used to get the default lookups +for alias files, +and is the default if no class is specified for alias files. +.ip user +Looks up users using +.i getpwnam (3). +The +.b \-v +flag can be used to specify the name of the field to return +(although this is normally used only to check the existence +of a user). +.ip host +Canonifies host domain names. +Given a host name it calls the name server +to find the canonical name for that host. +.ip bestmx +Returns the best MX record for a host name given as the key. +The current machine is always preferred \*- +that is, if the current machine is one of the hosts listed as a +lowest-preference MX record, then it will be guaranteed to be returned. +This can be used to find out if this machine is the target for an MX record, +and mail can be accepted on that basis. +If the +.b \-z +flag is given, then all MX names are returned, +separated by the given delimiter. +.ip sequence +The arguments on the `K' line are a list of maps; +the resulting map searches the argument maps in order +until it finds a match for the indicated key. +For example, if the key definition is: +.(b +Kmap1 ... +Kmap2 ... +Kseqmap sequence map1 map2 +.)b +then a lookup against +.q seqmap +first does a lookup in map1. +If that is found, it returns immediately. +Otherwise, the same key is used for map2. +.ip switch +Much like the +.q sequence +map except that the order of maps is determined by the service switch. +The argument is the name of the service to be looked up; +the values from the service switch are appended to the map name +to create new map names. +For example, consider the key definition: +.(b +Kali switch aliases +.)b +together with the service switch entry: +.(b +aliases nis files +.)b +This causes a query against the map +.q ali +to search maps named +.q ali.nis +and +.q ali.files +in that order. +.ip dequote +Strip double quotes (") from a name. +It does not strip backslashes, +and will not strip quotes if the resulting string +would contain unscannable syntax +(that is, basic errors like unbalanced angle brackets; +more sophisticated errors such as unknown hosts are not checked). +The intent is for use when trying to accept mail from systems such as +DECnet +that routinely quote odd syntax such as +.(b +"49ers::ubell" +.)b +A typical usage is probably something like: +.(b +Kdequote dequote + +\&... + +R$\- $: $(dequote $1 $) +R$\- $+ $: $>3 $1 $2 +.)b +Care must be taken to prevent unexpected results; +for example, +.(b +"|someprogram < input > output" +.)b +will have quotes stripped, +but the result is probably not what you had in mind. +Fortunately these cases are rare. +.ip regex +The map definition on the +.b K +line contains a regular expression. +Any key input is compared to that expression using the +POSIX regular expressions routines regcomp(), regerr(), and regexec(). +Refer to the documentation for those routines for more information +about the regular expression matching. +No rewriting of the key is done if the +.b \-m +flag is used. Without it, the key is discarded or if +.b \-s +if used, it is substituted by the substring matches, delimited by +.b $| +or the string specified with the the +.b \-d +flag. The flags availble for the map are +.(b +-n not +-f case sensitive +-b basic regular expressions + (default is extended) +-s substring match +-d set the delimiter used for -s +-a append string to key +-m match only, do not + replace/discard value +.)b +The +.b \-s flag can include an optional parameter which can be used +to select the substrings in the result of the lookup. For example, +.(b +-s1,3,4 +.)b +.ip program +The arguments on the +.b K +line are the pathname to a program and any initial parameters to be passed. +When the map is called, +the key is added to the initial parameters +and the program is invoked +as the default user/group id. +The first line of standard output is returned as the value of the lookup. +This has many potential security problems, +and has terrible performance; +it should be used only when absolutely necessary. +.pp +Most of these accept as arguments the same optional flags +and a filename +(or a mapname for NIS; +the filename is the root of the database path, +so that +.q .db +or some other extension appropriate for the database type +will be added to get the actual database name). +Known flags are: +.ip "\-o" +Indicates that this map is optional \*- that is, +if it cannot be opened, +no error is produced, +and +.i sendmail +will behave as if the map existed but was empty. +.ip "\-N, \-O" +If neither +.b \-N +or +.b \-O +are specified, +.i sendmail +uses an adaptive algorithm to decide whether or not to look for null bytes +on the end of keys. +It starts by trying both; +if it finds any key with a null byte it never tries again without a null byte +and vice versa. +If +.b \-N +is specified it never tries without a null byte and +if +.b \-O +is specified it never tries with a null byte. +Setting one of +these can speed matches but are never necessary. +If both +.b \-N +and +.b \-O +are specified, +.i sendmail +will never try any matches at all \(em +that is, everything will appear to fail. +.ip "\-a\fIx\fP" +Append the string +.i x +on successful matches. +For example, the default +.i host +map appends a dot on successful matches. +.ip "\-T\fIx\fP" +Append the string +.i x +on temporary failures. +For example, +.i x +would be appended if a DNS lookup returned +.q "server failed" +or an NIS lookup could not locate a server. +See also the +.b \-t +flag. +.ip "\-f" +Do not fold upper to lower case before looking up the key. +.ip "\-m" +Match only (without replacing the value). +If you only care about the existence of a key and not the value +(as you might when searching the NIS map +.q hosts.byname +for example), +this flag prevents the map from substituting the value. +However, +The \-a argument is still appended on a match, +and the default is still taken if the match fails. +.ip "\-k\fIkeycol\fP" +The key column name (for NIS+) or number +(for text lookups). +For LDAP maps this is a filter string +passed to printf with a %s where the string to be +.q "mapped" +is inserted. +.ip "\-v\fIvalcol\fP" +The value column name (for NIS+) or number +(for text lookups). +For LDAP maps this is the name of the +attribute to be returned. +.ip "\-z\fIdelim\fP" +The column delimiter (for text lookups). +It can be a single character or one of the special strings +.q \|\en +or +.q \|\et +to indicate newline or tab respectively. +If omitted entirely, +the column separator is any sequence of whitespace. +.ip "\-t" +Normally, when a map attempts to do a lookup +and the server fails +(e.g., +.i sendmail +couldn't contact any name server; +this is +.i not +the same as an entry not being found in the map), +the message being processed is queued for future processing. +The +.b \-t +flag turns off this behaviour, +letting the temporary failure (server down) +act as though it were a permanent failure (entry not found). +It is particularly useful for DNS lookups, +where someone else's misconfigured name server can cause problems +on your machine. +However, care must be taken to ensure that you don't bounce mail +that would be resolved correctly if you tried again. +A common strategy is to forward such mail +to another, possibly better connected, mail server. +.ip "\-s\fIspacesub\fP +For the dequote map only, +the character to use to replace space characters +after a successful dequote. +.ip "\-q" +Don't dequote the key before lookup. +.ip "\-A" +When rebuilding an alias file, +the +.b \-A +flag causes duplicate entries in the text version +to be merged. +For example, two entries: +.(b +list: user1, user2 +list: user3 +.)b +would be treated as though it were the single entry +.(b +list: user1, user2, user3 +.)b +in the presence of the +.b \-A +flag. +.pp +The +.i dbm +map appends the strings +.q \&.pag +and +.q \&.dir +to the given filename; +the +.i hash +and +.i btree +maps append +.q \&.db . +For example, the map specification +.(b +Kuucp dbm \-o \-N /usr/lib/uucpmap +.)b +specifies an optional map named +.q uucp +of class +.q dbm ; +it always has null bytes at the end of every string, +and the data is located in +/usr/lib/uucpmap.{dir,pag}. +.pp +The program +.i makemap (8) +can be used to build any of the three database-oriented maps. +It takes the following flags: +.ip \-f +Do not fold upper to lower case in the map. +.ip \-N +Include null bytes in keys. +.ip \-o +Append to an existing (old) file. +.ip \-r +Allow replacement of existing keys; +normally, re-inserting an existing key is an error. +.ip \-v +Print what is happening. +.lp +The +.i sendmail +daemon does not have to be restarted to read the new maps +as long as you change them in place; +file locking is used so that the maps won't be read +while they are being updated.\** +.(f +\**That is, don't create new maps and then use +.i mv (1) +to move them into place. +Since the maps are already open +the new maps will never be seen. +.)f +.pp +New classes can be added in the routine +.b setupmaps +in file +.b conf.c . +.sh 2 "The User Database" +.pp +If you have a version of +.i sendmail +with the user database package +compiled in, +the handling of sender and recipient addresses +is modified. +.pp +The location of this database is controlled with the +.b UserDatabaseSpec +option. +.sh 3 "Structure of the user database" +.pp +The database is a sorted (BTree-based) structure. +User records are stored with the key: +.(b +\fIuser-name\fP\fB:\fP\fIfield-name\fP +.)b +The sorted database format ensures that user records are clustered together. +Meta-information is always stored with a leading colon. +.pp +Field names define both the syntax and semantics of the value. +Defined fields include: +.nr ii 1i +.ip maildrop +The delivery address for this user. +There may be multiple values of this record. +In particular, +mailing lists will have one +.i maildrop +record for each user on the list. +.ip "mailname" +The outgoing mailname for this user. +For each outgoing name, +there should be an appropriate +.i maildrop +record for that name to allow return mail. +See also +.i :default:mailname . +.ip mailsender +Changes any mail sent to this address to have the indicated envelope sender. +This is intended for mailing lists, +and will normally be the name of an appropriate -request address. +It is very similar to the owner-\c +.i list +syntax in the alias file. +.ip fullname +The full name of the user. +.ip office-address +The office address for this user. +.ip office-phone +The office phone number for this user. +.ip office-fax +The office FAX number for this user. +.ip home-address +The home address for this user. +.ip home-phone +The home phone number for this user. +.ip home-fax +The home FAX number for this user. +.ip project +A (short) description of the project this person is affiliated with. +In the University this is often just the name of their graduate advisor. +.ip plan +A pointer to a file from which plan information can be gathered. +.pp +As of this writing, +only a few of these fields are actually being used by +.i sendmail : +.i maildrop +and +.i mailname . +A +.i finger +program that uses the other fields is planned. +.sh 3 "User database semantics" +.pp +When the rewriting rules submit an address to the local mailer, +the user name is passed through the alias file. +If no alias is found (or if the alias points back to the same address), +the name (with +.q :maildrop +appended) +is then used as a key in the user database. +If no match occurs (or if the maildrop points at the same address), +forwarding is tried. +.pp +If the first token of the user name returned by ruleset 0 +is an +.q @ +sign, the user database lookup is skipped. +The intent is that the user database will act as a set of defaults +for a cluster (in our case, the Computer Science Division); +mail sent to a specific machine should ignore these defaults. +.pp +When mail is sent, +the name of the sending user is looked up in the database. +If that user has a +.q mailname +record, +the value of that record is used as their outgoing name. +For example, I might have a record: +.(b +eric:mailname Eric.Allman@CS.Berkeley.EDU +.)b +This would cause my outgoing mail to be sent as Eric.Allman. +.pp +If a +.q maildrop +is found for the user, +but no corresponding +.q mailname +record exists, +the record +.q :default:mailname +is consulted. +If present, this is the name of a host to override the local host. +For example, in our case we would set it to +.q CS.Berkeley.EDU . +The effect is that anyone known in the database +gets their outgoing mail stamped as +.q user@CS.Berkeley.EDU , +but people not listed in the database use the local hostname. +.sh 3 "Creating the database\**" +.(f +\**These instructions are known to be incomplete. +A future version of the user database is planned +including things such as finger service \*- and good documentation. +.)f +.pp +The user database is built from a text file +using the +.i makemap +utility +(in the distribution in the makemap subdirectory). +The text file is a series of lines corresponding to userdb records; +each line has a key and a value separated by white space. +The key is always in the format described above \*- +for example: +.(b +eric:maildrop +.)b +This file is normally installed in a system directory; +for example, it might be called +.i /etc/userdb . +To make the database version of the map, run the program: +.(b +makemap btree /etc/userdb.db < /etc/userdb +.)b +Then create a config file that uses this. +For example, using the V8 M4 configuration, include the +following line in your .mc file: +.(b +define(\`confUSERDB_SPEC\', /etc/userdb.db) +.)b +.sh 1 "OTHER CONFIGURATION" +.pp +There are some configuration changes that can be made by +recompiling +.i sendmail . +This section describes what changes can be made +and what has to be modified to make them. +In most cases this should be unnecessary +unless you are porting +.i sendmail +to a new environment. +.sh 2 "Parameters in BuildTools/OS/$oscf" +.pp +These parameters are intended to describe the compilation environment, +not site policy, +and should normally be defined in the operating system +configuration file. +.b "This section needs a complete rewrite." +.ip NDBM +If set, +the new version of the DBM library +that allows multiple databases will be used. +If neither NDBM nor NEWDB are set, +a much less efficient method of alias lookup is used. +.ip NEWDB +If set, use the new database package from Berkeley (from 4.4BSD). +This package is substantially faster than DBM or NDBM. +If NEWDB and NDBM are both set, +.i sendmail +will read DBM files, +but will create and use NEWDB files. +.ip NIS +Include support for NIS. +If set together with +.i both +NEWDB and NDBM, +.i sendmail +will create both DBM and NEWDB files if and only if +an alias file includes the substring +.q /yp/ +in the name. +This is intended for compatibility with Sun Microsystems' +.i mkalias +program used on YP masters. +.ip NISPLUS +Compile in support for NIS+. +.ip NETINFO +Compile in support for NetInfo (NeXT stations). +.ip LDAPMAP +Compile in support for LDAP X500 queries. +Requires libldap and liblber +from the Umich LDAP 3.2 or 3.3 release. +.ip HESIOD +Compile in support for Hesiod. +.ip _PATH_SENDMAILCF +The pathname of the sendmail.cf file. +.ip _PATH_SENDMAILPID +The pathname of the sendmail.pid file. +.pp +There are also several compilation flags to indicate the environment +such as +.q _AIX3 +and +.q _SCO_unix_ . +See the src/README +file for the latest scoop on these flags. +.sh 2 "Parameters in src/conf.h" +.pp +Parameters and compilation options +are defined in conf.h. +Most of these need not normally be tweaked; +common parameters are all in sendmail.cf. +However, the sizes of certain primitive vectors, etc., +are included in this file. +The numbers following the parameters +are their default value. +.pp +This document is not the best source of information +for compilation flags in conf.h \(em +see src/README or src/conf.h itself. +.nr ii 1.2i +.ip "MAXLINE [2048]" +The maximum line length of any input line. +If message lines exceed this length +they will still be processed correctly; +however, header lines, +configuration file lines, +alias lines, +etc., +must fit within this limit. +.ip "MAXNAME [256]" +The maximum length of any name, +such as a host or a user name. +.ip "MAXPV [40]" +The maximum number of parameters to any mailer. +This limits the number of recipients that may be passed in one transaction. +It can be set to any arbitrary number above about 10, +since +.i sendmail +will break up a delivery into smaller batches as needed. +A higher number may reduce load on your system, however. +.ip "MAXATOM [100]" +The maximum number of atoms +(tokens) +in a single address. +For example, +the address +.q "eric@CS.Berkeley.EDU" +is seven atoms. +.ip "MAXMAILERS [25]" +The maximum number of mailers that may be defined +in the configuration file. +.ip "MAXRWSETS [200]" +The maximum number of rewriting sets +that may be defined. +The first half of these are reserved for numeric specification +(e.g., ``S92''), +while the upper half are reserved for auto-numbering +(e.g., ``Sfoo''). +Thus, with a value of 200 an attempt to use ``S99'' will succeed, +but ``S100'' will fail. +.ip "MAXPRIORITIES [25]" +The maximum number of values for the +.q Precedence: +field that may be defined +(using the +.b P +line in sendmail.cf). +.ip "MAXUSERENVIRON [100]" +The maximum number of items in the user environment +that will be passed to subordinate mailers. +.ip "MAXMXHOSTS [100]" +The maximum number of MX records we will accept for any single host. +.ip "MAXALIASDB [12]" +The maximum number of alias databases that can be open at any time. +Note that there may also be an open file limit. +.ip "MAXMAPSTACK [12]" +The maximum number of maps that may be "stacked" in a +.b sequence +class map. +.ip "MAXMIMEARGS [20]" +The maximum number of arguments in a MIME Content-Type: header; +additional arguments will be ignored. +.ip "MAXMIMENESTING [20]" +The maximum depth to which MIME messages may be nested +(that is, nested Message or Multipart documents; +this does not limit the number of components in a single Multipart document). +.lp +A number of other compilation options exist. +These specify whether or not specific code should be compiled in. +Ones marked with \(dg +are 0/1 valued. +.nr ii 1.2i +.ip NETINET\(dg +If set, +support for Internet protocol networking is compiled in. +Previous versions of +.i sendmail +referred to this as +.sm DAEMON ; +this old usage is now incorrect. +Defaults on; +turn it off in the Makefile +if your system doesn't support the Internet protocols. +.ip NETISO\(dg +If set, +support for ISO protocol networking is compiled in +(it may be appropriate to #define this in the Makefile instead of conf.h). +.ip LOG +If set, +the +.i syslog +routine in use at some sites is used. +This makes an informational log record +for each message processed, +and makes a higher priority log record +for internal system errors. +.b "STRONGLY RECOMMENDED" +\(em if you want no logging, turn it off in the configuration file. +.ip MATCHGECOS\(dg +Compile in the code to do ``fuzzy matching'' on the GECOS field +in /etc/passwd. +This also requires that the +.b MatchGECOS +option be turned on. +.ip NAMED_BIND\(dg +Compile in code to use the +Berkeley Internet Name Domain (BIND) server +to resolve TCP/IP host names. +.ip NOTUNIX +If you are using a non-UNIX mail format, +you can set this flag to turn off special processing +of UNIX-style +.q "From " +lines. +.ip QUEUE\(dg +This flag should be set to compile in the queueing code. +If this is not set, +mailers must accept the mail immediately +or it will be returned to the sender. +.ip SMTP\(dg +If set, +the code to handle user and server SMTP will be compiled in. +This is only necessary if your machine has some mailer +that speaks SMTP +(this means most machines everywhere). +.ip USERDB\(dg +Include the +.b experimental +Berkeley user information database package. +This adds a new level of local name expansion +between aliasing and forwarding. +It also uses the NEWDB package. +This may change in future releases. +.lp +The following options are normally turned on +in per-operating-system clauses in conf.h. +.ip IDENTPROTO\(dg +Compile in the IDENT protocol as defined in RFC 1413. +This defaults on for all systems except Ultrix, +which apparently has the interesting +.q feature +that when it receives a +.q "host unreachable" +message it closes all open connections to that host. +Since some firewall gateways send this error code +when you access an unauthorized port (such as 113, used by IDENT), +Ultrix cannot receive email from such hosts. +.ip SYSTEM5 +Set all of the compilation parameters appropriate for System V. +.ip HASFLOCK\(dg +Use Berkeley-style +.b flock +instead of System V +.b lockf +to do file locking. +Due to the highly unusual semantics of locks +across forks in +.b lockf , +this should always be used if at all possible. +.ip HASINITGROUPS +Set this if your system has the +.i initgroups() +call +(if you have multiple group support). +This is the default if SYSTEM5 is +.i not +defined or if you are on HPUX. +.ip HASUNAME +Set this if you have the +.i uname (2) +system call (or corresponding library routine). +Set by default if +SYSTEM5 +is set. +.ip HASGETDTABLESIZE +Set this if you have the +.i getdtablesize (2) +system call. +.ip HASWAITPID +Set this if you have the +.i haswaitpid (2) +system call. +.ip SFS_TYPE +The mechanism that can be used to get file system capacity information. +The values can be one of +SFS_USTAT (use the ustat(2) syscall), +SFS_4ARGS (use the four argument statfs(2) syscall), +SFS_VFS (use the two argument statfs(2) syscall including <sys/vfs.h>), +SFS_MOUNT (use the two argument statfs(2) syscall including <sys/mount.h>), +SFS_STATFS (use the two argument statfs(2) syscall including <sys/statfs.h>), +SFS_STATVFS (use the two argument statfs(2) syscall including <sys/statvfs.h>), +or +SFS_NONE (no way to get this information). +.ip LA_TYPE +The load average type. +Details are described below. +.lp +The are several built-in ways of computing the load average. +.i Sendmail +tries to auto-configure them based on imperfect guesses; +you can select one using the +.i cc +option +.b \-DLA_TYPE= \c +.i type , +where +.i type +is: +.ip LA_INT +The kernel stores the load average in the kernel as an array of long integers. +The actual values are scaled by a factor FSCALE +(default 256). +.ip LA_SHORT +The kernel stores the load average in the kernel as an array of short integers. +The actual values are scaled by a factor FSCALE +(default 256). +.ip LA_FLOAT +The kernel stores the load average in the kernel as an array of +double precision floats. +.ip LA_MACH +Use MACH-style load averages. +.ip LA_SUBR +Call the +.i getloadavg +routine to get the load average as an array of doubles. +.ip LA_ZERO +Always return zero as the load average. +This is the fallback case. +.lp +If type +.sm LA_INT , +.sm LA_SHORT , +or +.sm LA_FLOAT +is specified, +you may also need to specify +.sm _PATH_UNIX +(the path to your system binary) +and +.sm LA_AVENRUN +(the name of the variable containing the load average in the kernel; +usually +.q _avenrun +or +.q avenrun ). +.sh 2 "Configuration in src/conf.c" +.pp +The following changes can be made in conf.c. +.sh 3 "Built-in Header Semantics" +.pp +Not all header semantics are defined in the configuration file. +Header lines that should only be included by certain mailers +(as well as other more obscure semantics) +must be specified in the +.i HdrInfo +table in +.i conf.c . +This table contains the header name +(which should be in all lower case) +and a set of header control flags (described below), +The flags are: +.ip H_ACHECK +Normally when the check is made to see if a header line is compatible +with a mailer, +.i sendmail +will not delete an existing line. +If this flag is set, +.i sendmail +will delete +even existing header lines. +That is, +if this bit is set and the mailer does not have flag bits set +that intersect with the required mailer flags +in the header definition in +sendmail.cf, +the header line is +.i always +deleted. +.ip H_EOH +If this header field is set, +treat it like a blank line, +i.e., +it will signal the end of the header +and the beginning of the message text. +.ip H_FORCE +Add this header entry +even if one existed in the message before. +If a header entry does not have this bit set, +.i sendmail +will not add another header line if a header line +of this name already existed. +This would normally be used to stamp the message +by everyone who handled it. +.ip H_TRACE +If set, +this is a timestamp +(trace) +field. +If the number of trace fields in a message +exceeds a preset amount +the message is returned +on the assumption that it has an aliasing loop. +.ip H_RCPT +If set, +this field contains recipient addresses. +This is used by the +.b \-t +flag to determine who to send to +when it is collecting recipients from the message. +.ip H_FROM +This flag indicates that this field +specifies a sender. +The order of these fields in the +.i HdrInfo +table specifies +.i sendmail 's +preference +for which field to return error messages to. +.ip H_ERRORSTO +Addresses in this header should receive error messages. +.ip H_CTE +This header is a Content-Transfer-Encoding header. +.ip H_CTYPE +This header is a Content-Type header. +.ip H_STRIPVAL +Strip the value from the header (for Bcc:). +.nr ii 5n +.lp +Let's look at a sample +.i HdrInfo +specification: +.(b +.ta 4n +\w'"content-transfer-encoding", 'u +struct hdrinfo HdrInfo[] = +\&{ + /* originator fields, most to least significant */ + "resent-sender", H_FROM, + "resent-from", H_FROM, + "sender", H_FROM, + "from", H_FROM, + "full-name", H_ACHECK, + "errors-to", H_FROM\^|\^H_ERRORSTO, + /* destination fields */ + "to", H_RCPT, + "resent-to", H_RCPT, + "cc", H_RCPT, + "bcc", H_RCPT\^|\^H_STRIPVAL, + /* message identification and control */ + "message", H_EOH, + "text", H_EOH, + /* trace fields */ + "received", H_TRACE\^|\^H_FORCE, + /* miscellaneous fields */ + "content-transfer-encoding", H_CTE, + "content-type", H_CTYPE, + + NULL, 0, +}; +.)b +This structure indicates that the +.q To: , +.q Resent-To: , +and +.q Cc: +fields +all specify recipient addresses. +Any +.q Full-Name: +field will be deleted unless the required mailer flag +(indicated in the configuration file) +is specified. +The +.q Message: +and +.q Text: +fields will terminate the header; +these are used by random dissenters around the network world. +The +.q Received: +field will always be added, +and can be used to trace messages. +.pp +There are a number of important points here. +First, +header fields are not added automatically just because they are in the +.i HdrInfo +structure; +they must be specified in the configuration file +in order to be added to the message. +Any header fields mentioned in the configuration file but not +mentioned in the +.i HdrInfo +structure have default processing performed; +that is, +they are added unless they were in the message already. +Second, +the +.i HdrInfo +structure only specifies cliched processing; +certain headers are processed specially by ad hoc code +regardless of the status specified in +.i HdrInfo . +For example, +the +.q Sender: +and +.q From: +fields are always scanned on ARPANET mail +to determine the sender\**; +.(f +\**Actually, this is no longer true in SMTP; +this information is contained in the envelope. +The older ARPANET protocols did not completely distinguish +envelope from header. +.)f +this is used to perform the +.q "return to sender" +function. +The +.q "From:" +and +.q "Full-Name:" +fields are used to determine the full name of the sender +if possible; +this is stored in the macro +.b $x +and used in a number of ways. +.sh 3 "Restricting Use of Email" +.pp +If it is necessary to restrict mail through a relay, +the +.i checkcompat +routine can be modified. +This routine is called for every recipient address. +It returns an exit status +indicating the status of the message. +The status +.sm EX_OK +accepts the address, +.sm EX_TEMPFAIL +queues the message for a later try, +and other values +(commonly +.sm EX_UNAVAILABLE ) +reject the message. +It is up to +.i checkcompat +to print an error message +(using +.i usrerr ) +if the message is rejected. +For example, +.i checkcompat +could read: +.(b +.re +.sz -1 +.ta 4n +4n +4n +4n +4n +4n +4n +int +checkcompat(to, e) + register ADDRESS *to; + register ENVELOPE *e; +\&{ + register STAB *s; + + s = stab("private", ST_MAILER, ST_FIND); + if (s != NULL && e\->e_from.q_mailer != LocalMailer && + to->q_mailer == s->s_mailer) + { + usrerr("No private net mail allowed through this machine"); + return (EX_UNAVAILABLE); + } + if (MsgSize > 50000 && bitnset(M_LOCALMAILER, to\->q_mailer)) + { + usrerr("Message too large for non-local delivery"); + e\->e_flags |= EF_NORETURN; + return (EX_UNAVAILABLE); + } + return (EX_OK); +} +.sz +.)b +This would reject messages greater than 50000 bytes +unless they were local. +The +.i EF_NORETURN +flag can be set in +.i e\(->e_flags +to suppress the return of the actual body +of the message in the error return. +The actual use of this routine is highly dependent on the +implementation, +and use should be limited. +.sh 3 "New Database Map Classes" +.pp +New key maps can be added by creating a class initialization function +and a lookup function. +These are then added to the routine +.i setupmaps. +.pp +The initialization function is called as +.(b +\fIxxx\fP_map_init(MAP *map, char *args) +.)b +The +.i map +is an internal data structure. +The +.i args +is a pointer to the portion of the configuration file line +following the map class name; +flags and filenames can be extracted from this line. +The initialization function must return +.sm TRUE +if it successfully opened the map, +.sm FALSE +otherwise. +.pp +The lookup function is called as +.(b +\fIxxx\fP_map_lookup(MAP *map, char buf[], char **av, int *statp) +.)b +The +.i map +defines the map internally. +The +.i buf +has the input key. +This may be (and often is) used destructively. +The +.i av +is a list of arguments passed in from the rewrite line. +The lookup function should return a pointer to the new value. +If the map lookup fails, +.i *statp +should be set to an exit status code; +in particular, it should be set to +.sm EX_TEMPFAIL +if recovery is to be attempted by the higher level code. +.sh 3 "Queueing Function" +.pp +The routine +.i shouldqueue +is called to decide if a message should be queued +or processed immediately. +Typically this compares the message priority to the current load average. +The default definition is: +.(b +bool +shouldqueue(pri, ctime) + long pri; + time_t ctime; +{ + if (CurrentLA < QueueLA) + return (FALSE); + return (pri > (QueueFactor / (CurrentLA \- QueueLA + 1))); +} +.)b +If the current load average +(global variable +.i CurrentLA , +which is set before this function is called) +is less than the low threshold load average +(option +.b x , +variable +.i QueueLA ), +.i shouldqueue +returns +.sm FALSE +immediately +(that is, it should +.i not +queue). +If the current load average exceeds the high threshold load average +(option +.b X , +variable +.i RefuseLA ), +.i shouldqueue +returns +.sm TRUE +immediately. +Otherwise, it computes the function based on the message priority, +the queue factor +(option +.b q , +global variable +.i QueueFactor ), +and the current and threshold load averages. +.pp +An implementation wishing to take the actual age of the message into account +can also use the +.i ctime +parameter, +which is the time that the message was first submitted to +.i sendmail . +Note that the +.i pri +parameter is already weighted +by the number of times the message has been tried +(although this tends to lower the priority of the message with time); +the expectation is that the +.i ctime +would be used as an +.q "escape clause" +to ensure that messages are eventually processed. +.sh 3 "Refusing Incoming SMTP Connections" +.pp +The function +.i refuseconnections +returns +.sm TRUE +if incoming SMTP connections should be refused. +The current implementation is based exclusively on the current load average +and the refuse load average option +(option +.b X , +global variable +.i RefuseLA ): +.(b +bool +refuseconnections() +{ + return (CurrentLA >= RefuseLA); +} +.)b +A more clever implementation +could look at more system resources. +.sh 3 "Load Average Computation" +.pp +The routine +.i getla +returns the current load average (as a rounded integer). +The distribution includes several possible implementations. +If you are porting to a new environment +you may need to add some new tweaks.\** +.(f +\**If you do, please send updates to +sendmail@Sendmail.ORG. +.)f +.sh 2 "Configuration in src/daemon.c" +.pp +The file +.i src/daemon.c +contains a number of routines that are dependent +on the local networking environment. +The version supplied assumes you have BSD style sockets. +.pp +In previous releases, +we recommended that you modify the routine +.i maphostname +if you wanted to generalize +.b $[ +\&...\& +.b $] +lookups. +We now recommend that you create a new keyed map instead. +.sh 1 "ACKNOWLEDGEMENTS" +.pp +I've worked on +.i sendmail +for many years, +and many employers have been remarkably patient +about letting me work on a large project +that was not part of my official job. +This includes time on the INGRES Project at +the University of California at Berkeley, +at Britton Lee, +and again on the Mammoth and Titan Projects at Berkeley. +.pp +Much of the second wave of improvements +resulting in version 8.1 +should be credited to Bryan Costales of the +International Computer Science Institute. +As he passed me drafts of his book on +.i sendmail +I was inspired to start working on things again. +Bryan was also available to bounce ideas off of. +.pp +Gregory Neil Shapiro +of Worchester Polytechnic Institute +has become instrumental in all phases of +.i sendmail +support and development, +and was largely responsible for getting versions 8.8 and 8.9 +out the door. +.pp +Many, many people contributed chunks of code and ideas to +.i sendmail . +It has proven to be a group network effort. +Version 8 in particular was a group project. +The following people made notable contributions: +.(l +John Beck, Hewlett-Packard & Sun Microsystems +Keith Bostic, CSRG, University of California, Berkeley +Andrew Cheng, Sun Microsystems +Michael J. Corrigan, University of California, San Diego +Bryan Costales, International Computer Science Institute & InfoBeat +Pa\*:r (Pell) Emanuelsson +Craig Everhart, Transarc Corporation +Per Hedeland, Ericsson +Tom Ivar Helbekkmo, Norwegian School of Economics +Kari Hurtta, Finnish Meteorological Institute +Allan E. Johannesen, WPI +Jonathan Kamens, OpenVision Technologies, Inc. +Takahiro Kanbe, Fuji Xerox Information Systems Co., Ltd. +Brian Kantor, University of California, San Diego +John Kennedy, Cal State University, Chico +Murray S. Kucherawy, HookUp Communication Corp. +Bruce Lilly, Sony U.S. +Karl London +Motonori Nakamura, Ritsumeikan University & Kyoto University +John Gardiner Myers, Carnegie Mellon University +Neil Rickert, Northern Illinois University +Gregory Neil Shapiro, WPI +Eric Schnoebelen, Convex Computer Corp. +Eric Wassenaar, National Institute for Nuclear and High Energy Physics, Amsterdam +Randall Winchester, University of Maryland +Christophe Wolfhugel, Pasteur Institute & Herve Schauer Consultants (Paris) +.)l +I apologize for anyone I have omitted, misspelled, misattributed, or +otherwise missed. +At this point, I suspect that at least a hundred people +have contributed code, +and many more have contributed ideas, comments, and encouragement. +I've tried to list them in the RELEASE_NOTES in the distribution directory. +I appreciate their contribution as well. +.pp +Special thanks are reserved for Michael Corrigan and Christophe Wolfhugel, +who besides being wonderful guinea pigs and contributors +have also consented to be added to the ``sendmail@Sendmail.ORG'' list +and, by answering the bulk of the questions sent to that list, +have freed me up to do other work. +.++ A +.+c "COMMAND LINE FLAGS" +.ba 0 +.nr ii 1i +.pp +Arguments must be presented with flags before addresses. +The flags are: +.ip \-b\fIx\fP +Set operation mode to +.i x . +Operation modes are: +.(b +.ta 4n +m Deliver mail (default) +s Speak SMTP on input side +a\(dg ``Arpanet'' mode (get envelope sender information from header) +d Run as a daemon in background +D Run as a daemon in foreground +t Run in test mode +v Just verify addresses, don't collect or deliver +i Initialize the alias database +p Print the mail queue +.)b +.(f +\(dgDeprecated. +.)f +.ip \-B\fItype\fP +Indicate body type. +.ip \-C\fIfile\fP +Use a different configuration file. +.i Sendmail +runs as the invoking user (rather than root) +when this flag is specified. +.ip \-d\fIlevel\fP +Set debugging level. +.ip "\-f\ \fIaddr\fP" +The sender's machine address is +.i addr . +.ip \-F\ \fIname\fP +Sets the full name of this user to +.i name . +.ip "\-h\ \fIcnt\fP" +Sets the +.q "hop count" +to +.i cnt . +This represents the number of times this message has been processed +by +.i sendmail +(to the extent that it is supported by the underlying networks). +.i Cnt +is incremented during processing, +and if it reaches +MAXHOP +(currently 30) +.i sendmail +throws away the message with an error. +.ip \-n +Don't do aliasing or forwarding. +.ip "\-N \fInotifications\fP" +Tag all addresses being sent as wanting the indicated +.i notifications , +which consists of the word +.q NEVER +or a comma-separated list of +.q SUCCESS , +.q FAILURE , +and +.q DELAY +for successful delivery, +failure, +and a message that is stuck in a queue somewhere. +The default is +.q FAILURE,DELAY . +.ip "\-r\ \fIaddr\fP" +An obsolete form of +.b \-f . +.ip \-o\fIx\|value\fP +Set option +.i x +to the specified +.i value . +These options are described in Section 5.6. +.ip \-O\fIoption\fP\fB=\fP\fIvalue\fP +Set +.i option +to the specified +.i value +(for long form option names). +These options are described in Section 5.6. +.ip \-M\fIx\|value +Set macro +.i x +to the specified +.i value . +.ip \-p\fIprotocol\fP +Set the sending protocol. +Programs are encouraged to set this. +The protocol field can be in the form +.i protocol \c +.b : \c +.i host +to set both the sending protocol and sending host. +For example, +.q \-pUUCP:uunet +sets the sending protocol to UUCP +and the sending host to uunet. +(Some existing programs use \-oM to set the r and s macros; +this is equivalent to using \-p.) +.ip \-q\fItime\fP +Try to process the queued up mail. +If the time is given, +a +.i sendmail +will run through the queue at the specified interval +to deliver queued mail; +otherwise, it only runs once. +.ip \-q\fIXstring\fP +Run the queue once, +limiting the jobs to those matching +.i Xstring . +The key letter +.i X +can be +.b I +to limit based on queue identifier, +.b R +to limit based on recipient, +or +.b S +to limit based on sender. +A particular queued job is accepted if one of the corresponding addresses +contains the indicated +.i string . +Multiple +.i \-q\fIX\fP +flags are permitted, +with items with the same key letter +.q or'ed +together, and items with different key letters +.q and'ed +together. +.ip "\-R ret" +What information you want returned if the message bounces; +.i ret +can be +.q HDRS +for headers only or +.q FULL +for headers plus body. +This is a request only; +the other end is not required to honor the parameter. +.ip \-t +Read the header for +.q To: , +.q Cc: , +and +.q Bcc: +lines, and send to everyone listed in those lists. +The +.q Bcc: +line will be deleted before sending. +Any addresses in the argument vector will be deleted +from the send list. +.ip "\-U" +Indicate that this is an initial User Agent submission. +In future releases, sendmail may complain about syntactically invalid messages +rather than fixing them when this flag is not set. +.ip "\-V envid" +The indicated +.i envid +is passed with the envelope of the message +and returned if the message bounces. +.ip "\-X \fIlogfile\fP" +Log all traffic in and out of +.i sendmail +in the indicated +.i logfile +for debugging mailer problems. +This produces a lot of data very quickly and should be used sparingly. +.pp +There are a number of options that may be specified as +primitive flags. +These are the e, i, m, and v options. +Also, +the f option +may be specified as the +.b \-s +flag. +.+c "QUEUE FILE FORMATS" +.pp +This appendix describes the format of the queue files. +These files live in the directory defined by the +.b Q +option in the +.i sendmail.cf +file, usually +.i /var/spool/mqueue +or +.i /usr/spool/mqueue . +.pp +All queue files have the name +\fIx\fP\|\fBf\fP\fIAAA99999\fP +where +.i AAA99999 +is the +.i id +for this message +and the +.i x +is a type. +The first letter of the id encodes the hour of the day +that the message was received by the system +(with A being the hour between midnight and 1:00AM). +All files with the same id collectively define one message. +.pp +The types are: +.nr ii 0.5i +.ip d +The data file. +The message body (excluding the header) is kept in this file. +.ip q +The queue control file. +This file contains the information necessary to process the job. +.ip t +A temporary file. +These are an image of the +.b qf +file when it is being rebuilt. +It should be renamed to a +.b qf +file very quickly. +.ip x +A transcript file, +existing during the life of a session +showing everything that happens +during that session. +.pp +The +.b qf +file is structured as a series of lines +each beginning with a code letter. +The lines are as follows: +.ip V +The version number of the queue file format, +used to allow new +.i sendmail +binaries to read queue files created by older versions. +Defaults to version zero. +Must be the first line of the file if present. +.ip H +A header definition. +There may be any number of these lines. +The order is important: +they represent the order in the final message. +These use the same syntax +as header definitions in the configuration file. +.ip C +The controlling address. +The syntax is +.q localuser:aliasname . +Recipient addresses following this line +will be flagged so that deliveries will be run as the +.i localuser +(a user name from the /etc/passwd file); +.i aliasname +is the name of the alias that expanded to this address +(used for printing messages). +.ip Q +The ``original recipient'', +specified by the ORCPT= field in an ESMTP transaction. +Used exclusively for Delivery Status Notifications. +It applies only to the immediately following `R' line. +.ip R +A recipient address. +This will normally be completely aliased, +but is actually realiased when the job is processed. +There will be one line +for each recipient. +Version 1 qf files +also include a leading colon-terminated list of flags, +which can be +`S' to return a message on successful final delivery, +`F' to return a message on failure, +`D' to return a message if the message is delayed, +`B' to indicate that the body should be returned, +`N' to suppress returning the body, +and +`P' to declare this as a ``primary'' (command line or SMTP-session) address. +.ip S +The sender address. +There may only be one of these lines. +.ip T +The job creation time. +This is used to compute when to time out the job. +.ip P +The current message priority. +This is used to order the queue. +Higher numbers mean lower priorities. +The priority changes +as the message sits in the queue. +The initial priority depends on the message class +and the size of the message. +.ip M +A message. +This line is printed by the +.i mailq +command, +and is generally used to store status information. +It can contain any text. +.ip F +Flag bits, represented as one letter per flag. +Defined flag bits are +.b r +indicating that this is a response message +and +.b w +indicating that a warning message has been sent +announcing that the mail has been delayed. +.ip N +The total number of delivery attempts. +.ip K +The time (as seconds since January 1, 1970) +of the last delivery attempt. +.ip I +The i-number of the data file; +this can be used to recover your mail queue +after a disastrous disk crash. +.ip $ +A macro definition. +The values of certain macros +(as of this writing, only +.b $r +and +.b $s ) +are passed through to the queue run phase. +.ip B +The body type. +The remainder of the line is a text string defining the body type. +If this field is missing, +the body type is assumed to be +.q "undefined" +and no special processing is attempted. +Legal values are +.q 7BIT +and +.q 8BITMIME . +.ip O +The original MTS value (from the ESMTP transaction). +For Deliver Status Notifications only. +.ip Z +The original envelope id (from the ESMTP transaction). +For Deliver Status Notifications only. +.pp +As an example, +the following is a queue file sent to +.q eric@mammoth.Berkeley.EDU +and +.q bostic@okeeffe.CS.Berkeley.EDU \**: +.(f +\**This example is contrived and probably inaccurate for your environment. +Glance over it to get an idea; +nothing can replace looking at what your own system generates. +.)f +.(b +P835771 +T404261372 +Seric +Ceric:sendmail@vangogh.CS.Berkeley.EDU +Reric@mammoth.Berkeley.EDU +Rbostic@okeeffe.CS.Berkeley.EDU +H?P?Return-path: <owner-sendmail@vangogh.CS.Berkeley.EDU> +HReceived: by vangogh.CS.Berkeley.EDU (5.108/2.7) id AAA06703; + Fri, 17 Jul 1992 00:28:55 -0700 +HReceived: from mail.CS.Berkeley.EDU by vangogh.CS.Berkeley.EDU (5.108/2.7) + id AAA06698; Fri, 17 Jul 1992 00:28:54 -0700 +HReceived: from [128.32.31.21] by mail.CS.Berkeley.EDU (5.96/2.5) + id AA22777; Fri, 17 Jul 1992 03:29:14 -0400 +HReceived: by foo.bar.baz.de (5.57/Ultrix3.0-C) + id AA22757; Fri, 17 Jul 1992 09:31:25 GMT +H?F?From: eric@foo.bar.baz.de (Eric Allman) +H?x?Full-name: Eric Allman +HMessage-id: <9207170931.AA22757@foo.bar.baz.de> +HTo: sendmail@vangogh.CS.Berkeley.EDU +HSubject: this is an example message +.)b +This shows +the person who sent the message, +the submission time +(in seconds since January 1, 1970), +the message priority, +the message class, +the recipients, +and the headers for the message. +.+c "SUMMARY OF SUPPORT FILES" +.pp +This is a summary of the support files +that +.i sendmail +creates or generates. +Many of these can be changed by editing the sendmail.cf file; +check there to find the actual pathnames. +.nr ii 1i +.ip "/usr/\*(SD/sendmail" +The binary of +.i sendmail . +.ip /usr/\*(SB/newaliases +A link to /usr/\*(SD/sendmail; +causes the alias database to be rebuilt. +Running this program is completely equivalent to giving +.i sendmail +the +.b \-bi +flag. +.ip /usr/\*(SB/mailq +Prints a listing of the mail queue. +This program is equivalent to using the +.b \-bp +flag to +.i sendmail . +.ip /etc/sendmail.cf +The configuration file, +in textual form. +.ip /usr/lib/sendmail.hf +The SMTP help file. +.ip /etc/sendmail.st +A statistics file; need not be present. +.ip /etc/sendmail.pid +Created in daemon mode; +it contains the process id of the current SMTP daemon. +If you use this in scripts; +use ``head \-1'' to get just the first line; +the second line contains the command line used to invoke the daemon, +and later versions of +.i sendmail +may add more information to subsequent lines. +.ip /etc/aliases +The textual version of the alias file. +.ip /etc/aliases.db +The alias file in +.i hash \|(3) +format. +.ip /etc/aliases.{pag,dir} +The alias file in +.i ndbm \|(3) +format. +.ip /var/spool/mqueue +The directory in which the mail queue +and temporary files reside. +.ip /var/spool/mqueue/qf* +Control (queue) files for messages. +.ip /var/spool/mqueue/df* +Data files. +.ip /var/spool/mqueue/tf* +Temporary versions of the qf files, +used during queue file rebuild. +.ip /var/spool/mqueue/xf* +A transcript of the current session. +.if e \ +\{\ +. bp +. rs +. sp |4i +. ce 2 +This page intentionally left blank; +replace it with a blank sheet for double-sided output. +.\} +.\".ro +.\".ls 1 +.\".tp +.\".sp 2i +.\".in 0 +.\".ce 100 +.\".sz 24 +.\".b SENDMAIL +.\".sz 14 +.\".sp +.\"INSTALLATION AND OPERATION GUIDE +.\".sp +.\".sz 10 +.\"Eric Allman +.\".sp +.\"Version 8.129 +.\".ce 0 +.bp 3 +.ce +.sz 12 +TABLE OF CONTENTS +.sz 10 +.sp +.\" remove some things to avoid "out of temp file space" problem +.rm sh +.rm (x +.rm )x +.rm ip +.rm pp +.rm lp +.rm he +.rm fo +.rm eh +.rm oh +.rm ef +.rm of +.xp |
