1.\" Copyright (c) 1998-2005 Sendmail, Inc. and its suppliers.
2.\" All rights reserved.
3.\" Copyright (c) 1983, 1995 Eric P. Allman. All rights reserved.
4.\" Copyright (c) 1983, 1993
5.\" The Regents of the University of California. All rights reserved.
6.\"
7.\" By using this file, you agree to the terms and conditions set
8.\" forth in the LICENSE file which can be found at the top level of
9.\" the sendmail distribution.
10.\"
11.\"
| 1.\" Copyright (c) 1998-2005 Sendmail, Inc. and its suppliers.
2.\" All rights reserved.
3.\" Copyright (c) 1983, 1995 Eric P. Allman. All rights reserved.
4.\" Copyright (c) 1983, 1993
5.\" The Regents of the University of California. All rights reserved.
6.\"
7.\" By using this file, you agree to the terms and conditions set
8.\" forth in the LICENSE file which can be found at the top level of
9.\" the sendmail distribution.
10.\"
11.\"
|
12.\" $Id: op.me,v 8.749 2012/03/02 22:37:11 ca Exp $
| 12.\" $Id: op.me,v 8.751 2013/04/08 21:41:25 ca Exp $
|
13.\"
14.\" eqn op.me | pic | troff -me
15.\"
16.\" Define \(sc if not defined (for text output)
17.\"
18.if !c \(sc .char \(sc S
19.\"
20.\" Define \(dg as "*" for text output and create a new .DG macro
21.\" which describes the symbol.
22.\"
23.if n .ds { [
24.if n .ds } ]
25.ie !c \(dg \{\
26.char \(dg *
27.de DG
28an asterick
29..
30.\}
31.el \{\
32.de DG
33a dagger
34..
35.\}
36.\"
37.\" Define \(dd as "#" for text output and create a new .DD macro
38.\" which describes the symbol.
39.\"
40.ie !c \(dd \{\
41.char \(dd #
42.de DD
43a pound sign
44..
45.\}
46.el \{\
47.de DD
48a double dagger
49..
50.\}
51.eh 'SMM:08-%''Sendmail Installation and Operation Guide'
52.oh 'Sendmail Installation and Operation Guide''SMM:08-%'
53.\" SD is lib if sendmail is installed in /usr/lib, sbin if in /usr/sbin
54.ds SD sbin
55.\" SB is bin if newaliases/mailq are installed in /usr/bin, ucb if in /usr/ucb
56.ds SB bin
57.nr si 3n
58.de $0
59.(x
60.in \\$3u*3n
61.ti -3n
62\\$2. \\$1
63.)x
64..
65.de $C
66.(x
67.in 0
68\\$1 \\$2. \\$3
69.)x
70..
71.+c
72.(l C
73.sz 16
74.b SENDMAIL\u\s-6TM\s0\d
75.sz 12
76.sp
77.b "INSTALLATION AND OPERATION GUIDE"
78.(f
79.b DISCLAIMER:
80This documentation is under modification.
81.)f
82.sz 10
83.sp
84.r
85Eric Allman
86Claus Assmann
87Gregory Neil Shapiro
88Sendmail, Inc.
89.sp
90.de Ve
91Version \\$2
92..
| 13.\"
14.\" eqn op.me | pic | troff -me
15.\"
16.\" Define \(sc if not defined (for text output)
17.\"
18.if !c \(sc .char \(sc S
19.\"
20.\" Define \(dg as "*" for text output and create a new .DG macro
21.\" which describes the symbol.
22.\"
23.if n .ds { [
24.if n .ds } ]
25.ie !c \(dg \{\
26.char \(dg *
27.de DG
28an asterick
29..
30.\}
31.el \{\
32.de DG
33a dagger
34..
35.\}
36.\"
37.\" Define \(dd as "#" for text output and create a new .DD macro
38.\" which describes the symbol.
39.\"
40.ie !c \(dd \{\
41.char \(dd #
42.de DD
43a pound sign
44..
45.\}
46.el \{\
47.de DD
48a double dagger
49..
50.\}
51.eh 'SMM:08-%''Sendmail Installation and Operation Guide'
52.oh 'Sendmail Installation and Operation Guide''SMM:08-%'
53.\" SD is lib if sendmail is installed in /usr/lib, sbin if in /usr/sbin
54.ds SD sbin
55.\" SB is bin if newaliases/mailq are installed in /usr/bin, ucb if in /usr/ucb
56.ds SB bin
57.nr si 3n
58.de $0
59.(x
60.in \\$3u*3n
61.ti -3n
62\\$2. \\$1
63.)x
64..
65.de $C
66.(x
67.in 0
68\\$1 \\$2. \\$3
69.)x
70..
71.+c
72.(l C
73.sz 16
74.b SENDMAIL\u\s-6TM\s0\d
75.sz 12
76.sp
77.b "INSTALLATION AND OPERATION GUIDE"
78.(f
79.b DISCLAIMER:
80This documentation is under modification.
81.)f
82.sz 10
83.sp
84.r
85Eric Allman
86Claus Assmann
87Gregory Neil Shapiro
88Sendmail, Inc.
89.sp
90.de Ve
91Version \\$2
92..
|
93.Ve $Revision: 8.749 $
| 93.Ve $Revision: 8.751 $
|
94.rm Ve
95.sp
96For Sendmail Version 8.14
97.)l
98.(f
99Sendmail is a trademark of Sendmail, Inc.
100US Patent Numbers 6865671, 6986037.
101.)f
102.sp 2
103.pp
104.i Sendmail \u\s-2TM\s0\d
105implements a general purpose internetwork mail routing facility
106under the UNIX\(rg
107operating system.
108It is not tied to any one transport protocol \*-
109its function may be likened to a crossbar switch,
110relaying messages from one domain into another.
111In the process,
112it can do a limited amount of message header editing
113to put the message into a format that is appropriate
114for the receiving domain.
115All of this is done under the control of a configuration file.
116.pp
117Due to the requirements of flexibility
118for
119.i sendmail ,
120the configuration file can seem somewhat unapproachable.
121However, there are only a few basic configurations
122for most sites,
123for which standard configuration files have been supplied.
124Most other configurations
125can be built by adjusting an existing configuration file
126incrementally.
127.pp
128.i Sendmail
129is based on
130RFC 821 (Simple Mail Transport Protocol),
131RFC 822 (Internet Mail Headers Format),
132RFC 974 (MX routing),
133RFC 1123 (Internet Host Requirements),
134RFC 1413 (Identification server),
135RFC 1652 (SMTP 8BITMIME Extension),
136RFC 1869 (SMTP Service Extensions),
137RFC 1870 (SMTP SIZE Extension),
138RFC 1891 (SMTP Delivery Status Notifications),
139RFC 1892 (Multipart/Report),
140RFC 1893 (Enhanced Mail System Status Codes),
141RFC 1894 (Delivery Status Notifications),
142RFC 1985 (SMTP Service Extension for Remote Message Queue Starting),
143RFC 2033 (Local Message Transmission Protocol),
144RFC 2034 (SMTP Service Extension for Returning Enhanced Error Codes),
145RFC 2045 (MIME),
146RFC 2476 (Message Submission),
147RFC 2487 (SMTP Service Extension for Secure SMTP over TLS),
148RFC 2554 (SMTP Service Extension for Authentication),
149RFC 2821 (Simple Mail Transfer Protocol),
150RFC 2822 (Internet Message Format),
151RFC 2852 (Deliver By SMTP Service Extension),
152and
153RFC 2920 (SMTP Service Extension for Command Pipelining).
154However, since
155.i sendmail
156is designed to work in a wider world,
157in many cases it can be configured to exceed these protocols.
158These cases are described herein.
159.pp
160Although
161.i sendmail
162is intended to run
163without the need for monitoring,
164it has a number of features
165that may be used to monitor or adjust the operation
166under unusual circumstances.
167These features are described.
168.pp
169Section one describes how to do a basic
170.i sendmail
171installation.
172Section two
173explains the day-to-day information you should know
174to maintain your mail system.
175If you have a relatively normal site,
176these two sections should contain sufficient information
177for you to install
178.i sendmail
179and keep it happy.
180Section three
181has information regarding the command line arguments.
182Section four
183describes some parameters that may be safely tweaked.
184Section five
185contains the nitty-gritty information about the configuration
186file.
187This section is for masochists
188and people who must write their own configuration file.
189Section six
190describes configuration that can be done at compile time.
191The appendixes give a brief
192but detailed explanation of a number of features
193not described in the rest of the paper.
194.bp 7
195.sh 1 "BASIC INSTALLATION"
196.pp
197There are two basic steps to installing
198.i sendmail .
199First, you have to compile and install the binary.
200If
201.i sendmail
202has already been ported to your operating system
203that should be simple.
204Second, you must build a run-time configuration file.
205This is a file that
206.i sendmail
207reads when it starts up
208that describes the mailers it knows about,
209how to parse addresses,
210how to rewrite the message header,
211and the settings of various options.
212Although the configuration file can be quite complex,
213a configuration can usually be built
214using an M4-based configuration language.
215Assuming you have the standard
216.i sendmail
217distribution, see
218.i cf/README
219for further information.
220.pp
221The remainder of this section will describe the installation of
222.i sendmail
223assuming you can use one of the existing configurations
224and that the standard installation parameters are acceptable.
225All pathnames and examples
226are given from the root of the
227.i sendmail
228subtree,
229normally
230.i /usr/src/usr.\*(SD/sendmail
231on 4.4BSD-based systems.
232.pp
233Continue with the next section if you need/want to compile
234.i sendmail
235yourself.
236If you have a running binary already on your system,
237you should probably skip to section 1.2.
238.sh 2 "Compiling Sendmail"
239.pp
240All
241.i sendmail
242source is in the
243.i sendmail
244subdirectory.
245To compile sendmail,
246.q cd
247into the
248.i sendmail
249directory and type
250.(b
251\&./Build
252.)b
253This will leave the binary in an appropriately named subdirectory,
254e.g.,
255obj.BSD-OS.2.1.i386.
256It works for multiple object versions
257compiled out of the same directory.
258.sh 3 "Tweaking the Build Invocation"
259.pp
260You can give parameters on the
261.i Build
262command.
263In most cases these are only used when the
264.i obj.*
265directory is first created.
266To restart from scratch, use
267.i -c .
268These commands include:
269.nr ii 0.5i
270.ip "\-L \fIlibdirs\fP"
271A list of directories to search for libraries.
272.ip "\-I \fIincdirs\fP"
273A list of directories to search for include files.
274.ip "\-E \fIenvar\fP=\fIvalue\fP"
275Set an environment variable to an indicated
276.i value
277before compiling.
278.ip "\-c"
279Create a new
280.i obj.*
281tree before running.
282.ip "\-f \fIsiteconfig\fP"
283Read the indicated site configuration file.
284If this parameter is not specified,
285.i Build
286includes
287.i all
288of the files
289.i $BUILDTOOLS/Site/site.$oscf.m4
290and
291.i $BUILDTOOLS/Site/site.config.m4 ,
292where $BUILDTOOLS is normally
293.i \&../devtools
294and $oscf is the same name as used on the
295.i obj.*
296directory.
297See below for a description of the site configuration file.
298.ip "\-S"
299Skip auto-configuration.
300.i Build
301will avoid auto-detecting libraries if this is set.
302All libraries and map definitions must be specified
303in the site configuration file.
304.lp
305Most other parameters are passed to the
306.i make
307program; for details see
308.i $BUILDTOOLS/README .
309.sh 3 "Creating a Site Configuration File"
310.\"XXX
311.pp
312(This section is not yet complete.
313For now, see the file devtools/README for details.)
314See sendmail/README for various compilation flags that can be set.
315.sh 3 "Tweaking the Makefile"
316.pp
317.\" .b "XXX This should all be in the Site Configuration File section."
318.i Sendmail
319supports two different formats
320for the local (on disk) version of databases,
321notably the
322.i aliases
323database.
324At least one of these should be defined if at all possible.
325.nr ii 1i
326.ip NDBM
327The ``new DBM'' format,
328available on nearly all systems around today.
329This was the preferred format prior to 4.4BSD.
330It allows such complex things as multiple databases
331and closing a currently open database.
332.ip NEWDB
333The Berkeley DB package.
334If you have this, use it.
335It allows
336long records,
337multiple open databases,
338real in-memory caching,
339and so forth.
340You can define this in conjunction with
341.sm NDBM ;
342if you do,
343old alias databases are read,
344but when a new database is created it will be in NEWDB format.
345As a nasty hack,
346if you have NEWDB, NDBM, and NIS defined,
347and if the alias file name includes the substring
348.q /yp/ ,
349.i sendmail
350will create both new and old versions of the alias file
351during a
352.i newalias
353command.
354This is required because the Sun NIS/YP system
355reads the DBM version of the alias file.
356It's ugly as sin,
357but it works.
358.lp
359If neither of these are defined,
360.i sendmail
361reads the alias file into memory on every invocation.
362This can be slow and should be avoided.
363There are also several methods for remote database access:
364.ip LDAP
365Lightweight Directory Access Protocol.
366.ip NIS
367Sun's Network Information Services (formerly YP).
368.ip NISPLUS
369Sun's NIS+ services.
370.ip NETINFO
371NeXT's NetInfo service.
372.ip HESIOD
373Hesiod service (from Athena).
374.lp
375Other compilation flags are set in
376.i conf.h
377and should be predefined for you
378unless you are porting to a new environment.
379For more options see
380.i sendmail/README .
381.sh 3 "Compilation and installation"
382.pp
383After making the local system configuration described above,
384You should be able to compile and install the system.
385The script
386.q Build
387is the best approach on most systems:
388.(b
389\&./Build
390.)b
391This will use
392.i uname (1)
393to create a custom Makefile for your environment.
394.pp
395If you are installing in the standard places,
396you should be able to install using
397.(b
398\&./Build install
399.)b
400This should install the binary in
401/usr/\*(SD
402and create links from
403/usr/\*(SB/newaliases
404and
405/usr/\*(SB/mailq
406to
407/usr/\*(SD/sendmail.
408On most systems it will also format and install man pages.
409Notice: as of version 8.12
410.i sendmail
411will no longer be installed set-user-ID root by default.
412If you really want to use the old method, you can specify it as target:
413.(b
414\&./Build install-set-user-id
415.)b
416.sh 2 "Configuration Files"
417.pp
418.i Sendmail
419cannot operate without a configuration file.
420The configuration defines the mail delivery mechanisms understood at this site,
421how to access them,
422how to forward email to remote mail systems,
423and a number of tuning parameters.
424This configuration file is detailed
425in the later portion of this document.
426.pp
427The
428.i sendmail
429configuration can be daunting at first.
430The world is complex,
431and the mail configuration reflects that.
432The distribution includes an m4-based configuration package
433that hides a lot of the complexity.
434See
435.i cf/README
436for details.
437.pp
438Our configuration files are processed by
439.i m4
440to facilitate local customization;
441the directory
442.i cf
443of the
444.i sendmail
445distribution directory
446contains the source files.
447This directory contains several subdirectories:
448.nr ii 1i
449.ip cf
450Both site-dependent and site-independent descriptions of hosts.
451These can be literal host names
452(e.g.,
453.q ucbvax.mc )
454when the hosts are gateways
455or more general descriptions
456(such as
457.q "generic-solaris2.mc"
458as a general description of an SMTP-connected host
459running Solaris 2.x.
460Files ending
461.b \&.mc
462(``M4 Configuration'')
463are the input descriptions;
464the output is in the corresponding
465.b \&.cf
466file.
467The general structure of these files is described below.
468.ip domain
469Site-dependent subdomain descriptions.
470These are tied to the way your organization wants to do addressing.
471For example,
472.b domain/CS.Berkeley.EDU.m4
473is our description for hosts in the CS.Berkeley.EDU subdomain.
474These are referenced using the
475.sm DOMAIN
476.b m4
477macro in the
478.b \&.mc
479file.
480.ip feature
481Definitions of specific features that some particular host in your site
482might want.
483These are referenced using the
484.sm FEATURE
485.b m4
486macro.
487An example feature is
488use_cw_file
489(which tells
490.i sendmail
491to read an /etc/mail/local-host-names file on startup
492to find the set of local names).
493.ip hack
494Local hacks, referenced using the
495.sm HACK
496.b m4
497macro.
498Try to avoid these.
499The point of having them here is to make it clear that they smell.
500.ip m4
501Site-independent
502.i m4 (1)
503include files that have information common to all configuration files.
504This can be thought of as a
505.q #include
506directory.
507.ip mailer
508Definitions of mailers,
509referenced using the
510.sm MAILER
511.b m4
512macro.
513The mailer types that are known in this distribution are
514fax,
515local,
516smtp,
517uucp,
518and usenet.
519For example, to include support for the UUCP-based mailers,
520use
521.q MAILER(uucp) .
522.ip ostype
523Definitions describing various operating system environments
524(such as the location of support files).
525These are referenced using the
526.sm OSTYPE
527.b m4
528macro.
529.ip sh
530Shell files used by the
531.b m4
532build process.
533You shouldn't have to mess with these.
534.ip siteconfig
535Local UUCP connectivity information.
536This directory has been supplanted by the mailertable feature;
537any new configurations should use that feature to do UUCP
538(and other) routing.
539The use of this directory is deprecated.
540.pp
541If you are in a new domain
542(e.g., a company),
543you will probably want to create a
544cf/domain
545file for your domain.
546This consists primarily of relay definitions
547and features you want enabled site-wide:
548for example, Berkeley's domain definition
549defines relays for
550BitNET
551and UUCP.
552These are specific to Berkeley,
553and should be fully-qualified internet-style domain names.
554Please check to make certain they are reasonable for your domain.
555.pp
556Subdomains at Berkeley are also represented in the
557cf/domain
558directory.
559For example,
560the domain
561CS.Berkeley.EDU
562is the Computer Science subdomain,
563EECS.Berkeley.EDU
564is the Electrical Engineering and Computer Sciences subdomain,
565and
566S2K.Berkeley.EDU
567is the Sequoia 2000 subdomain.
568You will probably have to add an entry to this directory
569to be appropriate for your domain.
570.pp
571You will have to use or create
572.b \&.mc
573files in the
574.i cf/cf
575subdirectory for your hosts.
576This is detailed in the
577cf/README
578file.
579.sh 2 "Details of Installation Files"
580.pp
581This subsection describes the files that
582comprise the
583.i sendmail
584installation.
585.sh 3 "/usr/\*(SD/sendmail"
586.pp
587The binary for
588.i sendmail
589is located in /usr/\*(SD\**.
590.(f
591\**This is usually
592/usr/sbin
593on 4.4BSD and newer systems;
594many systems install it in
595/usr/lib.
596I understand it is in /usr/ucblib
597on System V Release 4.
598.)f
599It should be set-group-ID smmsp as described in
600sendmail/SECURITY.
601For security reasons,
602/, /usr, and /usr/\*(SD
603should be owned by root, mode 0755\**.
604.(f
605\**Some vendors ship them owned by bin;
606this creates a security hole that is not actually related to
607.i sendmail .
608Other important directories that should have restrictive ownerships
609and permissions are
610/bin, /usr/bin, /etc, /etc/mail, /usr/etc, /lib, and /usr/lib.
611.)f
612.sh 3 "/etc/mail/sendmail.cf"
613.pp
614This is the main configuration file for
615.i sendmail \**.
616.(f
617\**Actually, the pathname varies depending on the operating system;
618/etc/mail is the preferred directory.
619Some older systems install it in
620.b /usr/lib/sendmail.cf ,
621and I've also seen it in
622.b /usr/ucblib .
623If you want to move this file,
624add -D_PATH_SENDMAILCF=\e"/file/name\e"
625to the flags passed to the C compiler.
626Moving this file is not recommended:
627other programs and scripts know of this location.
628.)f
629This is one of the two non-library file names compiled into
630.i sendmail \**,
631the other is /etc/mail/submit.cf.
632.(f
633\**The system libraries can reference other files;
634in particular, system library subroutines that
635.i sendmail
636calls probably reference
637.i /etc/passwd
638and
639.i /etc/resolv.conf .
640.)f
641.pp
642The configuration file is normally created
643using the distribution files described above.
644If you have a particularly unusual system configuration
645you may need to create a special version.
646The format of this file is detailed in later sections
647of this document.
648.sh 3 "/etc/mail/submit.cf"
649.pp
650This is the configuration file for
651.i sendmail
652when it is used for initial mail submission, in which case
653it is also called ``Mail Submission Program'' (MSP)
654in contrast to ``Mail Transfer Agent'' (MTA).
655Starting with version 8.12,
656.i sendmail
657uses one of two different configuration files based on its operation mode
658(or the new
659.b \-A
660option).
661For initial mail submission, i.e., if one of the options
662.b \-bm
663(default),
664.b \-bs ,
665or
666.b \-t
667is specified, submit.cf is used (if available),
668for other operations sendmail.cf is used.
669Details can be found in
670.i sendmail/SECURITY .
671submit.cf is shipped with sendmail (in cf/cf/) and is installed by default.
672If changes to the configuration need to be made, start with
673cf/cf/submit.mc and follow the instruction in cf/README.
674.sh 3 "/usr/\*(SB/newaliases"
675.pp
676The
677.i newaliases
678command should just be a link to
679.i sendmail :
680.(b
681rm \-f /usr/\*(SB/newaliases
682ln \-s /usr/\*(SD/sendmail /usr/\*(SB/newaliases
683.)b
684This can be installed in whatever search path you prefer
685for your system.
686.sh 3 "/usr/\*(SB/hoststat"
687.pp
688The
689.i hoststat
690command should just be a link to
691.i sendmail ,
692in a fashion similar to
693.i newaliases .
694This command lists the status of the last mail transaction
695with all remote hosts. The
696.b \-v
697flag will prevent the status display from being truncated.
698It functions only when the
699.b HostStatusDirectory
700option is set.
701.sh 3 "/usr/\*(SB/purgestat"
702.pp
703This command is also a link to
704.i sendmail .
705It flushes expired (Timeout.hoststatus) information that is stored in the
706.b HostStatusDirectory
707tree.
708.sh 3 "/var/spool/mqueue"
709.pp
710The directory
711.i /var/spool/mqueue
712should be created to hold the mail queue.
713This directory should be mode 0700
714and owned by root.
715.pp
716The actual path of this directory
717is defined by the
718.b QueueDirectory
719option of the
720.i sendmail.cf
721file.
722To use multiple queues,
723supply a value ending with an asterisk.
724For example,
725.i /var/spool/mqueue/qd*
726will use all of the directories or symbolic links to directories
727beginning with `qd' in
728.i /var/spool/mqueue
729as queue directories.
730Do not change the queue directory structure
731while sendmail is running.
732.pp
733If these directories have subdirectories or symbolic links to directories
734named `qf', `df', and `xf', then these will be used for the different
735queue file types.
736That is, the data files are stored in the `df' subdirectory,
737the transcript files are stored in the `xf' subdirectory, and
738all others are stored in the `qf' subdirectory.
739.pp
740If shared memory support is compiled in,
741.i sendmail
742stores the available diskspace in a shared memory segment
743to make the values readily available to all children without
744incurring system overhead.
745In this case, only the daemon updates the data;
746i.e., the sendmail daemon creates the shared memory segment
747and deletes it if it is terminated.
748To use this,
749.i sendmail
750must have been compiled with support for shared memory
751(-DSM_CONF_SHM)
752and the option
753.b SharedMemoryKey
754must be set.
755Notice: do not use the same key for
756.i sendmail
757invocations with different queue directories
758or different queue group declarations.
759Access to shared memory is not controlled by locks,
760i.e., there is a race condition when data in the shared memory is updated.
761However, since operation of
762.i sendmail
763does not rely on the data in the shared memory, this does not negatively
764influence the behavior.
765.sh 3 "/var/spool/clientmqueue"
766.pp
767The directory
768.i /var/spool/clientmqueue
769should be created to hold the mail queue.
770This directory should be mode 0770
771and owned by user smmsp, group smmsp.
772.pp
773The actual path of this directory
774is defined by the
775.b QueueDirectory
776option of the
777.i submit.cf
778file.
779.sh 3 "/var/spool/mqueue/.hoststat"
780.pp
781This is a typical value for the
782.b HostStatusDirectory
783option,
784containing one file per host
785that this sendmail has chatted with recently.
786It is normally a subdirectory of
787.i mqueue .
788.sh 3 "/etc/mail/aliases*"
789.pp
790The system aliases are held in
791.q /etc/mail/aliases .
792A sample is given in
793.q sendmail/aliases
794which includes some aliases which
795.i must
796be defined:
797.(b
798cp sendmail/aliases /etc/mail/aliases
799.i "edit /etc/mail/aliases"
800.)b
801You should extend this file with any aliases that are apropos to your system.
802.pp
803Normally
804.i sendmail
805looks at a database version of the files,
806stored either in
807.q /etc/mail/aliases.dir
808and
809.q /etc/mail/aliases.pag
810or
811.q /etc/mail/aliases.db
812depending on which database package you are using.
813The actual path of this file
814is defined in the
815.b AliasFile
816option of the
817.i sendmail.cf
818file.
819.pp
820The permissions of the alias file and the database versions
821should be 0640 to prevent local denial of service attacks
822as explained in the top level
823.b README
824in the sendmail distribution.
825If the permissions 0640 are used, be sure that only trusted users belong
826to the group assigned to those files. Otherwise, files should not even
827be group readable.
828.sh 3 "/etc/rc or /etc/init.d/sendmail"
829.pp
830It will be necessary to start up the
831.i sendmail
832daemon when your system reboots.
833This daemon performs two functions:
834it listens on the SMTP socket for connections
835(to receive mail from a remote system)
836and it processes the queue periodically
837to insure that mail gets delivered when hosts come up.
838.pp
839If necessary, add the following lines to
840.q /etc/rc
841(or
842.q /etc/rc.local
843as appropriate)
844in the area where it is starting up the daemons
845on a BSD-base system,
846or on a System-V-based system
847in one of the startup files, typically
848.q /etc/init.d/sendmail :
849.(b
850if [ \-f /usr/\*(SD/sendmail \-a \-f /etc/mail/sendmail.cf ]; then
851 (cd /var/spool/mqueue; rm \-f xf*)
852 /usr/\*(SD/sendmail \-bd \-q30m &
853 echo \-n ' sendmail' >/dev/console
854fi
855.)b
856The
857.q cd
858and
859.q rm
860commands insure that all transcript files have been removed;
861extraneous transcript files may be left around
862if the system goes down in the middle of processing a message.
863The line that actually invokes
864.i sendmail
865has two flags:
866.q \-bd
867causes it to listen on the SMTP port,
868and
869.q \-q30m
870causes it to run the queue every half hour.
871.pp
872Some people use a more complex startup script,
873removing zero length qf/hf/Qf files and df files for which there is no
874qf/hf/Qf file.
875Note this is not advisable.
876For example, see Figure 1
877for an example of a complex script which does this clean up.
878.(z
879.hl
880#!/bin/sh
881# remove zero length qf/hf/Qf files
882for qffile in qf* hf* Qf*
883do
884 if [ \-r $qffile ]
885 then
886 if [ ! \-s $qffile ]
887 then
888 echo \-n " <zero: $qffile>" > /dev/console
889 rm \-f $qffile
890 fi
891 fi
892done
893# rename tf files to be qf if the qf does not exist
894for tffile in tf*
895do
896 qffile=`echo $tffile | sed 's/t/q/'`
897 if [ \-r $tffile \-a ! \-f $qffile ]
898 then
899 echo \-n " <recovering: $tffile>" > /dev/console
900 mv $tffile $qffile
901 else
902 if [ \-f $tffile ]
903 then
904 echo \-n " <extra: $tffile>" > /dev/console
905 rm \-f $tffile
906 fi
907 fi
908done
909# remove df files with no corresponding qf/hf/Qf files
910for dffile in df*
911do
912 qffile=`echo $dffile | sed 's/d/q/'`
913 hffile=`echo $dffile | sed 's/d/h/'`
914 Qffile=`echo $dffile | sed 's/d/Q/'`
915 if [ \-r $dffile \-a ! \-f $qffile \-a ! \-f $hffile \-a ! \-f $Qffile ]
916 then
917 echo \-n " <incomplete: $dffile>" > /dev/console
918 mv $dffile `echo $dffile | sed 's/d/D/'`
919 fi
920done
921# announce files that have been saved during disaster recovery
922for xffile in [A-Z]f*
923do
924 if [ \-f $xffile ]
925 then
926 echo \-n " <panic: $xffile>" > /dev/console
927 fi
928done
929.sp
930.ce
931Figure 1 \(em A complex startup script
932.hl
933.)z
934.sh 3 "/etc/mail/helpfile"
935.pp
936This is the help file used by the SMTP
937.b HELP
938command.
939It should be copied from
940.q sendmail/helpfile :
941.(b
942cp sendmail/helpfile /etc/mail/helpfile
943.)b
944The actual path of this file
945is defined in the
946.b HelpFile
947option of the
948.i sendmail.cf
949file.
950.sh 3 "/etc/mail/statistics"
951.pp
952If you wish to collect statistics
953about your mail traffic,
954you should create the file
955.q /etc/mail/statistics :
956.(b
957cp /dev/null /etc/mail/statistics
958chmod 0600 /etc/mail/statistics
959.)b
960This file does not grow.
961It is printed with the program
962.q mailstats/mailstats.c.
963The actual path of this file
964is defined in the
965.b S
966option of the
967.i sendmail.cf
968file.
969.sh 3 "/usr/\*(SB/mailq"
970.pp
971If
972.i sendmail
973is invoked as
974.q mailq,
975it will simulate the
976.b \-bp
977flag
978(i.e.,
979.i sendmail
980will print the contents of the mail queue;
981see below).
982This should be a link to /usr/\*(SD/sendmail.
983.sh 3 "sendmail.pid"
984.pp
985.i sendmail
986stores its current pid in the file specified by the
987.b PidFile
988option (default is _PATH_SENDMAILPID).
989.i sendmail
990uses
991.b TempFileMode
992(which defaults to 0600) as
993the permissions of that file
994to prevent local denial of service attacks
995as explained in the top level
996.b README
997in the sendmail distribution.
998If the file already exists, then it might be necessary to
999change the permissions accordingly, e.g.,
1000.(b
1001chmod 0600 /var/run/sendmail.pid
1002.)b
1003Note that as of version 8.13, this file is unlinked when
1004.i sendmail
1005exits.
1006As a result of this change, a script such as the following,
1007which may have worked prior to 8.13, will no longer work:
1008.(b
1009# stop & start sendmail
1010PIDFILE=/var/run/sendmail.pid
1011kill `head -1 $PIDFILE`
1012`tail -1 $PIDFILE`
1013.)b
1014because it assumes that the pidfile will still exist even
1015after killing the process to which it refers.
1016Below is a script which will work correctly
1017on both newer and older versions:
1018.(b
1019# stop & start sendmail
1020PIDFILE=/var/run/sendmail.pid
1021pid=`head -1 $PIDFILE`
1022cmd=`tail -1 $PIDFILE`
1023kill $pid
1024$cmd
1025.)b
1026This is just an example script, it does not perform any error checks,
1027e.g., whether the pidfile exists at all.
1028.sh 3 "Map Files"
1029.pp
1030To prevent local denial of service attacks
1031as explained in the top level
1032.b README
1033in the sendmail distribution,
1034the permissions of map files created by
1035.i makemap
1036should be 0640.
1037The use of 0640 implies that only trusted users belong to the group
1038assigned to those files.
1039If those files already exist, then it might be necessary to
1040change the permissions accordingly, e.g.,
1041.(b
1042cd /etc/mail
1043chmod 0640 *.db *.pag *.dir
1044.)b
1045.sh 1 "NORMAL OPERATIONS"
1046.sh 2 "The System Log"
1047.pp
1048The system log is supported by the
1049.i syslogd \|(8)
1050program.
1051All messages from
1052.i sendmail
1053are logged under the
1054.sm LOG_MAIL
1055facility\**.
1056.(f
1057\**Except on Ultrix,
1058which does not support facilities in the syslog.
1059.)f
1060.sh 3 "Format"
1061.pp
1062Each line in the system log
1063consists of a timestamp,
1064the name of the machine that generated it
1065(for logging from several machines
1066over the local area network),
1067the word
1068.q sendmail: ,
1069and a message\**.
1070.(f
1071\**This format may vary slightly if your vendor has changed
1072the syntax.
1073.)f
1074Most messages are a sequence of
1075.i name \c
1076=\c
1077.i value
1078pairs.
1079.pp
1080The two most common lines are logged when a message is processed.
1081The first logs the receipt of a message;
1082there will be exactly one of these per message.
1083Some fields may be omitted if they do not contain interesting information.
1084Fields are:
1085.ip from
1086The envelope sender address.
1087.ip size
1088The size of the message in bytes.
1089.ip class
1090The class (i.e., numeric precedence) of the message.
1091.ip pri
1092The initial message priority (used for queue sorting).
1093.ip nrcpts
1094The number of envelope recipients for this message
1095(after aliasing and forwarding).
1096.ip msgid
1097The message id of the message (from the header).
1098.ip bodytype
1099The message body type (7BIT or 8BITMIME),
1100as determined from the envelope.
1101.ip proto
1102The protocol used to receive this message (e.g., ESMTP or UUCP)
1103.ip daemon
1104The daemon name from the
1105.b DaemonPortOptions
1106setting.
1107.ip relay
1108The machine from which it was received.
1109.lp
1110There is also one line logged per delivery attempt
1111(so there can be several per message if delivery is deferred
1112or there are multiple recipients).
1113Fields are:
1114.ip to
1115A comma-separated list of the recipients to this mailer.
1116.ip ctladdr
1117The ``controlling user'', that is, the name of the user
1118whose credentials we use for delivery.
1119.ip delay
1120The total delay between the time this message was received
1121and the current delivery attempt.
1122.ip xdelay
1123The amount of time needed in this delivery attempt
1124(normally indicative of the speed of the connection).
1125.ip mailer
1126The name of the mailer used to deliver to this recipient.
1127.ip relay
1128The name of the host that actually accepted (or rejected) this recipient.
1129.ip dsn
1130The enhanced error code (RFC 2034) if available.
1131.ip stat
1132The delivery status.
1133.lp
1134Not all fields are present in all messages;
1135for example, the relay is usually not listed for local deliveries.
1136.sh 3 "Levels"
1137.pp
1138If you have
1139.i syslogd \|(8)
1140or an equivalent installed,
1141you will be able to do logging.
1142There is a large amount of information that can be logged.
1143The log is arranged as a succession of levels.
1144At the lowest level
1145only extremely strange situations are logged.
1146At the highest level,
1147even the most mundane and uninteresting events
1148are recorded for posterity.
1149As a convention,
1150log levels under ten
1151are considered generally
1152.q useful;
1153log levels above 64
1154are reserved for debugging purposes.
1155Levels from 11\-64 are reserved for verbose information
1156that some sites might want.
1157.pp
1158A complete description of the log levels
1159is given in section ``Log Level''.
1160.sh 2 "Dumping State"
1161.pp
1162You can ask
1163.i sendmail
1164to log a dump of the open files
1165and the connection cache
1166by sending it a
1167.sm SIGUSR1
1168signal.
1169The results are logged at
1170.sm LOG_DEBUG
1171priority.
1172.sh 2 "The Mail Queues"
1173.pp
1174Mail messages may either be delivered immediately or be held for later
1175delivery.
1176Held messages are placed into a holding directory called a mail queue.
1177.pp
1178A mail message may be queued for these reasons:
1179.bu
1180If a mail message is temporarily undeliverable, it is queued
1181and delivery is attempted later.
1182If the message is addressed to multiple recipients, it is queued
1183only for those recipients to whom delivery is not immediately possible.
1184.bu
1185If the SuperSafe option is set to true,
1186all mail messages are queued while delivery is attempted.
1187.bu
1188If the DeliveryMode option is set to queue-only or defer,
1189all mail is queued, and no immediate delivery is attempted.
1190.bu
1191If the load average becomes higher than the value of the QueueLA option
1192and the
1193.b QueueFactor
1194(\c
1195.b q )
1196option divided by the difference in the current load average and the
1197.b QueueLA
1198option plus one
1199is less than the priority of the message,
1200messages are queued rather than immediately delivered.
1201.bu
1202One or more addresses are marked as expensive and delivery is postponed
1203until the next queue run or one or more address are marked as held via
1204mailer which uses the hold mailer flag.
1205.bu
1206The mail message has been marked as quarantined via a mail filter or
1207rulesets.
1208.bu
1209.sh 3 "Queue Groups and Queue Directories"
1210.pp
1211There are one or more mail queues.
1212Each mail queue belongs to a queue group.
1213There is always a default queue group that is called ``mqueue''
1214(which is where messages go by default unless otherwise specified).
1215The directory or directories which comprise the default queue group
1216are specified by the QueueDirectory option.
1217There are zero or more
1218additional named queue groups declared using the
1219.b Q
1220command in the configuration file.
1221.pp
1222By default, a queued message is placed in the queue group
1223associated with the first recipient in the recipient list.
1224A recipient address is mapped to a queue group as follows.
1225First, if there is a ruleset called ``queuegroup'',
1226and if this ruleset maps the address to a queue group name,
1227then that queue group is chosen.
1228That is, the argument for the ruleset is the recipient address
1229and the result should be
1230.b $#
1231followed by the name of a queue group.
1232Otherwise, if the mailer associated with the address specifies
1233a queue group, then that queue group is chosen.
1234Otherwise, the default queue group is chosen.
1235.pp
1236A message with multiple recipients will be split
1237if different queue groups are chosen
1238by the mapping of recipients to queue groups.
1239.pp
1240When a message is placed in a queue group, and the queue group has
1241more than one queue, a queue is selected randomly.
1242.pp
1243If a message with multiple recipients is placed into a queue group
1244with the 'r' option (maximum number of recipients per message)
1245set to a positive value
1246.i N ,
1247and if there are more than
1248.i N
1249recipients
1250in the message, then the message will be split into multiple messages,
1251each of which have at most
1252.i N
1253recipients.
1254.pp
1255Notice: if multiple queue groups are used, do
1256.b not
1257move queue files around, e.g., into a different queue directory.
1258This may have weird effects and can cause mail not to be delivered.
1259Queue files and directories should be treated as opaque
1260and should not be manipulated directly.
1261.sh 3 "Queue Runs"
1262.pp
1263.i sendmail
1264has two different ways to process the queue(s).
1265The first one is to start queue runners after certain intervals
1266(``normal'' queue runners),
1267the second one is to keep queue runner processes around
1268(``persistent'' queue runners).
1269How to select either of these types is discussed in the appendix
1270``COMMAND LINE FLAGS''.
1271Persistent queue runners have the advantage that no new processes
1272need to be spawned at certain intervals; they just sleep for
1273a specified time after they finished a queue run.
1274Another advantage of persistent queue runners is that only one process
1275belonging to a workgroup (a workgroup is a set of queue groups)
1276collects the data for a queue run
1277and then multiple queue runner may go ahead using that data.
1278This can significantly reduce the disk I/O necessary to read the
1279queue files compared to starting multiple queue runners directly.
1280Their disadvantage is that a new queue run is only started
1281after all queue runners belonging to a group finished their tasks.
1282In case one of the queue runners tries delivery to a slow recipient site
1283at the end of a queue run, the next queue run may be substantially delayed.
1284In general this should be smoothed out due to the distribution of
1285those slow jobs, however, for sites with small number of
1286queue entries this might introduce noticable delays.
1287In general, persistent queue runners are only useful for
1288sites with big queues.
1289.sh 3 "Manual Intervention"
1290.pp
1291Under normal conditions the mail queue will be processed transparently.
1292However, you may find that manual intervention is sometimes necessary.
1293For example,
1294if a major host is down for a period of time
1295the queue may become clogged.
1296Although
1297.i sendmail
1298ought to recover gracefully when the host comes up,
1299you may find performance unacceptably bad in the meantime.
1300In that case you want to check the content of the queue
1301and manipulate it as explained in the next two sections.
1302.sh 3 "Printing the queue"
1303.pp
1304The contents of the queue(s) can be printed
1305using the
1306.i mailq
1307command
1308(or by specifying the
1309.b \-bp
1310flag to
1311.i sendmail ):
1312.(b
1313mailq
1314.)b
1315This will produce a listing of the queue id's,
1316the size of the message,
1317the date the message entered the queue,
1318and the sender and recipients.
1319If shared memory support is compiled in,
1320the flag
1321.b \-bP
1322can be used to print the number of entries in the queue(s),
1323provided a process updates the data.
1324However, as explained earlier, the output might be slightly wrong,
1325since access to the shared memory is not locked.
1326For example,
1327``unknown number of entries''
1328might be shown.
1329The internal counters are updated after each queue run
1330to the correct value again.
1331.sh 3 "Forcing the queue"
1332.pp
1333.i Sendmail
1334should run the queue automatically at intervals.
1335When using multiple queues,
1336a separate process will by default be created to
1337run each of the queues
1338unless the queue run is initiated by a user
1339with the verbose flag.
1340The algorithm is to read and sort the queue,
1341and then to attempt to process all jobs in order.
1342When it attempts to run the job,
1343.i sendmail
1344first checks to see if the job is locked.
1345If so, it ignores the job.
1346.pp
1347There is no attempt to insure that only one queue processor
1348exists at any time,
1349since there is no guarantee that a job cannot take forever
1350to process
1351(however,
1352.i sendmail
1353does include heuristics to try to abort jobs
1354that are taking absurd amounts of time;
1355technically, this violates RFC 821, but is blessed by RFC 1123).
1356Due to the locking algorithm,
1357it is impossible for one job to freeze the entire queue.
1358However,
1359an uncooperative recipient host
1360or a program recipient
1361that never returns
1362can accumulate many processes in your system.
1363Unfortunately,
1364there is no completely general way to solve this.
1365.pp
1366In some cases,
1367you may find that a major host going down
1368for a couple of days
1369may create a prohibitively large queue.
1370This will result in
1371.i sendmail
1372spending an inordinate amount of time
1373sorting the queue.
1374This situation can be fixed by moving the queue to a temporary place
1375and creating a new queue.
1376The old queue can be run later when the offending host returns to service.
1377.pp
1378To do this,
1379it is acceptable to move the entire queue directory:
1380.(b
1381cd /var/spool
1382mv mqueue omqueue; mkdir mqueue; chmod 0700 mqueue
1383.)b
1384You should then kill the existing daemon
1385(since it will still be processing in the old queue directory)
1386and create a new daemon.
1387.pp
1388To run the old mail queue, issue the following command:
1389.(b
1390/usr/\*(SD/sendmail \-C /etc/mail/queue.cf \-q
1391.)b
1392The
1393.b \-C
1394flag specifies an alternate configuration file
1395.b queue.cf
1396which should refer to the moved queue directory
1397.(b
1398O QueueDirectory=/var/spool/omqueue
1399.)b
1400and the
1401.b \-q
1402flag says to just run every job in the queue.
1403You can also specify the moved queue directory on the command line
1404.(b
1405/usr/\*(SD/sendmail \-oQ/var/spool/omqueue \-q
1406.)b
1407but this requires that you do not have
1408queue groups in the configuration file,
1409because those are not subdirectories of the moved directory.
1410See the section about ``Queue Group Declaration'' for details;
1411you most likely need a different configuration file to correctly deal
1412with this problem.
1413However, a proper configuration of queue groups should avoid
1414filling up queue directories, so you shouldn't run into
1415this problem.
1416If you have a tendency toward voyeurism,
1417you can use the
1418.b \-v
1419flag to watch what is going on.
1420.pp
1421When the queue is finally emptied,
1422you can remove the directory:
1423.(b
1424rmdir /var/spool/omqueue
1425.)b
1426.sh 3 "Quarantined Queue Items"
1427.pp
1428It is possible to "quarantine" mail messages,
1429otherwise known as envelopes.
1430Envelopes (queue files) are stored but not considered for delivery or
1431display unless the "quarantine" state of the envelope is undone or
1432delivery or display of quarantined items is requested.
1433Quarantined messages are tagged by using a different name for the queue
1434file, 'hf' instead of 'qf', and by adding the quarantine reason to the
1435queue file.
1436.pp
1437Delivery or display of quarantined items can be requested using the
1438.b \-qQ
1439flag to
1440.i sendmail
1441or
1442.i mailq .
1443Additionally, messages already in the queue can be quarantined or
1444unquarantined using the new
1445.b \-Q
1446flag to sendmail.
1447For example,
1448.(b
1449sendmail -Qreason -q[!][I|R|S][matchstring]
1450.)b
1451Quarantines the normal queue items matching the criteria specified by the
1452.b "-q[!][I|R|S][matchstring]"
1453using the reason given on the
1454.b \-Q
1455flag.
1456Likewise,
1457.(b
1458sendmail -qQ -Q[reason] -q[!][I|R|S|Q][matchstring]
1459.)b
1460Change the quarantine reason for the quarantined items matching the
1461criteria specified by the
1462.b "-q[!][I|R|S|Q][matchstring]"
1463using the reason given on the
1464.b \-Q
1465flag.
1466If there is no reason,
1467 unquarantine the matching items and make them normal queue items.
1468Note that the
1469.b \-qQ
1470flag tells sendmail to operate on quarantined items instead of normal items.
1471.sh 2 "Disk Based Connection Information"
1472.pp
1473.i Sendmail
1474stores a large amount of information about each remote system it
1475has connected to in memory. It is possible to preserve some
1476of this information on disk as well, by using the
1477.b HostStatusDirectory
1478option, so that it may be shared between several invocations of
1479.i sendmail .
1480This allows mail to be queued immediately or skipped during a queue run if
1481there has been a recent failure in connecting to a remote machine.
1482Note: information about a remote system is stored in a file
1483whose pathname consists of the components of the hostname in reverse order.
1484For example, the information for
1485.b host.example.com
1486is stored in
1487.b com./example./host .
1488For top-level domains like
1489.b com
1490this can create a large number of subdirectories
1491which on some filesystems can exhaust some limits.
1492Moreover, the performance of lookups in directory with thousands of entries
1493can be fairly slow depending on the filesystem implementation.
1494.pp
1495Additionally enabling
1496.b SingleThreadDelivery
1497has the added effect of single-threading mail delivery to a destination.
1498This can be quite helpful
1499if the remote machine is running an SMTP server that is easily overloaded
1500or cannot accept more than a single connection at a time,
1501but can cause some messages to be punted to a future queue run.
1502It also applies to
1503.i all
1504hosts, so setting this because you have one machine on site
1505that runs some software that is easily overrun
1506can cause mail to other hosts to be slowed down.
1507If this option is set,
1508you probably want to set the
1509.b MinQueueAge
1510option as well and run the queue fairly frequently;
1511this way jobs that are skipped because another
1512.i sendmail
1513is talking to the same host will be tried again quickly
1514rather than being delayed for a long time.
1515.pp
1516The disk based host information is stored in a subdirectory of the
1517.b mqueue
1518directory called
1519.b \&.hoststat \**.
1520.(f
1521\**This is the usual value of the
1522.b HostStatusDirectory
1523option;
1524it can, of course, go anywhere you like in your filesystem.
1525.)f
1526Removing this directory and its subdirectories has an effect similar to
1527the
1528.i purgestat
1529command and is completely safe.
1530However,
1531.i purgestat
1532only removes expired (Timeout.hoststatus) data.
1533The information in these directories can
1534be perused with the
1535.i hoststat
1536command, which will indicate the host name, the last access, and the
1537status of that access.
1538An asterisk in the left most column indicates that a
1539.i sendmail
1540process currently has the host locked for mail delivery.
1541.pp
1542The disk based connection information is treated the same way as memory based
1543connection information for the purpose of timeouts.
1544By default, information about host failures is valid for 30 minutes.
1545This can be adjusted with
1546the
1547.b Timeout.hoststatus
1548option.
1549.pp
1550The connection information stored on disk may be expired at any time
1551with the
1552.i purgestat
1553command or by invoking sendmail with the
1554.b \-bH
1555switch.
1556The connection information may be viewed with the
1557.i hoststat
1558command or by invoking sendmail with the
1559.b \-bh
1560switch.
1561.sh 2 "The Service Switch"
1562.pp
1563The implementation of certain system services
1564such as host and user name lookup
1565is controlled by the service switch.
1566If the host operating system supports such a switch,
1567and sendmail knows about it,
1568.i sendmail
1569will use the native version.
1570Ultrix, Solaris, and DEC OSF/1 are examples of such systems\**.
1571.(f
1572\**HP-UX 10 has service switch support,
1573but since the APIs are apparently not available in the libraries
1574.i sendmail
1575does not use the native service switch in this release.
1576.)f
1577.pp
1578If the underlying operating system does not support a service switch
1579(e.g., SunOS 4.X, HP-UX, BSD)
1580then
1581.i sendmail
1582will provide a stub implementation.
1583The
1584.b ServiceSwitchFile
1585option points to the name of a file that has the service definitions.
1586Each line has the name of a service
1587and the possible implementations of that service.
1588For example, the file:
1589.(b
1590hosts dns files nis
1591aliases files nis
1592.)b
1593will ask
1594.i sendmail
1595to look for hosts in the Domain Name System first.
1596If the requested host name is not found, it tries local files,
1597and if that fails it tries NIS.
1598Similarly, when looking for aliases
1599it will try the local files first followed by NIS.
1600.pp
1601Notice: since
1602.i sendmail
1603must access MX records for correct operation, it will use
1604DNS if it is configured in the
1605.b ServiceSwitchFile
1606file.
1607Hence an entry like
1608.(b
1609hosts files dns
1610.)b
1611will not avoid DNS lookups even if a host can be found
1612in /etc/hosts.
1613.pp
1614Service switches are not completely integrated.
1615For example, despite the fact that the host entry listed in the above example
1616specifies to look in NIS,
1617on SunOS this won't happen because the system implementation of
1618.i gethostbyname \|(3)
1619doesn't understand this.
1620.sh 2 "The Alias Database"
1621.pp
1622After recipient addresses are read from the SMTP connection
1623or command line
1624they are parsed by ruleset 0,
1625which must resolve to a
1626{\c
1627.i mailer ,
1628.i host ,
1629.i address }
1630triple.
1631If the flags selected by the
1632.i mailer
1633include the
1634.b A
1635(aliasable) flag,
1636the
1637.i address
1638part of the triple is looked up as the key
1639(i.e., the left hand side)
1640in the alias database.
1641If there is a match, the address is deleted from the send queue
1642and all addresses on the right hand side of the alias
1643are added in place of the alias that was found.
1644This is a recursive operation,
1645so aliases found in the right hand side of the alias
1646are similarly expanded.
1647.pp
1648The alias database exists in two forms.
1649One is a text form,
1650maintained in the file
1651.i /etc/mail/aliases.
1652The aliases are of the form
1653.(b
1654name: name1, name2, ...
1655.)b
1656Only local names may be aliased;
1657e.g.,
1658.(b
1659eric@prep.ai.MIT.EDU: eric@CS.Berkeley.EDU
1660.)b
1661will not have the desired effect
1662(except on prep.ai.MIT.EDU,
1663and they probably don't want me)\**.
1664.(f
1665\**Actually, any mailer that has the `A' mailer flag set
1666will permit aliasing;
1667this is normally limited to the local mailer.
1668.)f
1669Aliases may be continued by starting any continuation lines
1670with a space or a tab or by putting a backslash directly before
1671the newline.
1672Blank lines and lines beginning with a sharp sign
1673(\c
1674.q # )
1675are comments.
1676.pp
1677The second form is processed by the
1678.i ndbm \|(3)\**
1679.(f
1680\**The
1681.i gdbm
1682package does not work.
1683.)f
1684or the Berkeley DB library.
1685This form is in the file
1686.i /etc/mail/aliases.db
1687(if using NEWDB)
1688or
1689.i /etc/mail/aliases.dir
1690and
1691.i /etc/mail/aliases.pag
1692(if using NDBM).
1693This is the form that
1694.i sendmail
1695actually uses to resolve aliases.
1696This technique is used to improve performance.
1697.pp
1698The control of search order is actually set by the service switch.
1699Essentially, the entry
1700.(b
1701O AliasFile=switch:aliases
1702.)b
1703is always added as the first alias entry;
1704also, the first alias file name without a class
1705(e.g., without
1706.q nis:
1707on the front)
1708will be used as the name of the file for a ``files'' entry
1709in the aliases switch.
1710For example, if the configuration file contains
1711.(b
1712O AliasFile=/etc/mail/aliases
1713.)b
1714and the service switch contains
1715.(b
1716aliases nis files nisplus
1717.)b
1718then aliases will first be searched in the NIS database,
1719then in /etc/mail/aliases,
1720then in the NIS+ database.
1721.pp
1722You can also use
1723.sm NIS -based
1724alias files.
1725For example, the specification:
1726.(b
1727O AliasFile=/etc/mail/aliases
1728O AliasFile=nis:mail.aliases@my.nis.domain
1729.)b
1730will first search the /etc/mail/aliases file
1731and then the map named
1732.q mail.aliases
1733in
1734.q my.nis.domain .
1735Warning: if you build your own
1736.sm NIS -based
1737alias files,
1738be sure to provide the
1739.b \-l
1740flag to
1741.i makedbm (8)
1742to map upper case letters in the keys to lower case;
1743otherwise, aliases with upper case letters in their names
1744won't match incoming addresses.
1745.pp
1746Additional flags can be added after the colon
1747exactly like a
1748.b K
1749line \(em for example:
1750.(b
1751O AliasFile=nis:\-N mail.aliases@my.nis.domain
1752.)b
1753will search the appropriate NIS map and always include null bytes in the key.
1754Also:
1755.(b
1756O AliasFile=nis:\-f mail.aliases@my.nis.domain
1757.)b
1758will prevent sendmail from downcasing the key before the alias lookup.
1759.sh 3 "Rebuilding the alias database"
1760.pp
1761The
1762.i hash
1763or
1764.i dbm
1765version of the database
1766may be rebuilt explicitly by executing the command
1767.(b
1768newaliases
1769.)b
1770This is equivalent to giving
1771.i sendmail
1772the
1773.b \-bi
1774flag:
1775.(b
1776/usr/\*(SD/sendmail \-bi
1777.)b
1778.pp
1779If you have multiple aliases databases specified,
1780the
1781.b \-bi
1782flag rebuilds all the database types it understands
1783(for example, it can rebuild NDBM databases but not NIS databases).
1784.sh 3 "Potential problems"
1785.pp
1786There are a number of problems that can occur
1787with the alias database.
1788They all result from a
1789.i sendmail
1790process accessing the DBM version
1791while it is only partially built.
1792This can happen under two circumstances:
1793One process accesses the database
1794while another process is rebuilding it,
1795or the process rebuilding the database dies
1796(due to being killed or a system crash)
1797before completing the rebuild.
1798.pp
1799Sendmail has three techniques to try to relieve these problems.
1800First, it ignores interrupts while rebuilding the database;
1801this avoids the problem of someone aborting the process
1802leaving a partially rebuilt database.
1803Second,
1804it locks the database source file during the rebuild \(em
1805but that may not work over NFS or if the file is unwritable.
1806Third,
1807at the end of the rebuild
1808it adds an alias of the form
1809.(b
1810@: @
1811.)b
1812(which is not normally legal).
1813Before
1814.i sendmail
1815will access the database,
1816it checks to insure that this entry exists\**.
1817.(f
1818\**The
1819.b AliasWait
1820option is required in the configuration
1821for this action to occur.
1822This should normally be specified.
1823.)f
1824.sh 3 "List owners"
1825.pp
1826If an error occurs on sending to a certain address,
1827say
1828.q \fIx\fP ,
1829.i sendmail
1830will look for an alias
1831of the form
1832.q owner-\fIx\fP
1833to receive the errors.
1834This is typically useful
1835for a mailing list
1836where the submitter of the list
1837has no control over the maintenance of the list itself;
1838in this case the list maintainer would be the owner of the list.
1839For example:
1840.(b
1841unix-wizards: eric@ucbarpa, wnj@monet, nosuchuser,
1842 sam@matisse
1843owner-unix-wizards: unix-wizards-request
1844unix-wizards-request: eric@ucbarpa
1845.)b
1846would cause
1847.q eric@ucbarpa
1848to get the error that will occur
1849when someone sends to
1850unix-wizards
1851due to the inclusion of
1852.q nosuchuser
1853on the list.
1854.pp
1855List owners also cause the envelope sender address to be modified.
1856The contents of the owner alias are used if they point to a single user,
1857otherwise the name of the alias itself is used.
1858For this reason, and to obey Internet conventions,
1859the
1860.q owner-
1861address normally points at the
1862.q -request
1863address; this causes messages to go out with the typical Internet convention
1864of using ``\c
1865.i list -request''
1866as the return address.
1867.sh 2 "User Information Database"
1868.pp
1869This option is deprecated, use virtusertable and genericstable instead
1870as explained in
1871.i cf/README .
1872If you have a version of
1873.i sendmail
1874with the user information database
1875compiled in,
1876and you have specified one or more databases using the
1877.b U
1878option,
1879the databases will be searched for a
1880.i user :maildrop
1881entry.
1882If found, the mail will be sent to the specified address.
1883.sh 2 "Per-User Forwarding (.forward Files)"
1884.pp
1885As an alternative to the alias database,
1886any user may put a file with the name
1887.q .forward
1888in his or her home directory.
1889If this file exists,
1890.i sendmail
1891redirects mail for that user
1892to the list of addresses listed in the .forward file.
1893Note that aliases are fully expanded before forward files are referenced.
1894For example, if the home directory for user
1895.q mckusick
1896has a .forward file with contents:
1897.(b
1898mckusick@ernie
1899kirk@calder
1900.)b
1901then any mail arriving for
1902.q mckusick
1903will be redirected to the specified accounts.
1904.pp
1905Actually, the configuration file defines a sequence of filenames to check.
1906By default, this is the user's .forward file,
1907but can be defined to be more generally using the
1908.b ForwardPath
1909option.
1910If you change this,
1911you will have to inform your user base of the change;
1912\&.forward is pretty well incorporated into the collective subconscious.
1913.sh 2 "Special Header Lines"
1914.pp
1915Several header lines have special interpretations
1916defined by the configuration file.
1917Others have interpretations built into
1918.i sendmail
1919that cannot be changed without changing the code.
1920These built-ins are described here.
1921.sh 3 "Errors-To:"
1922.pp
1923If errors occur anywhere during processing,
1924this header will cause error messages to go to
1925the listed addresses.
1926This is intended for mailing lists.
1927.pp
1928The Errors-To: header was created in the bad old days
1929when UUCP didn't understand the distinction between an envelope and a header;
1930this was a hack to provide what should now be passed
1931as the envelope sender address.
1932It should go away.
1933It is only used if the
1934.b UseErrorsTo
1935option is set.
1936.pp
1937The Errors-To: header is officially deprecated
1938and will go away in a future release.
1939.sh 3 "Apparently-To:"
1940.pp
1941RFC 822 requires at least one recipient field
1942(To:, Cc:, or Bcc: line)
1943in every message.
1944If a message comes in with no recipients listed in the message
1945then
1946.i sendmail
1947will adjust the header based on the
1948.q NoRecipientAction
1949option.
1950One of the possible actions is to add an
1951.q "Apparently-To:"
1952header line for any recipients it is aware of.
1953.pp
1954The Apparently-To: header is non-standard
1955and is both deprecated and strongly discouraged.
1956.sh 3 "Precedence"
1957.pp
1958The Precedence: header can be used as a crude control of message priority.
1959It tweaks the sort order in the queue
1960and can be configured to change the message timeout values.
1961The precedence of a message also controls how
1962delivery status notifications (DSNs)
1963are processed for that message.
1964.sh 2 "IDENT Protocol Support"
1965.pp
1966.i Sendmail
1967supports the IDENT protocol as defined in RFC 1413.
1968Note that the RFC states
1969a client should wait at least 30 seconds for a response.
1970The default Timeout.ident is 5 seconds
1971as many sites have adopted the practice of dropping IDENT queries.
1972This has lead to delays processing mail.
1973Although this enhances identification
1974of the author of an email message
1975by doing a ``call back'' to the originating system to include
1976the owner of a particular TCP connection
1977in the audit trail
1978it is in no sense perfect;
1979a determined forger can easily spoof the IDENT protocol.
1980The following description is excerpted from RFC 1413:
1981.ba +5
1982.lp
19836. Security Considerations
1984.lp
1985The information returned by this protocol is at most as trustworthy
1986as the host providing it OR the organization operating the host. For
1987example, a PC in an open lab has few if any controls on it to prevent
1988a user from having this protocol return any identifier the user
1989wants. Likewise, if the host has been compromised the information
1990returned may be completely erroneous and misleading.
1991.lp
1992The Identification Protocol is not intended as an authorization or
1993access control protocol. At best, it provides some additional
1994auditing information with respect to TCP connections. At worst, it
1995can provide misleading, incorrect, or maliciously incorrect
1996information.
1997.lp
1998The use of the information returned by this protocol for other than
1999auditing is strongly discouraged. Specifically, using Identification
2000Protocol information to make access control decisions - either as the
2001primary method (i.e., no other checks) or as an adjunct to other
2002methods may result in a weakening of normal host security.
2003.lp
2004An Identification server may reveal information about users,
2005entities, objects or processes which might normally be considered
2006private. An Identification server provides service which is a rough
2007analog of the CallerID services provided by some phone companies and
2008many of the same privacy considerations and arguments that apply to
2009the CallerID service apply to Identification. If you wouldn't run a
2010"finger" server due to privacy considerations you may not want to run
2011this protocol.
2012.ba
2013.lp
2014In some cases your system may not work properly with IDENT support
2015due to a bug in the TCP/IP implementation.
2016The symptoms will be that for some hosts
2017the SMTP connection will be closed
2018almost immediately.
2019If this is true or if you do not want to use IDENT,
2020you should set the IDENT timeout to zero;
2021this will disable the IDENT protocol.
2022.sh 1 "ARGUMENTS"
2023.pp
2024The complete list of arguments to
2025.i sendmail
2026is described in detail in Appendix A.
2027Some important arguments are described here.
2028.sh 2 "Queue Interval"
2029.pp
2030The amount of time between forking a process
2031to run through the queue is defined by the
2032.b \-q
2033flag.
2034If you run with delivery mode set to
2035.b i
2036or
2037.b b
2038this can be relatively large, since it will only be relevant
2039when a host that was down comes back up.
2040If you run in
2041.b q
2042mode it should be relatively short,
2043since it defines the maximum amount of time that a message
2044may sit in the queue.
2045(See also the MinQueueAge option.)
2046.pp
2047RFC 1123 section 5.3.1.1 says that this value should be at least 30 minutes
2048(although that probably doesn't make sense if you use ``queue-only'' mode).
2049.pp
2050Notice: the meaning of the interval time depends on whether normal
2051queue runners or persistent queue runners are used.
2052For the former, it is the time between subsequent starts of a queue run.
2053For the latter, it is the time sendmail waits after a persistent queue
2054runner has finished its work to start the next one.
2055Hence for persistent queue runners this interval should be very low,
2056typically no more than two minutes.
2057.sh 2 "Daemon Mode"
2058.pp
2059If you allow incoming mail over an IPC connection,
2060you should have a daemon running.
2061This should be set by your
2062.i /etc/rc
2063file using the
2064.b \-bd
2065flag.
2066The
2067.b \-bd
2068flag and the
2069.b \-q
2070flag may be combined in one call:
2071.(b
2072/usr/\*(SD/sendmail \-bd \-q30m
2073.)b
2074.pp
2075An alternative approach is to invoke sendmail from
2076.i inetd (8)
2077(use the
2078.b \-bs \ \-Am
2079flags to ask sendmail to speak SMTP on its standard input and output
2080and to run as MTA).
2081This works and allows you to wrap
2082.i sendmail
2083in a TCP wrapper program,
2084but may be a bit slower since the configuration file
2085has to be re-read on every message that comes in.
2086If you do this, you still need to have a
2087.i sendmail
2088running to flush the queue:
2089.(b
2090/usr/\*(SD/sendmail \-q30m
2091.)b
2092.sh 2 "Forcing the Queue"
2093.pp
2094In some cases you may find that the queue has gotten clogged for some reason.
2095You can force a queue run
2096using the
2097.b \-q
2098flag (with no value).
2099It is entertaining to use the
2100.b \-v
2101flag (verbose)
2102when this is done to watch what happens:
2103.(b
2104/usr/\*(SD/sendmail \-q \-v
2105.)b
2106.pp
2107You can also limit the jobs to those with a particular queue identifier,
2108recipient, sender, quarantine reason, or queue group
2109using one of the queue modifiers.
2110For example,
2111.q \-qRberkeley
2112restricts the queue run to jobs that have the string
2113.q berkeley
2114somewhere in one of the recipient addresses.
2115Similarly,
2116.q \-qSstring
2117limits the run to particular senders,
2118.q \-qIstring
2119limits it to particular queue identifiers, and
2120.q \-qQstring
2121limits it to particular quarantined reasons and only operated on
2122quarantined queue items, and
2123.q \-qGstring
2124limits it to a particular queue group.
2125The named queue group will be run even if it is set to have 0 runners.
2126You may also place an
2127.b !
2128before the
2129.b I
2130or
2131.b R
2132or
2133.b S
2134or
2135.b Q
2136to indicate that jobs are limited to not including a particular queue
2137identifier, recipient or sender.
2138For example,
2139.q \-q!Rseattle
2140limits the queue run to jobs that do not have the string
2141.q seattle
2142somewhere in one of the recipient addresses.
2143Should you need to terminate the queue jobs currently active then a SIGTERM
2144to the parent of the process (or processes) will cleanly stop the jobs.
2145.sh 2 "Debugging"
2146.pp
2147There are a fairly large number of debug flags
2148built into
2149.i sendmail .
2150Each debug flag has a category and a level.
2151Higher levels increase the level of debugging activity;
2152in most cases, this means to print out more information.
2153The convention is that levels greater than nine are
2154.q absurd,
2155i.e.,
2156they print out so much information that you wouldn't normally
2157want to see them except for debugging that particular piece of code.
2158.pp
2159You should
2160.b never
2161run a production sendmail server in debug mode.
2162Many of the debug flags will result in debug output being sent over the
2163SMTP channel unless the option
2164.b \-D
2165is used.
2166This will confuse many mail programs.
2167However, for testing purposes, it can be useful
2168when sending mail manually via
2169telnet to the port you are using while debugging.
2170.pp
2171A debug category is either an integer, like 42,
2172or a name, like ANSI.
2173You can specify a range of numeric debug categories
2174using the syntax 17-42.
2175You can specify a set of named debug categories using
2176a glob pattern like
2177.q sm_trace_* .
2178At present, only
2179.q *
2180and
2181.q ?
2182are supported in these glob patterns.
2183.pp
2184Debug flags are set using the
2185.b \-d
2186option;
2187the syntax is:
2188.(b
2189.ta \w'debug-categories:M 'u
2190debug-flag: \fB\-d\fP debug-list
2191debug-list: debug-option [ , debug-option ]*
2192debug-option: debug-categories [ . debug-level ]
2193debug-categories: integer | integer \- integer | category-pattern
2194category-pattern: [a-zA-Z_*?][a-zA-Z0-9_*?]*
2195debug-level: integer
2196.)b
2197where spaces are for reading ease only.
2198For example,
2199.(b
2200\-d12 Set category 12 to level 1
2201\-d12.3 Set category 12 to level 3
2202\-d3\-17 Set categories 3 through 17 to level 1
2203\-d3\-17.4 Set categories 3 through 17 to level 4
2204\-dANSI Set category ANSI to level 1
2205\-dsm_trace_*.3 Set all named categories matching sm_trace_* to level 3
2206.)b
2207For a complete list of the available debug flags
2208you will have to look at the code
2209and the
2210.i TRACEFLAGS
2211file in the sendmail distribution
2212(they are too dynamic to keep this document up to date).
2213For a list of named debug categories in the sendmail binary, use
2214.(b
2215ident /usr/sbin/sendmail | grep Debug
2216.)b
2217.sh 2 "Changing the Values of Options"
2218.pp
2219Options can be overridden using the
2220.b \-o
2221or
2222.b \-O
2223command line flags.
2224For example,
2225.(b
2226/usr/\*(SD/sendmail \-oT2m
2227.)b
2228sets the
2229.b T
2230(timeout) option to two minutes
2231for this run only;
2232the equivalent line using the long option name is
2233.(b
2234/usr/\*(SD/sendmail -OTimeout.queuereturn=2m
2235.)b
2236.pp
2237Some options have security implications.
2238Sendmail allows you to set these,
2239but relinquishes its set-user-ID or set-group-ID permissions thereafter\**.
2240.(f
2241\**That is, it sets its effective uid to the real uid;
2242thus, if you are executing as root,
2243as from root's crontab file or during system startup
2244the root permissions will still be honored.
2245.)f
2246.sh 2 "Trying a Different Configuration File"
2247.pp
2248An alternative configuration file
2249can be specified using the
2250.b \-C
2251flag; for example,
2252.(b
2253/usr/\*(SD/sendmail \-Ctest.cf \-oQ/tmp/mqueue
2254.)b
2255uses the configuration file
2256.i test.cf
2257instead of the default
2258.i /etc/mail/sendmail.cf.
2259If the
2260.b \-C
2261flag has no value
2262it defaults to
2263.i sendmail.cf
2264in the current directory.
2265.pp
2266.i Sendmail
2267gives up set-user-ID root permissions
2268(if it has been installed set-user-ID root)
2269when you use this flag, so it is common to use a publicly writable directory
2270(such as /tmp)
2271as the queue directory (QueueDirectory or Q option) while testing.
2272.sh 2 "Logging Traffic"
2273.pp
2274Many SMTP implementations do not fully implement the protocol.
2275For example, some personal computer based SMTPs
2276do not understand continuation lines in reply codes.
2277These can be very hard to trace.
2278If you suspect such a problem, you can set traffic logging using the
2279.b \-X
2280flag.
2281For example,
2282.(b
2283/usr/\*(SD/sendmail \-X /tmp/traffic \-bd
2284.)b
2285will log all traffic in the file
2286.i /tmp/traffic .
2287.pp
2288This logs a lot of data very quickly and should
2289.b NEVER
2290be used
2291during normal operations.
2292After starting up such a daemon,
2293force the errant implementation to send a message to your host.
2294All message traffic in and out of
2295.i sendmail ,
2296including the incoming SMTP traffic,
2297will be logged in this file.
2298.sh 2 "Testing Configuration Files"
2299.pp
2300When you build a configuration table,
2301you can do a certain amount of testing
2302using the
2303.q "test mode"
2304of
2305.i sendmail .
2306For example,
2307you could invoke
2308.i sendmail
2309as:
2310.(b
2311sendmail \-bt \-Ctest.cf
2312.)b
2313which would read the configuration file
2314.q test.cf
2315and enter test mode.
2316In this mode,
2317you enter lines of the form:
2318.(b
2319rwset address
2320.)b
2321where
2322.i rwset
2323is the rewriting set you want to use
2324and
2325.i address
2326is an address to apply the set to.
2327Test mode shows you the steps it takes
2328as it proceeds,
2329finally showing you the address it ends up with.
2330You may use a comma separated list of rwsets
2331for sequential application of rules to an input.
2332For example:
2333.(b
23343,1,21,4 monet:bollard
2335.)b
2336first applies ruleset three to the input
2337.q monet:bollard.
2338Ruleset one is then applied to the output of ruleset three,
2339followed similarly by rulesets twenty-one and four.
2340.pp
2341If you need more detail,
2342you can also use the
2343.q \-d21
2344flag to turn on more debugging.
2345For example,
2346.(b
2347sendmail \-bt \-d21.99
2348.)b
2349turns on an incredible amount of information;
2350a single word address
2351is probably going to print out several pages worth of information.
2352.pp
2353You should be warned that internally,
2354.i sendmail
2355applies ruleset 3 to all addresses.
2356In test mode
2357you will have to do that manually.
2358For example, older versions allowed you to use
2359.(b
23600 bruce@broadcast.sony.com
2361.)b
2362This version requires that you use:
2363.(b
23643,0 bruce@broadcast.sony.com
2365.)b
2366.pp
2367As of version 8.7,
2368some other syntaxes are available in test mode:
2369.nr ii 1i
2370.ip \&.D\|x\|value
2371defines macro
2372.i x
2373to have the indicated
2374.i value .
2375This is useful when debugging rules that use the
2376.b $& \c
2377.i x
2378syntax.
2379.ip \&.C\|c\|value
2380adds the indicated
2381.i value
2382to class
2383.i c .
2384.ip \&=S\|ruleset
2385dumps the contents of the indicated ruleset.
2386.ip \-d\|debug-spec
2387is equivalent to the command-line flag.
2388.lp
2389Version 8.9 introduced more features:
2390.nr ii 1i
2391.ip ?
2392shows a help message.
2393.ip =M
2394display the known mailers.
2395.ip $m
2396print the value of macro m.
2397.ip $=c
2398print the contents of class c.
2399.ip /mx\ host
2400returns the MX records for `host'.
2401.ip /parse\ address
2402parse address, returning the value of
2403.i crackaddr ,
2404and the parsed address.
2405.ip /try\ mailer\ addr
2406rewrite address into the form it will have when
2407presented to the indicated mailer.
2408.ip /tryflags\ flags
2409set flags used by parsing. The flags can be `H' for
2410Header or `E' for Envelope, and `S' for Sender or `R'
2411for Recipient. These can be combined, `HR' sets
2412flags for header recipients.
2413.ip /canon\ hostname
2414try to canonify hostname.
2415.ip /map\ mapname\ key
2416look up `key' in the indicated `mapname'.
2417.ip /quit
2418quit address test mode.
2419.lp
2420.sh 2 "Persistent Host Status Information"
2421.pp
2422When
2423.b HostStatusDirectory
2424is enabled,
2425information about the status of hosts is maintained on disk
2426and can thus be shared between different instantiations of
2427.i sendmail .
2428The status of the last connection with each remote host
2429may be viewed with the command:
2430.(b
2431sendmail \-bh
2432.)b
2433This information may be flushed with the command:
2434.(b
2435sendmail \-bH
2436.)b
2437Flushing the information prevents new
2438.i sendmail
2439processes from loading it,
2440but does not prevent existing processes from using the status information
2441that they already have.
2442.sh 1 "TUNING"
2443.pp
2444There are a number of configuration parameters
2445you may want to change,
2446depending on the requirements of your site.
2447Most of these are set
2448using an option in the configuration file.
2449For example,
2450the line
2451.q "O Timeout.queuereturn=5d"
2452sets option
2453.q Timeout.queuereturn
2454to the value
2455.q 5d
2456(five days).
2457.pp
2458Most of these options have appropriate defaults for most sites.
2459However,
2460sites having very high mail loads may find they need to tune them
2461as appropriate for their mail load.
2462In particular,
2463sites experiencing a large number of small messages,
2464many of which are delivered to many recipients,
2465may find that they need to adjust the parameters
2466dealing with queue priorities.
2467.pp
2468All versions of
2469.i sendmail
2470prior to 8.7
2471had single character option names.
2472As of 8.7,
2473options have long (multi-character names).
2474Although old short names are still accepted,
2475most new options do not have short equivalents.
2476.pp
2477This section only describes the options you are most likely
2478to want to tweak;
2479read section
2480.\"XREF
24815
2482for more details.
2483.sh 2 "Timeouts"
2484.pp
2485All time intervals are set
2486using a scaled syntax.
2487For example,
2488.q 10m
2489represents ten minutes, whereas
2490.q 2h30m
2491represents two and a half hours.
2492The full set of scales is:
2493.(b
2494.ta 4n
2495s seconds
2496m minutes
2497h hours
2498d days
2499w weeks
2500.)b
2501.sh 3 "Queue interval"
2502.pp
2503The argument to the
2504.b \-q
2505flag specifies how often a sub-daemon will run the queue.
2506This is typically set to between fifteen minutes and one hour.
2507If not set, or set to zero,
2508the queue will not be run automatically.
2509RFC 1123 section 5.3.1.1 recommends that this be at least 30 minutes.
2510Should you need to terminate the queue jobs currently active then a SIGTERM
2511to the parent of the process (or processes) will cleanly stop the jobs.
2512.sh 3 "Read timeouts"
2513.pp
2514Timeouts all have option names
2515.q Timeout.\fIsuboption\fP .
2516Most of these control SMTP operations.
2517The recognized
2518.i suboption s,
2519their default values, and the minimum values
2520allowed by RFC 2821 section 4.5.3.2 (or RFC 1123 section 5.3.2) are:
2521.nr ii 1i
2522.ip connect
2523The time to wait for an SMTP connection to open
2524(the
2525.i connect (2)
2526system call)
2527[0, unspecified].
2528If zero, uses the kernel default.
2529In no case can this option extend the timeout
2530longer than the kernel provides, but it can shorten it.
2531This is to get around kernels that provide an absurdly long connection timeout
2532(90 minutes in one case).
2533.ip iconnect
2534The same as
2535.i connect,
2536except it applies only to the initial attempt to connect to a host
2537for a given message
2538[0, unspecified].
2539The concept is that this should be very short (a few seconds);
2540hosts that are well connected and responsive will thus be serviced immediately.
2541Hosts that are slow will not hold up other deliveries in the initial
2542delivery attempt.
2543.ip aconnect
2544[0, unspecified]
2545The overall timeout waiting for all connection for a single delivery
2546attempt to succeed.
2547If 0, no overall limit is applied.
2548This can be used to restrict the total amount of time trying to connect to
2549a long list of host that could accept an e-mail for the recipient.
2550This timeout does not apply to
2551.b FallbackMXhost ,
2552i.e., if the time is exhausted, the
2553.b FallbackMXhost
2554is tried next.
2555.ip initial
2556The wait for the initial 220 greeting message
2557[5m, 5m].
2558.ip helo
2559The wait for a reply from a HELO or EHLO command
2560[5m, unspecified].
2561This may require a host name lookup, so
2562five minutes is probably a reasonable minimum.
2563.ip mail\(dg
2564The wait for a reply from a MAIL command
2565[10m, 5m].
2566.ip rcpt\(dg
2567The wait for a reply from a RCPT command
2568[1h, 5m].
2569This should be long
2570because it could be pointing at a list
2571that takes a long time to expand
2572(see below).
2573.ip datainit\(dg
2574The wait for a reply from a DATA command
2575[5m, 2m].
2576.ip datablock\(dg\(dd
2577The wait for reading a data block
2578(that is, the body of the message).
2579[1h, 3m].
2580This should be long because it also applies to programs
2581piping input to
2582.i sendmail
2583which have no guarantee of promptness.
2584.ip datafinal\(dg
2585The wait for a reply from the dot terminating a message.
2586[1h, 10m].
2587If this is shorter than the time actually needed
2588for the receiver to deliver the message,
2589duplicates will be generated.
2590This is discussed in RFC 1047.
2591.ip rset
2592The wait for a reply from a RSET command
2593[5m, unspecified].
2594.ip quit
2595The wait for a reply from a QUIT command
2596[2m, unspecified].
2597.ip misc
2598The wait for a reply from miscellaneous (but short) commands
2599such as NOOP (no-operation) and VERB (go into verbose mode).
2600[2m, unspecified].
2601.ip command\(dg\(dd
2602In server SMTP,
2603the time to wait for another command.
2604[1h, 5m].
2605.ip ident\(dd
2606The timeout waiting for a reply to an IDENT query
2607[5s\**, unspecified].
2608.(f
2609\**On some systems the default is zero to turn the protocol off entirely.
2610.)f
2611.ip lhlo
2612The wait for a reply to an LMTP LHLO command
2613[2m, unspecified].
2614.ip auth
2615The timeout for a reply in an SMTP AUTH dialogue
2616[10m, unspecified].
2617.ip starttls
2618The timeout for a reply to an SMTP STARTTLS command and the TLS handshake
2619[1h, unspecified].
2620.ip fileopen\(dd
2621The timeout for opening .forward and :include: files [60s, none].
2622.ip control\(dd
2623The timeout for a complete control socket transaction to complete [2m, none].
2624.ip hoststatus\(dd
2625How long status information about a host
2626(e.g., host down)
2627will be cached before it is considered stale
2628[30m, unspecified].
2629.ip resolver.retrans\(dd
2630The resolver's
2631retransmission time interval
2632(in seconds)
2633[varies].
2634Sets both
2635.i Timeout.resolver.retrans.first
2636and
2637.i Timeout.resolver.retrans.normal .
2638.ip resolver.retrans.first\(dd
2639The resolver's
2640retransmission time interval
2641(in seconds)
2642for the first attempt to
2643deliver a message
2644[varies].
2645.ip resolver.retrans.normal\(dd
2646The resolver's
2647retransmission time interval
2648(in seconds)
2649for all resolver lookups
2650except the first delivery attempt
2651[varies].
2652.ip resolver.retry\(dd
2653The number of times
2654to retransmit a resolver query.
2655Sets both
2656.i Timeout.resolver.retry.first
2657and
2658.i Timeout.resolver.retry.normal
2659[varies].
2660.ip resolver.retry.first\(dd
2661The number of times
2662to retransmit a resolver query
2663for the first attempt
2664to deliver a message
2665[varies].
2666.ip resolver.retry.normal\(dd
2667The number of times
2668to retransmit a resolver query
2669for all resolver lookups
2670 except the first delivery attempt
2671[varies].
2672.lp
2673For compatibility with old configuration files,
2674if no
2675.i suboption
2676is specified,
2677all the timeouts marked with
2678.DG
2679(\(dg) are set to the indicated value.
2680All but those marked with
2681.DD
2682(\(dd) apply to client SMTP.
2683.pp
2684For example, the lines:
2685.(b
2686O Timeout.command=25m
2687O Timeout.datablock=3h
2688.)b
2689sets the server SMTP command timeout to 25 minutes
2690and the input data block timeout to three hours.
2691.sh 3 "Message timeouts"
2692.pp
2693After sitting in the queue for a few days,
2694an undeliverable message will time out.
2695This is to insure that at least the sender is aware
2696of the inability to send a message.
2697The timeout is typically set to five days.
2698It is sometimes considered convenient to also send a warning message
2699if the message is in the queue longer than a few hours
2700(assuming you normally have good connectivity;
2701if your messages normally took several hours to send
2702you wouldn't want to do this because it wouldn't be an unusual event).
2703These timeouts are set using the
2704.b Timeout.queuereturn
2705and
2706.b Timeout.queuewarn
2707options in the configuration file
2708(previously both were set using the
2709.b T
2710option).
2711.pp
2712If the message is submitted using the
2713.sm NOTIFY
2714.sm SMTP
2715extension,
2716warning messages will only be sent if
2717.sm NOTIFY=DELAY
2718is specified.
2719The queuereturn and queuewarn timeouts
2720can be further qualified with a tag based on the Precedence: field
2721in the message;
2722they must be one of
2723.q urgent
2724(indicating a positive non-zero precedence),
2725.q normal
2726(indicating a zero precedence), or
2727.q non-urgent
2728(indicating negative precedences).
2729For example, setting
2730.q Timeout.queuewarn.urgent=1h
2731sets the warning timeout for urgent messages only
2732to one hour.
2733The default if no precedence is indicated
2734is to set the timeout for all precedences.
2735If the message has a normal (default) precedence
2736and it is a delivery status notification (DSN),
2737.b Timeout.queuereturn.dsn
2738and
2739.b Timeout.queuewarn.dsn
2740can be used to give an alternative warn and return time
2741for DSNs.
2742The value "now" can be used for
2743-O Timeout.queuereturn
2744to return entries immediately during a queue run,
2745e.g., to bounce messages independent of their time in the queue.
2746.pp
2747Since these options are global,
2748and since you cannot know
2749.i "a priori"
2750how long another host outside your domain will be down,
2751a five day timeout is recommended.
2752This allows a recipient to fix the problem even if it occurs
2753at the beginning of a long weekend.
2754RFC 1123 section 5.3.1.1 says that this parameter
2755should be ``at least 4\-5 days''.
2756.pp
2757The
2758.b Timeout.queuewarn
2759value can be piggybacked on the
2760.b T
2761option by indicating a time after which
2762a warning message should be sent;
2763the two timeouts are separated by a slash.
2764For example, the line
2765.(b
2766OT5d/4h
2767.)b
2768causes email to fail after five days,
2769but a warning message will be sent after four hours.
2770This should be large enough that the message will have been tried
2771several times.
2772.sh 2 "Forking During Queue Runs"
2773.pp
2774By setting the
2775.b ForkEachJob
2776(\c
2777.b Y )
2778option,
2779.i sendmail
2780will fork before each individual message
2781while running the queue.
2782This option was used with earlier releases to prevent
2783.i sendmail
2784from consuming large amounts of memory.
2785It should no longer be necessary with
2786.i sendmail
27878.12.
2788If the
2789.b ForkEachJob
2790option is not set,
2791.i sendmail
2792will keep track of hosts that are down during a queue run,
2793which can improve performance dramatically.
2794.pp
2795If the
2796.b ForkEachJob
2797option is set,
2798.i sendmail
2799cannot use connection caching.
2800.sh 2 "Queue Priorities"
2801.pp
2802Every message is assigned a priority when it is first instantiated,
2803consisting of the message size (in bytes)
2804offset by the message class
2805(which is determined from the Precedence: header)
2806times the
2807.q "work class factor"
2808and the number of recipients times the
2809.q "work recipient factor."
2810The priority is used to order the queue.
2811Higher numbers for the priority mean that the message will be processed later
2812when running the queue.
2813.pp
2814The message size is included so that large messages are penalized
2815relative to small messages.
2816The message class allows users to send
2817.q "high priority"
2818messages by including a
2819.q Precedence:
2820field in their message;
2821the value of this field is looked up in the
2822.b P
2823lines of the configuration file.
2824Since the number of recipients affects the amount of load a message presents
2825to the system,
2826this is also included into the priority.
2827.pp
2828The recipient and class factors
2829can be set in the configuration file using the
2830.b RecipientFactor
2831(\c
2832.b y )
2833and
2834.b ClassFactor
2835(\c
2836.b z )
2837options respectively.
2838They default to 30000 (for the recipient factor)
2839and 1800
2840(for the class factor).
2841The initial priority is:
2842.EQ
2843pri = msgsize - (class times bold ClassFactor) + (nrcpt times bold RecipientFactor)
2844.EN
2845(Remember, higher values for this parameter actually mean
2846that the job will be treated with lower priority.)
2847.pp
2848The priority of a job can also be adjusted each time it is processed
2849(that is, each time an attempt is made to deliver it)
2850using the
2851.q "work time factor,"
2852set by the
2853.b RetryFactor
2854(\c
2855.b Z )
2856option.
2857This is added to the priority,
2858so it normally decreases the precedence of the job,
2859on the grounds that jobs that have failed many times
2860will tend to fail again in the future.
2861The
2862.b RetryFactor
2863option defaults to 90000.
2864.sh 2 "Load Limiting"
2865.pp
2866.i Sendmail
2867can be asked to queue (but not deliver) mail
2868if the system load average gets too high using the
2869.b QueueLA
2870(\c
2871.b x )
2872option.
2873When the load average exceeds the value of the
2874.b QueueLA
2875option, the delivery mode is set to
2876.b q
2877(queue only) if the
2878.b QueueFactor
2879(\c
2880.b q )
2881option divided by the difference in the current load average and the
2882.b QueueLA
2883option plus one
2884is less than the priority of the message \(em
2885that is, the message is queued iff:
2886.EQ
2887pri > { bold QueueFactor } over { LA - { bold QueueLA } + 1 }
2888.EN
2889The
2890.b QueueFactor
2891option defaults to 600000,
2892so each point of load average is worth 600000 priority points
2893(as described above).
2894.pp
2895For drastic cases, the
2896.b RefuseLA
2897(\c
2898.b X )
2899option defines a load average at which
2900.i sendmail
2901will refuse to accept network connections.
2902Locally generated mail, i.e., mail which is not submitted via SMTP
2903(including incoming UUCP mail),
2904is still accepted.
2905Notice that the MSP submits mail to the MTA via SMTP, and hence
2906mail will be queued in the client queue in such a case.
2907Therefore it is necessary to run the client mail queue periodically.
2908.sh 2 "Resource Limits"
2909.pp
2910.i Sendmail
2911has several parameters to control resource usage.
2912Besides those mentionted in the previous section, there are at least
2913.b MaxDaemonChildren ,
2914.b ConnectionRateThrottle ,
2915.b MaxQueueChildren ,
2916and
2917.b MaxRunnersPerQueue .
2918The latter two limit the number of
2919.i sendmail
2920processes that operate on the queue.
2921These are discussed in the section
2922``Queue Group Declaration''.
2923The former two can be used to limit the number of incoming connections.
2924Their appropriate values depend on the host operating system and
2925the hardware, e.g., amount of memory.
2926In many situations it might be useful to set limits to prevent
2927to have too many
2928.i sendmail
2929processes, however, these limits can be abused to mount a
2930denial of service attack.
2931For example, if
2932.b MaxDaemonChildren=10
2933then an attacker needs to open only 10 SMTP sessions to the server,
2934leave them idle for most of the time,
2935and no more connections will be accepted.
2936If this option is set then the timeouts used in a SMTP session
2937should be lowered from their default values to
2938their minimum values as specified in RFC 2821 and listed in
2939section
2940.\"XREF
29414.1.2.
2942.sh 2 "Measures against Denial of Service Attacks"
2943.pp
2944.i Sendmail
2945has some built-in measures against simple denial of service (DoS) attacks.
2946The SMTP server by default slows down if too many bad commands are
2947issued or if some commands are repeated too often within a session.
2948Details can be found in the source file
2949.b sendmail/srvrsmtp.c
2950by looking for the macro definitions of
2951.b MAXBADCOMMANDS ,
2952.b MAXNOOPCOMMANDS ,
2953.b MAXHELOCOMMANDS ,
2954.b MAXVRFYCOMMANDS ,
2955and
2956.b MAXETRNCOMMANDS .
2957If an SMTP command is issued more often than the corresponding
2958.b MAXcmdCOMMANDS
2959value, then the response is delayed exponentially,
2960starting with a sleep time of one second,
2961up to a maximum of four minutes (as defined by
2962.b MAXTIMEOUT ).
2963If the option
2964.b MaxDaemonChildren
2965is set to a value greater than zero,
2966then this could make a DoS attack even worse since it
2967keeps a connection open longer than necessary.
2968Therefore a connection is terminated with a 421 SMTP reply code
2969if the number of commands exceeds the limit by a factor of two and
2970.b MAXBADCOMMANDS
2971is set to a value greater than zero (the default is 25).
2972.sh 2 "Delivery Mode"
2973.pp
2974There are a number of delivery modes that
2975.i sendmail
2976can operate in,
2977set by the
2978.b DeliveryMode
2979(\c
2980.b d )
2981configuration option.
2982These modes
2983specify how quickly mail will be delivered.
2984Legal modes are:
2985.(b
2986.ta 4n
2987i deliver interactively (synchronously)
2988b deliver in background (asynchronously)
2989q queue only (don't deliver)
2990d defer delivery attempts (don't deliver)
2991.)b
2992There are tradeoffs.
2993Mode
2994.q i
2995gives the sender the quickest feedback,
2996but may slow down some mailers and
2997is hardly ever necessary.
2998Mode
2999.q b
3000delivers promptly but
3001can cause large numbers of processes
3002if you have a mailer that takes a long time to deliver a message.
3003Mode
3004.q q
3005minimizes the load on your machine,
3006but means that delivery may be delayed for up to the queue interval.
3007Mode
3008.q d
3009is identical to mode
3010.q q
3011except that it also prevents lookups in maps including the
3012.b -D
3013flag from working during the initial queue phase;
3014it is intended for ``dial on demand'' sites where DNS lookups
3015might cost real money.
3016Some simple error messages
3017(e.g., host unknown during the SMTP protocol)
3018will be delayed using this mode.
3019Mode
3020.q b
3021is the usual default.
3022.pp
3023If you run in mode
3024.q q
3025(queue only),
3026.q d
3027(defer),
3028or
3029.q b
3030(deliver in background)
3031.i sendmail
3032will not expand aliases and follow .forward files
3033upon initial receipt of the mail.
3034This speeds up the response to RCPT commands.
3035Mode
3036.q i
3037should not be used by the SMTP server.
3038.sh 2 "Log Level"
3039.pp
3040The level of logging can be set for
3041.i sendmail .
3042The default using a standard configuration table is level 9.
3043The levels are as follows:
3044.nr ii 0.5i
3045.ip 0
3046Minimal logging.
3047.ip 1
3048Serious system failures and potential security problems.
3049.ip 2
3050Lost communications (network problems) and protocol failures.
3051.ip 3
3052Other serious failures, malformed addresses, transient forward/include
3053errors, connection timeouts.
3054.ip 4
3055Minor failures, out of date alias databases, connection rejections
3056via check_ rulesets.
3057.ip 5
3058Message collection statistics.
3059.ip 6
3060Creation of error messages,
3061VRFY and EXPN commands.
3062.ip 7
3063Delivery failures (host or user unknown, etc.).
3064.ip 8
3065Successful deliveries and alias database rebuilds.
3066.ip 9
3067Messages being deferred
3068(due to a host being down, etc.).
3069.ip 10
3070Database expansion (alias, forward, and userdb lookups)
3071and authentication information.
3072.ip 11
3073NIS errors and end of job processing.
3074.ip 12
3075Logs all SMTP connections.
3076.ip 13
3077Log bad user shells, files with improper permissions, and other
3078questionable situations.
3079.ip 14
3080Logs refused connections.
3081.ip 15
3082Log all incoming and outgoing SMTP commands.
3083.ip 20
3084Logs attempts to run locked queue files.
3085These are not errors,
3086but can be useful to note if your queue appears to be clogged.
3087.ip 30
3088Lost locks (only if using lockf instead of flock).
3089.lp
3090Additionally,
3091values above 64 are reserved for extremely verbose debugging output.
3092No normal site would ever set these.
3093.sh 2 "File Modes"
3094.pp
3095The modes used for files depend on what functionality you want
3096and the level of security you require.
3097In many cases
3098.i sendmail
3099does careful checking of the modes
3100of files and directories
3101to avoid accidental compromise;
3102if you want to make it possible to have group-writable support files
3103you may need to use the
3104.b DontBlameSendmail
3105option to turn off some of these checks.
3106.sh 3 "To suid or not to suid?"
3107.pp
3108.i Sendmail
3109is no longer installed
3110set-user-ID to root.
3111sendmail/SECURITY
3112explains how to configure and install
3113.i sendmail
3114without set-user-ID to root but set-group-ID
3115which is the default configuration starting with 8.12.
3116.pp
3117The daemon usually runs as root, unless other measures are taken.
3118At the point where
3119.i sendmail
3120is about to
3121.i exec \|(2)
3122a mailer,
3123it checks to see if the userid is zero (root);
3124if so,
3125it resets the userid and groupid to a default
3126(set by the
3127.b U=
3128equate in the mailer line;
3129if that is not set, the
3130.b DefaultUser
3131option is used).
3132This can be overridden
3133by setting the
3134.b S
3135flag to the mailer
3136for mailers that are trusted
3137and must be called as root.
3138However,
3139this will cause mail processing
3140to be accounted
3141(using
3142.i sa \|(8))
3143to root
3144rather than to the user sending the mail.
3145.pp
3146A middle ground is to set the
3147.b RunAsUser
3148option.
3149This causes
3150.i sendmail
3151to become the indicated user as soon as it has done the startup
3152that requires root privileges
3153(primarily, opening the
3154.sm SMTP
3155socket).
3156If you use
3157.b RunAsUser ,
3158the queue directory
3159(normally
3160.i /var/spool/mqueue )
3161should be owned by that user,
3162and all files and databases
3163(including user
3164.i \&.forward
3165files,
3166alias files,
3167:include: files,
3168and external databases)
3169must be readable by that user.
3170Also, since sendmail will not be able to change its uid,
3171delivery to programs or files will be marked as unsafe,
3172e.g., undeliverable,
3173in
3174.i \&.forward ,
3175aliases,
3176and :include: files.
3177Administrators can override this by setting the
3178.b DontBlameSendmail
3179option to the setting
3180.b NonRootSafeAddr .
3181.b RunAsUser
3182is probably best suited for firewall configurations
3183that don't have regular user logins.
3184If the option is used on a system which performs local delivery,
3185then the local delivery agent must have the proper permissions
3186(i.e., usually set-user-ID root)
3187since it will be invoked by the
3188.b RunAsUser ,
3189not by root.
3190.sh 3 "Turning off security checks"
3191.pp
3192.i Sendmail
3193is very particular about the modes of files that it reads or writes.
3194For example, by default it will refuse to read most files
3195that are group writable
3196on the grounds that they might have been tampered with
3197by someone other than the owner;
3198it will even refuse to read files in group writable directories.
3199Also, sendmail will refuse to create a new aliases database in an
3200unsafe directory. You can get around this by manually creating the
3201database file as a trusted user ahead of time and then rebuilding the
3202aliases database with
3203.b newaliases .
3204.pp
3205If you are
3206.i quite
3207sure that your configuration is safe and you want
3208.i sendmail
3209to avoid these security checks,
3210you can turn off certain checks using the
3211.b DontBlameSendmail
3212option.
3213This option takes one or more names that disable checks.
3214In the descriptions that follow,
3215.q "unsafe directory"
3216means a directory that is writable by anyone other than the owner.
3217The values are:
3218.nr ii 0.5i
3219.ip Safe
3220No special handling.
3221.ip AssumeSafeChown
3222Assume that the
3223.i chown
3224system call is restricted to root.
3225Since some versions of UNIX permit regular users
3226to give away their files to other users on some filesystems,
3227.i sendmail
3228often cannot assume that a given file was created by the owner,
3229particularly when it is in a writable directory.
3230You can set this flag if you know that file giveaway is restricted
3231on your system.
3232.ip ClassFileInUnsafeDirPath
3233When reading class files (using the
3234.b F
3235line in the configuration file),
3236allow files that are in unsafe directories.
3237.ip DontWarnForwardFileInUnsafeDirPath
3238Prevent logging of
3239unsafe directory path warnings
3240for non-existent forward files.
3241.ip ErrorHeaderInUnsafeDirPath
3242Allow the file named in the
3243.b ErrorHeader
3244option to be in an unsafe directory.
3245.ip FileDeliveryToHardLink
3246Allow delivery to files that are hard links.
3247.ip FileDeliveryToSymLink
3248Allow delivery to files that are symbolic links.
3249.ip ForwardFileInGroupWritableDirPath
3250Allow
3251.i \&.forward
3252files in group writable directories.
3253.ip ForwardFileInUnsafeDirPath
3254Allow
3255.i \&.forward
3256files in unsafe directories.
3257.ip ForwardFileInUnsafeDirPathSafe
3258Allow a
3259.i \&.forward
3260file that is in an unsafe directory to include references
3261to program and files.
3262.ip GroupReadableKeyFile
3263Accept a group-readable key file for STARTTLS.
3264.ip GroupReadableSASLDBFile
3265Accept a group-readable Cyrus SASL password file.
3266.ip GroupWritableAliasFile
3267Allow group-writable alias files.
3268.ip GroupWritableDirPathSafe
3269Change the definition of
3270.q "unsafe directory"
3271to consider group-writable directories to be safe.
3272World-writable directories are always unsafe.
3273.ip GroupWritableForwardFile
3274Allow group writable
3275.i \&.forward
3276files.
3277.ip GroupWritableForwardFileSafe
3278Accept group-writable
3279.i \&.forward
3280files as safe for program and file delivery.
3281.ip GroupWritableIncludeFile
3282Allow group wriable
3283.i :include:
3284files.
3285.ip GroupWritableIncludeFileSafe
3286Accept group-writable
3287.i :include:
3288files as safe for program and file delivery.
3289.ip GroupWritableSASLDBFile
3290Accept a group-writable Cyrus SASL password file.
3291.ip HelpFileInUnsafeDirPath
3292Allow the file named in the
3293.b HelpFile
3294option to be in an unsafe directory.
3295.ip IncludeFileInGroupWritableDirPath
3296Allow
3297.i :include:
3298files in group writable directories.
3299.ip IncludeFileInUnsafeDirPath
3300Allow
3301.i :include:
3302files in unsafe directories.
3303.ip IncludeFileInUnsafeDirPathSafe
3304Allow a
3305.i :include:
3306file that is in an unsafe directory to include references
3307to program and files.
3308.ip InsufficientEntropy
3309Try to use STARTTLS even if the PRNG for OpenSSL is not properly seeded
3310despite the security problems.
3311.ip LinkedAliasFileInWritableDir
3312Allow an alias file that is a link in a writable directory.
3313.ip LinkedClassFileInWritableDir
3314Allow class files that are links in writable directories.
3315.ip LinkedForwardFileInWritableDir
3316Allow
3317.i \&.forward
3318files that are links in writable directories.
3319.ip LinkedIncludeFileInWritableDir
3320Allow
3321.i :include:
3322files that are links in writable directories.
3323.ip LinkedMapInWritableDir
3324Allow map files that are links in writable directories.
3325This includes alias database files.
3326.ip LinkedServiceSwitchFileInWritableDir
3327Allow the service switch file to be a link
3328even if the directory is writable.
3329.ip MapInUnsafeDirPath
3330Allow maps (e.g.,
3331.i hash ,
3332.i btree ,
3333and
3334.i dbm
3335files)
3336in unsafe directories.
3337This includes alias database files.
3338.ip NonRootSafeAddr
3339Do not mark file and program deliveries as unsafe
3340if sendmail is not running with root privileges.
3341.ip RunProgramInUnsafeDirPath
3342Run programs that are in writable directories without logging a warning.
3343.ip RunWritableProgram
3344Run programs that are group- or world-writable without logging a warning.
3345.ip TrustStickyBit
3346Allow group or world writable directories
3347if the sticky bit is set on the directory.
3348Do not set this on systems which do not honor
3349the sticky bit on directories.
3350.ip WorldWritableAliasFile
3351Accept world-writable alias files.
3352.ip WorldWritableForwardfile
3353Allow world writable
3354.i \&.forward
3355files.
3356.ip WorldWritableIncludefile
3357Allow world wriable
3358.i :include:
3359files.
3360.ip WriteMapToHardLink
3361Allow writes to maps that are hard links.
3362.ip WriteMapToSymLink
3363Allow writes to maps that are symbolic links.
3364.ip WriteStatsToHardLink
3365Allow the status file to be a hard link.
3366.ip WriteStatsToSymLink
3367Allow the status file to be a symbolic link.
3368.sh 2 "Connection Caching"
3369.pp
3370When processing the queue,
3371.i sendmail
3372will try to keep the last few open connections open
3373to avoid startup and shutdown costs.
3374This only applies to IPC and LPC connections.
3375.pp
3376When trying to open a connection
3377the cache is first searched.
3378If an open connection is found, it is probed to see if it is still active
3379by sending a
3380.sm RSET
3381command.
3382It is not an error if this fails;
3383instead, the connection is closed and reopened.
3384.pp
3385Two parameters control the connection cache.
3386The
3387.b ConnectionCacheSize
3388(\c
3389.b k )
3390option defines the number of simultaneous open connections
3391that will be permitted.
3392If it is set to zero,
3393connections will be closed as quickly as possible.
3394The default is one.
3395This should be set as appropriate for your system size;
3396it will limit the amount of system resources that
3397.i sendmail
3398will use during queue runs.
3399Never set this higher than 4.
3400.pp
3401The
3402.b ConnectionCacheTimeout
3403(\c
3404.b K )
3405option specifies the maximum time that any cached connection
3406will be permitted to idle.
3407When the idle time exceeds this value
3408the connection is closed.
3409This number should be small
3410(under ten minutes)
3411to prevent you from grabbing too many resources
3412from other hosts.
3413The default is five minutes.
3414.sh 2 "Name Server Access"
3415.pp
3416Control of host address lookups is set by the
3417.b hosts
3418service entry in your service switch file.
3419If you are on a system that has built-in service switch support
3420(e.g., Ultrix, Solaris, or DEC OSF/1)
3421then your system is probably configured properly already.
3422Otherwise,
3423.i sendmail
3424will consult the file
3425.b /etc/mail/service.switch ,
3426which should be created.
3427.i Sendmail
3428only uses two entries:
3429.b hosts
3430and
3431.b aliases ,
3432although system routines may use other services
3433(notably the
3434.b passwd
3435service for user name lookups by
3436.i getpwname ).
3437.pp
3438However, some systems (such as SunOS 4.X)
3439will do DNS lookups
3440regardless of the setting of the service switch entry.
3441In particular, the system routine
3442.i gethostbyname (3)
3443is used to look up host names,
3444and many vendor versions try some combination of DNS, NIS,
3445and file lookup in /etc/hosts
3446without consulting a service switch.
3447.i Sendmail
3448makes no attempt to work around this problem,
3449and the DNS lookup will be done anyway.
3450If you do not have a nameserver configured at all,
3451such as at a UUCP-only site,
3452.i sendmail
3453will get a
3454.q "connection refused"
3455message when it tries to connect to the name server.
3456If the
3457.b hosts
3458switch entry has the service
3459.q dns
3460listed somewhere in the list,
3461.i sendmail
3462will interpret this to mean a temporary failure
3463and will queue the mail for later processing;
3464otherwise, it ignores the name server data.
3465.pp
3466The same technique is used to decide whether to do MX lookups.
3467If you want MX support, you
3468.i must
3469have
3470.q dns
3471listed as a service in the
3472.b hosts
3473switch entry.
3474.pp
3475The
3476.b ResolverOptions
3477(\c
3478.b I )
3479option allows you to tweak name server options.
3480The command line takes a series of flags as documented in
3481.i resolver (3)
3482(with the leading
3483.q RES_
3484deleted).
3485Each can be preceded by an optional `+' or `\(mi'.
3486For example, the line
3487.(b
3488O ResolverOptions=+AAONLY \(miDNSRCH
3489.)b
3490turns on the AAONLY (accept authoritative answers only)
3491and turns off the DNSRCH (search the domain path) options.
3492Most resolver libraries default DNSRCH, DEFNAMES, and RECURSE
3493flags on and all others off.
3494If NETINET6 is enabled, most libraries default to USE_INET6 as well.
3495You can also include
3496.q HasWildcardMX
3497to specify that there is a wildcard MX record matching your domain;
3498this turns off MX matching when canonifying names,
3499which can lead to inappropriate canonifications.
3500Use
3501.q WorkAroundBrokenAAAA
3502when faced with a broken nameserver that returns SERVFAIL
3503(a temporary failure)
3504on T_AAAA (IPv6) lookups
3505during hostname canonification.
3506Notice: it might be necessary to apply the same (or similar) options to
3507.i submit.cf
3508too.
3509.pp
3510Version level 1 configurations (see the section about
3511``Configuration Version Level'')
3512turn DNSRCH and DEFNAMES off when doing delivery lookups,
3513but leave them on everywhere else.
3514Version 8 of
3515.i sendmail
3516ignores them when doing canonification lookups
3517(that is, when using $[ ... $]),
3518and always does the search.
3519If you don't want to do automatic name extension,
3520don't call $[ ... $].
3521.pp
3522The search rules for $[ ... $] are somewhat different than usual.
3523If the name being looked up
3524has at least one dot, it always tries the unmodified name first.
3525If that fails, it tries the reduced search path,
3526and lastly tries the unmodified name
3527(but only for names without a dot,
3528since names with a dot have already been tried).
3529This allows names such as
3530``utc.CS''
3531to match the site in Czechoslovakia
3532rather than the site in your local Computer Science department.
3533It also prefers A and CNAME records over MX records \*-
3534that is, if it finds an MX record it makes note of it,
3535but keeps looking.
3536This way, if you have a wildcard MX record matching your domain,
3537it will not assume that all names match.
3538.pp
3539To completely turn off all name server access
3540on systems without service switch support
3541(such as SunOS 4.X)
3542you will have to recompile with
3543\-DNAMED_BIND=0
3544and remove \-lresolv from the list of libraries to be searched
3545when linking.
3546.sh 2 "Moving the Per-User Forward Files"
3547.pp
3548Some sites mount each user's home directory
3549from a local disk on their workstation,
3550so that local access is fast.
3551However, the result is that .forward file lookups
3552from a central mail server are slow.
3553In some cases,
3554mail can even be delivered on machines inappropriately
3555because of a file server being down.
3556The performance can be especially bad if you run the automounter.
3557.pp
3558The
3559.b ForwardPath
3560(\c
3561.b J )
3562option allows you to set a path of forward files.
3563For example, the config file line
3564.(b
3565O ForwardPath=/var/forward/$u:$z/.forward.$w
3566.)b
3567would first look for a file with the same name as the user's login
3568in /var/forward;
3569if that is not found (or is inaccessible)
3570the file
3571``.forward.\c
3572.i machinename ''
3573in the user's home directory is searched.
3574A truly perverse site could also search by sender
3575by using $r, $s, or $f.
3576.pp
3577If you create a directory such as /var/forward,
3578it should be mode 1777
3579(that is, the sticky bit should be set).
3580Users should create the files mode 0644.
3581Note that you must use the
3582ForwardFileInUnsafeDirPath and
3583ForwardFileInUnsafeDirPathSafe
3584flags with the
3585.b DontBlameSendmail
3586option to allow forward files in a world writable directory.
3587This might also be used as a denial of service attack
3588(users could create forward files for other users);
3589a better approach might be to create
3590/var/forward
3591mode 0755
3592and create empty files for each user,
3593owned by that user,
3594mode 0644.
3595If you do this, you don't have to set the DontBlameSendmail options
3596indicated above.
3597.sh 2 "Free Space"
3598.pp
3599On systems that have one of the system calls in the
3600.i statfs (2)
3601family
3602(including
3603.i statvfs
3604and
3605.i ustat ),
3606you can specify a minimum number of free blocks on the queue filesystem
3607using the
3608.b MinFreeBlocks
3609(\c
3610.b b )
3611option.
3612If there are fewer than the indicated number of blocks free
3613on the filesystem on which the queue is mounted
3614the SMTP server will reject mail
3615with the
3616452 error code.
3617This invites the SMTP client to try again later.
3618.pp
3619Beware of setting this option too high;
3620it can cause rejection of email
3621when that mail would be processed without difficulty.
3622.sh 2 "Maximum Message Size"
3623.pp
3624To avoid overflowing your system with a large message,
3625the
3626.b MaxMessageSize
3627option can be set to set an absolute limit
3628on the size of any one message.
3629This will be advertised in the ESMTP dialogue
3630and checked during message collection.
3631.sh 2 "Privacy Flags"
3632.pp
3633The
3634.b PrivacyOptions
3635(\c
3636.b p )
3637option allows you to set certain
3638``privacy''
3639flags.
3640Actually, many of them don't give you any extra privacy,
3641rather just insisting that client SMTP servers
3642use the HELO command
3643before using certain commands
3644or adding extra headers to indicate possible spoof attempts.
3645.pp
3646The option takes a series of flag names;
3647the final privacy is the inclusive or of those flags.
3648For example:
3649.(b
3650O PrivacyOptions=needmailhelo, noexpn
3651.)b
3652insists that the HELO or EHLO command be used before a MAIL command is accepted
3653and disables the EXPN command.
3654.pp
3655The flags are detailed in section
3656.\"XREF
36575.6.
3658.sh 2 "Send to Me Too"
3659.pp
3660Beginning with version 8.10,
3661.i sendmail
3662includes by default the (envelope) sender in any list expansions.
3663For example, if
3664.q matt
3665sends to a list that contains
3666.q matt
3667as one of the members he will get a copy of the message.
3668If the
3669.b MeToo
3670option is set to
3671.sm FALSE
3672(in the configuration file or via the command line),
3673this behavior is changed, i.e.,
3674the (envelope) sender is excluded in list expansions.
3675.sh 1 "THE WHOLE SCOOP ON THE CONFIGURATION FILE"
3676.pp
3677This section describes the configuration file
3678in detail.
3679.pp
3680There is one point that should be made clear immediately:
3681the syntax of the configuration file
3682is designed to be reasonably easy to parse,
3683since this is done every time
3684.i sendmail
3685starts up,
3686rather than easy for a human to read or write.
3687The configuration file should be generated via the method described in
3688.b cf/README ,
3689it should not be edited directly unless someone is familiar
3690with the internals of the syntax described here and it is
3691not possible to achieve the desired result via the default method.
3692.pp
3693The configuration file is organized as a series of lines,
3694each of which begins with a single character
3695defining the semantics for the rest of the line.
3696Lines beginning with a space or a tab
3697are continuation lines
3698(although the semantics are not well defined in many places).
3699Blank lines and lines beginning with a sharp symbol
3700(`#')
3701are comments.
3702.sh 2 "R and S \*- Rewriting Rules"
3703.pp
3704The core of address parsing
3705are the rewriting rules.
3706These are an ordered production system.
3707.i Sendmail
3708scans through the set of rewriting rules
3709looking for a match on the left hand side
3710(LHS)
3711of the rule.
3712When a rule matches,
3713the address is replaced by the right hand side
3714(RHS)
3715of the rule.
3716.pp
3717There are several sets of rewriting rules.
3718Some of the rewriting sets are used internally
3719and must have specific semantics.
3720Other rewriting sets
3721do not have specifically assigned semantics,
3722and may be referenced by the mailer definitions
3723or by other rewriting sets.
3724.pp
3725The syntax of these two commands are:
3726.(b F
3727.b S \c
3728.i n
3729.)b
3730Sets the current ruleset being collected to
3731.i n .
3732If you begin a ruleset more than once
3733it appends to the old definition.
3734.(b F
3735.b R \c
3736.i lhs
3737.i rhs
3738.i comments
3739.)b
3740The
3741fields must be separated
3742by at least one tab character;
3743there may be embedded spaces
3744in the fields.
3745The
3746.i lhs
3747is a pattern that is applied to the input.
3748If it matches,
3749the input is rewritten to the
3750.i rhs .
3751The
3752.i comments
3753are ignored.
3754.pp
3755Macro expansions of the form
3756.b $ \c
3757.i x
3758are performed when the configuration file is read.
3759A literal
3760.b $
3761can be included using
3762.b $$ .
3763Expansions of the form
3764.b $& \c
3765.i x
3766are performed at run time using a somewhat less general algorithm.
3767This is intended only for referencing internally defined macros
3768such as
3769.b $h
3770that are changed at runtime.
3771.sh 3 "The left hand side"
3772.pp
3773The left hand side of rewriting rules contains a pattern.
3774Normal words are simply matched directly.
3775Metasyntax is introduced using a dollar sign.
3776The metasymbols are:
3777.(b
3778.ta \w'\fB$=\fP\fIx\fP 'u
3779\fB$*\fP Match zero or more tokens
3780\fB$+\fP Match one or more tokens
3781\fB$\-\fP Match exactly one token
3782\fB$=\fP\fIx\fP Match any phrase in class \fIx\fP
3783\fB$~\fP\fIx\fP Match any word not in class \fIx\fP
3784.)b
3785If any of these match,
3786they are assigned to the symbol
3787.b $ \c
3788.i n
3789for replacement on the right hand side,
3790where
3791.i n
3792is the index in the LHS.
3793For example,
3794if the LHS:
3795.(b
3796$\-:$+
3797.)b
3798is applied to the input:
3799.(b
3800UCBARPA:eric
3801.)b
3802the rule will match, and the values passed to the RHS will be:
3803.(b
3804.ta 4n
3805$1 UCBARPA
3806$2 eric
3807.)b
3808.pp
3809Additionally, the LHS can include
3810.b $@
3811to match zero tokens.
3812This is
3813.i not
3814bound to a
3815.b $ \c
3816.i n
3817on the RHS, and is normally only used when it stands alone
3818in order to match the null input.
3819.sh 3 "The right hand side"
3820.pp
3821When the left hand side of a rewriting rule matches,
3822the input is deleted and replaced by the right hand side.
3823Tokens are copied directly from the RHS
3824unless they begin with a dollar sign.
3825Metasymbols are:
3826.(b
3827.ta \w'$#mailer\0\0\0'u
3828\fB$\fP\fIn\fP Substitute indefinite token \fIn\fP from LHS
3829\fB$[\fP\fIname\fP\fB$]\fP Canonicalize \fIname\fP
3830\fB$(\fP\fImap key\fP \fB$@\fP\fIarguments\fP \fB$:\fP\fIdefault\fP \fB$)\fP
3831 Generalized keyed mapping function
3832\fB$>\fP\fIn\fP \*(lqCall\*(rq ruleset \fIn\fP
3833\fB$#\fP\fImailer\fP Resolve to \fImailer\fP
3834\fB$@\fP\fIhost\fP Specify \fIhost\fP
3835\fB$:\fP\fIuser\fP Specify \fIuser\fP
3836.)b
3837.pp
3838The
3839.b $ \c
3840.i n
3841syntax substitutes the corresponding value from a
3842.b $+ ,
3843.b $\- ,
3844.b $* ,
3845.b $= ,
3846or
3847.b $~
3848match on the LHS.
3849It may be used anywhere.
3850.pp
3851A host name enclosed between
3852.b $[
3853and
3854.b $]
3855is looked up in the host database(s)
3856and replaced by the canonical name\**.
3857.(f
3858\**This is actually
3859completely equivalent
3860to $(host \fIhostname\fP$).
3861In particular, a
3862.b $:
3863default can be used.
3864.)f
3865For example,
3866.q $[ftp$]
3867might become
3868.q ftp.CS.Berkeley.EDU
3869and
3870.q $[[128.32.130.2]$]
3871would become
3872.q vangogh.CS.Berkeley.EDU.
3873.i Sendmail
3874recognizes its numeric IP address
3875without calling the name server
3876and replaces it with its canonical name.
3877.pp
3878The
3879.b $(
3880\&...
3881.b $)
3882syntax is a more general form of lookup;
3883it uses a named map instead of an implicit map.
3884If no lookup is found, the indicated
3885.i default
3886is inserted;
3887if no default is specified and no lookup matches,
3888the value is left unchanged.
3889The
3890.i arguments
3891are passed to the map for possible use.
3892.pp
3893The
3894.b $> \c
3895.i n
3896syntax
3897causes the remainder of the line to be substituted as usual
3898and then passed as the argument to ruleset
3899.i n .
3900The final value of ruleset
3901.i n
3902then becomes
3903the substitution for this rule.
3904The
3905.b $>
3906syntax expands everything after the ruleset name
3907to the end of the replacement string
3908and then passes that as the initial input to the ruleset.
3909Recursive calls are allowed.
3910For example,
3911.(b
3912$>0 $>3 $1
3913.)b
3914expands $1, passes that to ruleset 3, and then passes the result
3915of ruleset 3 to ruleset 0.
3916.pp
3917The
3918.b $#
3919syntax should
3920.i only
3921be used in ruleset zero,
3922a subroutine of ruleset zero,
3923or rulesets that return decisions (e.g., check_rcpt).
3924It causes evaluation of the ruleset to terminate immediately,
3925and signals to
3926.i sendmail
3927that the address has completely resolved.
3928The complete syntax for ruleset 0 is:
3929.(b
3930\fB$#\fP\fImailer\fP \fB$@\fP\fIhost\fP \fB$:\fP\fIuser\fP
3931.)b
3932This specifies the
3933{mailer, host, user}
39343-tuple necessary to direct the mailer.
3935Note: the third element (
3936.i user
3937) is often also called
3938.i address
3939part.
3940If the mailer is local
3941the host part may be omitted\**.
3942.(f
3943\**You may want to use it for special
3944.q "per user"
3945extensions.
3946For example, in the address
3947.q jgm+foo@CMU.EDU ;
3948the
3949.q +foo
3950part is not part of the user name,
3951and is passed to the local mailer for local use.
3952.)f
3953The
3954.i mailer
3955must be a single word,
3956but the
3957.i host
3958and
3959.i user
3960may be multi-part.
3961If the
3962.i mailer
3963is the built-in IPC mailer,
3964the
3965.i host
3966may be a colon-separated list of hosts
3967that are searched in order for the first working address
3968(exactly like MX records).
3969The
3970.i user
3971is later rewritten by the mailer-specific envelope rewriting set
3972and assigned to the
3973.b $u
3974macro.
3975As a special case, if the mailer specified has the
3976.b F=@
3977flag specified
3978and the first character of the
3979.b $:
3980value is
3981.q @ ,
3982the
3983.q @
3984is stripped off, and a flag is set in the address descriptor
3985that causes sendmail to not do ruleset 5 processing.
3986.pp
3987Normally, a rule that matches is retried,
3988that is,
3989the rule loops until it fails.
3990A RHS may also be preceded by a
3991.b $@
3992or a
3993.b $:
3994to change this behavior.
3995A
3996.b $@
3997prefix causes the ruleset to return with the remainder of the RHS
3998as the value.
3999A
4000.b $:
4001prefix causes the rule to terminate immediately,
4002but the ruleset to continue;
4003this can be used to avoid continued application of a rule.
4004The prefix is stripped before continuing.
4005.pp
4006The
4007.b $@
4008and
4009.b $:
4010prefixes may precede a
4011.b $>
4012spec;
4013for example:
4014.(b
4015.ta 8n
4016R$+ $: $>7 $1
4017.)b
4018matches anything,
4019passes that to ruleset seven,
4020and continues;
4021the
4022.b $:
4023is necessary to avoid an infinite loop.
4024.pp
4025Substitution occurs in the order described,
4026that is,
4027parameters from the LHS are substituted,
4028hostnames are canonicalized,
4029.q subroutines
4030are called,
4031and finally
4032.b $# ,
4033.b $@ ,
4034and
4035.b $:
4036are processed.
4037.sh 3 "Semantics of rewriting rule sets"
4038.pp
4039There are six rewriting sets
4040that have specific semantics.
4041Five of these are related as depicted by figure 1.
4042.(z
4043.hl
4044.ie n \{\
4045.(c
4046 +---+
4047 -->| 0 |-->resolved address
4048 / +---+
4049 / +---+ +---+
4050 / ---->| 1 |-->| S |--
4051 +---+ / +---+ / +---+ +---+ \e +---+
4052addr-->| 3 |-->| D |-- --->| 4 |-->msg
4053 +---+ +---+ \e +---+ +---+ / +---+
4054 --->| 2 |-->| R |--
4055 +---+ +---+
4056.)c
4057
4058.\}
4059.el \{\
4060.ie !"\*(.T"" \{\
4061.PS
4062boxwid = 0.3i
4063boxht = 0.3i
4064movewid = 0.3i
4065moveht = 0.3i
4066linewid = 0.3i
4067lineht = 0.3i
4068
4069 box invis "addr"; arrow
4070Box3: box "3"
4071A1: arrow
4072BoxD: box "D"; line; L1: Here
4073C: [
4074 C1: arrow; box "1"; arrow; box "S"; line; E1: Here
4075 move to C1 down 0.5; right
4076 C2: arrow; box "2"; arrow; box "R"; line; E2: Here
4077 ] with .w at L1 + (0.5, 0)
4078 move to C.e right 0.5
4079L4: arrow; box "4"; arrow; box invis "msg"
4080 line from L1 to C.C1
4081 line from L1 to C.C2
4082 line from C.E1 to L4
4083 line from C.E2 to L4
4084 move to BoxD.n up 0.6; right
4085Box0: arrow; box "0"
4086 arrow; box invis "resolved address" width 1.3
4087 line from 1/3 of the way between A1 and BoxD.w to Box0
4088.PE
4089.\}
4090.el .sp 2i
4091.\}
4092.ce
4093Figure 1 \*- Rewriting set semantics
4094.(c
4095D \*- sender domain addition
4096S \*- mailer-specific sender rewriting
4097R \*- mailer-specific recipient rewriting
4098.)c
4099.hl
4100.)z
4101.pp
4102Ruleset three
4103should turn the address into
4104.q "canonical form."
4105This form should have the basic syntax:
4106.(b
4107local-part@host-domain-spec
4108.)b
4109Ruleset three
4110is applied by
4111.i sendmail
4112before doing anything with any address.
4113.pp
4114If no
4115.q @
4116sign is specified,
4117then the
4118host-domain-spec
4119.i may
4120be appended (box
4121.q D
4122in Figure 1)
4123from the
4124sender address
4125(if the
4126.b C
4127flag is set in the mailer definition
4128corresponding to the
4129.i sending
4130mailer).
4131.pp
4132Ruleset zero
4133is applied after ruleset three
4134to addresses that are going to actually specify recipients.
4135It must resolve to a
4136.i "{mailer, host, address}"
4137triple.
4138The
4139.i mailer
4140must be defined in the mailer definitions
4141from the configuration file.
4142The
4143.i host
4144is defined into the
4145.b $h
4146macro
4147for use in the argv expansion of the specified mailer.
4148Notice: since the envelope sender address will be used if
4149a delivery status notification must be send,
4150i.e., is may specify a recipient,
4151it is also run through ruleset zero.
4152If ruleset zero returns a temporary error
4153.b 4xy
4154then delivery is deferred.
4155This can be used to temporarily disable delivery,
4156e.g., based on the time of the day or other varying parameters.
4157It should not be used to quarantine e-mails.
4158.pp
4159Rulesets one and two
4160are applied to all sender and recipient addresses respectively.
4161They are applied before any specification
4162in the mailer definition.
4163They must never resolve.
4164.pp
4165Ruleset four is applied to all addresses
4166in the message.
4167It is typically used
4168to translate internal to external form.
4169.pp
4170In addition,
4171ruleset 5 is applied to all local addresses
4172(specifically, those that resolve to a mailer with the `F=5'
4173flag set)
4174that do not have aliases.
4175This allows a last minute hook for local names.
4176.sh 3 "Ruleset hooks"
4177.pp
4178A few extra rulesets are defined as
4179.q hooks
4180that can be defined to get special features.
4181They are all named rulesets.
4182The
4183.q check_*
4184forms all give accept/reject status;
4185falling off the end or returning normally is an accept,
4186and resolving to
4187.b $#error
4188is a reject or quarantine.
4189Quarantining is chosen by specifying
4190.b quarantine
4191in the second part of the mailer triplet:
4192.(b
4193$#error $@ quarantine $: Reason for quarantine
4194.)b
4195Many of these can also resolve to the special mailer name
4196.b $#discard ;
4197this accepts the message as though it were successful
4198but then discards it without delivery.
4199Note,
4200this mailer cannot be chosen as a mailer in ruleset 0.
4201Note also that all
4202.q check_*
4203rulesets have to deal with temporary failures, especially for map lookups,
4204themselves, i.e., they should return a temporary error code
4205or at least they should make a proper decision in those cases.
4206.sh 4 "check_relay"
4207.pp
4208The
4209.i check_relay
4210ruleset is called after a connection is accepted by the daemon.
4211It is not called when sendmail is started using the
4212.b \-bs
4213option.
4214It is passed
4215.(b
4216client.host.name $| client.host.address
4217.)b
4218where
4219.b $|
4220is a metacharacter separating the two parts.
4221This ruleset can reject connections from various locations.
4222Note that it only checks the connecting SMTP client IP address and hostname.
4223It does not check for third party message relaying.
4224The
4225.i check_rcpt
4226ruleset discussed below usually does third party message relay checking.
4227.sh 4 "check_mail"
4228.pp
4229The
4230.i check_mail
4231ruleset is passed the user name parameter of the
4232.sm "SMTP MAIL"
4233command.
4234It can accept or reject the address.
4235.sh 4 "check_rcpt"
4236.pp
4237The
4238.i check_rcpt
4239ruleset is passed the user name parameter of the
4240.sm "SMTP RCPT"
4241command.
4242It can accept or reject the address.
4243.sh 4 "check_data"
4244.pp
4245The
4246.i check_data
4247ruleset is called after the
4248.sm "SMTP DATA"
4249command, its parameter is the number of recipients.
4250It can accept or reject the command.
4251.sh 4 "check_compat"
4252.pp
4253The
4254.i check_compat
4255ruleset is passed
4256.(b
4257sender-address $| recipient-address
4258.)b
4259where
4260.b $|
4261is a metacharacter separating the addresses.
4262It can accept or reject mail transfer between these two addresses
4263much like the
4264.i checkcompat()
4265function.
4266Note:
4267while other
4268.i check_*
4269rulesets are invoked during the SMTP mail receiption stage
4270(i.e., in the SMTP server),
4271.i check_compat
4272is invoked during the mail delivery stage.
4273.sh 4 "check_eoh"
4274.pp
4275The
4276.i check_eoh
4277ruleset is passed
4278.(b
4279number-of-headers $| size-of-headers
4280.)b
4281where
4282.b $|
4283is a metacharacter separating the numbers.
4284These numbers can be used for size comparisons with the
4285.b arith
4286map.
4287The ruleset is triggered after
4288all of the headers have been read.
4289It can be used to correlate information gathered
4290from those headers using the
4291.b macro
4292storage map.
4293One possible use is to check for a missing header.
4294For example:
4295.(b
4296.ta 1.5i
4297Kstorage macro
4298HMessage-Id: $>CheckMessageId
4299
4300SCheckMessageId
4301# Record the presence of the header
4302R$* $: $(storage {MessageIdCheck} $@ OK $) $1
4303R< $+ @ $+ > $@ OK
4304R$* $#error $: 553 Header Error
4305
4306Scheck_eoh
4307# Check the macro
4308R$* $: < $&{MessageIdCheck} >
4309# Clear the macro for the next message
4310R$* $: $(storage {MessageIdCheck} $) $1
4311# Has a Message-Id: header
4312R< $+ > $@ OK
4313# Allow missing Message-Id: from local mail
4314R$* $: < $&{client_name} >
4315R< > $@ OK
4316R< $=w > $@ OK
4317# Otherwise, reject the mail
4318R$* $#error $: 553 Header Error
4319.)b
4320Keep in mind the Message-Id: header is not a required header and
4321is not a guaranteed spam indicator.
4322This ruleset is an example and
4323should probably not be used in production.
4324.sh 4 "check_eom"
4325.pp
4326The
4327.i check_eom
4328ruleset is called after the end of a message,
4329its parameter is the message size.
4330It can accept or reject the message.
4331.sh 4 "check_etrn"
4332.pp
4333The
4334.i check_etrn
4335ruleset is passed the parameter of the
4336.sm "SMTP ETRN"
4337command.
4338It can accept or reject the command.
4339.sh 4 "check_expn"
4340.pp
4341The
4342.i check_expn
4343ruleset is passed the user name parameter of the
4344.sm "SMTP EXPN"
4345command.
4346It can accept or reject the address.
4347.sh 4 "check_vrfy"
4348.pp
4349The
4350.i check_vrfy
4351ruleset is passed the user name parameter of the
4352.sm "SMTP VRFY"
4353command.
4354It can accept or reject the command.
4355.sh 4 "trust_auth"
4356.pp
4357The
4358.i trust_auth
4359ruleset is passed the AUTH= parameter of the
4360.sm "SMTP MAIL"
4361command.
4362It is used to determine whether this value should be
4363trusted. In order to make this decision, the ruleset
4364may make use of the various
4365.b ${auth_*}
4366macros.
4367If the ruleset does resolve to the
4368.q error
4369mailer the AUTH= parameter is not trusted and hence
4370not passed on to the next relay.
4371.sh 4 "tls_client"
4372.pp
4373The
4374.i tls_client
4375ruleset is called when sendmail acts as server, after a STARTTLS command
4376has been issued, and from
4377.i check_mail.
4378The parameter is the value of
4379.b ${verify}
4380and STARTTLS or MAIL, respectively.
4381If the ruleset does resolve to the
4382.q error
4383mailer, the appropriate error code is returned to the client.
4384.sh 4 "tls_server"
4385.pp
4386The
4387.i tls_server
4388ruleset is called when sendmail acts as client after a STARTTLS command
4389(should) have been issued.
4390The parameter is the value of
4391.b ${verify} .
4392If the ruleset does resolve to the
4393.q error
4394mailer, the connection is aborted
4395(treated as non-deliverable with a permanent or temporary error).
4396.sh 4 "tls_rcpt"
4397.pp
4398The
4399.i tls_rcpt
4400ruleset is called each time before a RCPT TO command is sent.
4401The parameter is the current recipient.
4402If the ruleset does resolve to the
4403.q error
4404mailer, the RCPT TO command is suppressed
4405(treated as non-deliverable with a permanent or temporary error).
4406This ruleset allows to require encryption or verification of
4407the recipient's MTA even if the mail is somehow redirected
4408to another host.
4409For example, sending mail to
4410.i luke@endmail.org
4411may get redirected to a host named
4412.i death.star
4413and hence the tls_server ruleset won't apply.
4414By introducing per recipient restrictions such attacks
4415(e.g., via DNS spoofing) can be made impossible.
4416See
4417.i cf/README
4418how this ruleset can be used.
4419.sh 4 "srv_features"
4420.pp
4421The
4422.i srv_features
4423ruleset is called with the connecting client's host name
4424when a client connects to sendmail.
4425This ruleset should return
4426.b $#
4427followed by a list of options (single characters
4428delimited by white space).
4429If the return value starts with anything else it is silently ignored.
4430Generally upper case characters turn off a feature
4431while lower case characters turn it on.
4432Option `S' causes the server not to offer STARTTLS,
4433which is useful to interact with MTAs/MUAs that have broken
4434STARTTLS implementations by simply not offering it.
4435`V' turns off the request for a client certificate during the TLS handshake.
4436Options `A' and `P' suppress SMTP AUTH and PIPELINING, respectively.
4437`c' is the equivalent to AuthOptions=p, i.e.,
4438it doesn't permit mechanisms susceptible to simple
4439passive attack (e.g., PLAIN, LOGIN), unless a security layer is active.
4440Option `l' requires SMTP AUTH for a connection.
4441Options 'B', 'D', 'E', and 'X' suppress SMTP VERB, DSN, ETRN, and EXPN,
4442respectively.
4443.(b
4444.ta 9n
4445A Do not offer AUTH
4446a Offer AUTH (default)
4447B Do not offer VERB
4448b Offer VERB (default)
4449C Do not require security layer for
4450 plaintext AUTH (default)
4451c Require security layer for plaintext AUTH
4452D Do not offer DSN
4453d Offer DSN (default)
4454E Do not offer ETRN
4455e Offer ETRN (default)
4456L Do not require AUTH (default)
4457l Require AUTH
4458P Do not offer PIPELINING
4459p Offer PIPELINING (default)
4460S Do not offer STARTTLS
4461s Offer STARTTLS (default)
4462V Do not request a client certificate
4463v Request a client certificate (default)
4464X Do not offer EXPN
4465x Offer EXPN (default)
4466.)b
4467Note: the entries marked as ``(default)'' may require that some
4468configuration has been made, e.g., SMTP AUTH is only available if
4469properly configured.
4470Moreover, many options can be changed on a global basis via other
4471settings as explained in this document, e.g., via DaemonPortOptions.
4472.pp
4473The ruleset may return `$#temp' to indicate that there is a temporary
4474problem determining the correct features, e.g., if a map is unavailable.
4475In that case, the SMTP server issues a temporary failure and does not
4476accept email.
4477.sh 4 "try_tls"
4478.pp
4479The
4480.i try_tls
4481ruleset is called when sendmail connects to another MTA.
4482If the ruleset does resolve to the
4483.q error
4484mailer, sendmail does not try STARTTLS even if it is offered.
4485This is useful to interact with MTAs that have broken
4486STARTTLS implementations by simply not using it.
4487.sh 4 "authinfo"
4488.pp
4489The
4490.i authinfo
4491ruleset is called when sendmail tries to authenticate to another MTA.
4492It should return
4493.b $#
4494followed by a list of tokens that are used for SMTP AUTH.
4495If the return value starts with anything else it is silently ignored.
4496Each token is a tagged string of the form:
4497"TDstring"
4498(including the quotes), where
4499.(b
4500.ta 9n
4501T Tag which describes the item
4502D Delimiter: ':' simple text follows
4503 '=' string is base64 encoded
4504string Value of the item
4505.)b
4506Valid values for the tag are:
4507.(b
4508.ta 9n
4509U user (authorization) id
4510I authentication id
4511P password
4512R realm
4513M list of mechanisms delimited by spaces
4514.)b
4515If this ruleset is defined, the option
4516.b DefaultAuthInfo
4517is ignored (even if the ruleset does not return a ``useful'' result).
4518.sh 4 "queuegroup"
4519.pp
4520The
4521.i queuegroup
4522ruleset is used to map a recipient address to a queue group name.
4523The input for the ruleset is a recipient address as specified by the
4524.sm "SMTP RCPT"
4525command.
4526The ruleset should return
4527.b $#
4528followed by the name of a queue group.
4529If the return value starts with anything else it is silently ignored.
4530See the section about ``Queue Groups and Queue Directories''
4531for further information.
4532.sh 4 "greet_pause"
4533.pp
4534The
4535.i greet_pause
4536ruleset is used to specify the amount of time to pause before sending the
4537initial SMTP 220 greeting.
4538If any traffic is received during that pause, an SMTP 554 rejection
4539response is given instead of the 220 greeting and all SMTP commands are
4540rejected during that connection.
4541This helps protect sites from open proxies and SMTP slammers.
4542The ruleset should return
4543.b $#
4544followed by the number of milliseconds (thousandths of a second) to
4545pause.
4546If the return value starts with anything else or is not a number,
4547it is silently ignored.
4548Note: this ruleset is not invoked (and hence the feature is disabled)
4549when the smtps (SMTP over SSL) is used, i.e.,
4550the
4551.i s
4552modifier is set for the daemon via
4553.b DaemonPortOptions ,
4554because in this case the SSL handshake is performed before
4555the greeting is sent.
4556.sh 3 "IPC mailers"
4557.pp
4558Some special processing occurs
4559if the ruleset zero resolves to an IPC mailer
4560(that is, a mailer that has
4561.q [IPC]
4562listed as the Path in the
4563.b M
4564configuration line.
4565The host name passed after
4566.q $@
4567has MX expansion performed if not delivering via a named socket;
4568this looks the name up in DNS to find alternate delivery sites.
4569.pp
4570The host name can also be provided as a dotted quad
4571or an IPv6 address in square brackets;
4572for example:
4573.(b
4574[128.32.149.78]
4575.)b
4576or
4577.(b
4578[IPv6:2002:c0a8:51d2::23f4]
4579.)b
4580This causes direct conversion of the numeric value
4581to an IP host address.
4582.pp
4583The host name passed in after the
4584.q $@
4585may also be a colon-separated list of hosts.
4586Each is separately MX expanded and the results are concatenated
4587to make (essentially) one long MX list.
4588The intent here is to create
4589.q fake
4590MX records that are not published in DNS
4591for private internal networks.
4592.pp
4593As a final special case, the host name can be passed in
4594as a text string
4595in square brackets:
4596.(b
4597[ucbvax.berkeley.edu]
4598.)b
4599This form avoids the MX mapping.
4600.b N.B.:
4601.i
4602This is intended only for situations where you have a network firewall
4603or other host that will do special processing for all your mail,
4604so that your MX record points to a gateway machine;
4605this machine could then do direct delivery to machines
4606within your local domain.
4607Use of this feature directly violates RFC 1123 section 5.3.5:
4608it should not be used lightly.
4609.r
4610.sh 2 "D \*- Define Macro"
4611.pp
4612Macros are named with a single character
4613or with a word in {braces}.
4614The names ``x'' and ``{x}'' denote the same macro
4615for every single character ``x''.
4616Single character names may be selected from the entire ASCII set,
4617but user-defined macros
4618should be selected from the set of upper case letters only.
4619Lower case letters
4620and special symbols
4621are used internally.
4622Long names beginning with a lower case letter or a punctuation character
4623are reserved for use by sendmail,
4624so user-defined long macro names should begin with an upper case letter.
4625.pp
4626The syntax for macro definitions is:
4627.(b F
4628.b D \c
4629.i x\|val
4630.)b
4631where
4632.i x
4633is the name of the macro
4634(which may be a single character
4635or a word in braces)
4636and
4637.i val
4638is the value it should have.
4639There should be no spaces given
4640that do not actually belong in the macro value.
4641.pp
4642Macros are interpolated
4643using the construct
4644.b $ \c
4645.i x ,
4646where
4647.i x
4648is the name of the macro to be interpolated.
4649This interpolation is done when the configuration file is read,
4650except in
4651.b M
4652lines.
4653The special construct
4654.b $& \c
4655.i x
4656can be used in
4657.b R
4658lines to get deferred interpolation.
4659.pp
4660Conditionals can be specified using the syntax:
4661.(b
4662$?x text1 $| text2 $.
4663.)b
4664This interpolates
4665.i text1
4666if the macro
4667.b $x
4668is set and non-null,
4669and
4670.i text2
4671otherwise.
4672The
4673.q else
4674(\c
4675.b $| )
4676clause may be omitted.
4677.pp
4678The following macros are defined and/or used internally by
4679.i sendmail
4680for interpolation into argv's for mailers
4681or for other contexts.
4682The ones marked \(dg are information passed into sendmail\**,
4683.(f
4684\**As of version 8.6,
4685all of these macros have reasonable defaults.
4686Previous versions required that they be defined.
4687.)f
4688the ones marked \(dd are information passed both in and out of sendmail,
4689and the unmarked macros are passed out of sendmail
4690but are not otherwise used internally.
4691These macros are:
4692.nr ii 5n
4693.ip $a
4694The origination date in RFC 822 format.
4695This is extracted from the Date: line.
4696.ip $b
4697The current date in RFC 822 format.
4698.ip $c
4699The hop count.
4700This is a count of the number of Received: lines
4701plus the value of the
4702.b \-h
4703command line flag.
4704.ip $d
4705The current date in UNIX (ctime) format.
4706.ip $e\(dg
4707(Obsolete; use SmtpGreetingMessage option instead.)
4708The SMTP entry message.
4709This is printed out when SMTP starts up.
4710The first word must be the
4711.b $j
4712macro as specified by RFC 821.
4713Defaults to
4714.q "$j Sendmail $v ready at $b" .
4715Commonly redefined to include the configuration version number, e.g.,
4716.q "$j Sendmail $v/$Z ready at $b"
4717.ip $f
4718The envelope sender (from) address.
4719.ip $g
4720The sender address relative to the recipient.
4721For example, if
4722.b $f
4723is
4724.q foo ,
4725.b $g
4726will be
4727.q host!foo ,
4728.q foo@host.domain ,
4729or whatever is appropriate for the receiving mailer.
4730.ip $h
4731The recipient host.
4732This is set in ruleset 0 from the $@ field of a parsed address.
4733.ip $i
4734The queue id,
4735e.g.,
4736.q f344MXxp018717 .
4737.ip $j\(dd
4738The \*(lqofficial\*(rq domain name for this site.
4739This is fully qualified if the full qualification can be found.
4740It
4741.i must
4742be redefined to be the fully qualified domain name
4743if your system is not configured so that information can find
4744it automatically.
4745.ip $k
4746The UUCP node name (from the uname system call).
4747.ip $l\(dg
4748(Obsolete; use UnixFromLine option instead.)
4749The format of the UNIX from line.
4750Unless you have changed the UNIX mailbox format,
4751you should not change the default,
4752which is
4753.q "From $g $d" .
4754.ip $m
4755The domain part of the \fIgethostname\fP return value.
4756Under normal circumstances,
4757.b $j
4758is equivalent to
4759.b $w.$m .
4760.ip $n\(dg
4761The name of the daemon (for error messages).
4762Defaults to
4763.q MAILER-DAEMON .
4764.ip $o\(dg
4765(Obsolete: use OperatorChars option instead.)
4766The set of \*(lqoperators\*(rq in addresses.
4767A list of characters
4768which will be considered tokens
4769and which will separate tokens
4770when doing parsing.
4771For example, if
4772.q @
4773were in the
4774.b $o
4775macro, then the input
4776.q a@b
4777would be scanned as three tokens:
4778.q a,
4779.q @,
4780and
4781.q b.
4782Defaults to
4783.q ".:@[]" ,
4784which is the minimum set necessary to do RFC 822 parsing;
4785a richer set of operators is
4786.q ".:%@!/[]" ,
4787which adds support for UUCP, the %-hack, and X.400 addresses.
4788.ip $p
4789Sendmail's process id.
4790.ip $q\(dg
4791Default format of sender address.
4792The
4793.b $q
4794macro specifies how an address should appear in a message
4795when it is defaulted.
4796Defaults to
4797.q "<$g>" .
4798It is commonly redefined to be
4799.q "$?x$x <$g>$|$g$."
4800or
4801.q "$g$?x ($x)$." ,
4802corresponding to the following two formats:
4803.(b
4804Eric Allman <eric@CS.Berkeley.EDU>
4805eric@CS.Berkeley.EDU (Eric Allman)
4806.)b
4807.i Sendmail
4808properly quotes names that have special characters
4809if the first form is used.
4810.ip $r
4811Protocol used to receive the message.
4812Set from the
4813.b \-p
4814command line flag or by the SMTP server code.
4815.ip $s
4816Sender's host name.
4817Set from the
4818.b \-p
4819command line flag or by the SMTP server code
4820(in which case it is set to the EHLO/HELO parameter).
4821.ip $t
4822A numeric representation of the current time in the format YYYYMMDDHHmm
4823(4 digit year 1900-9999, 2 digit month 01-12, 2 digit day 01-31,
48242 digit hours 00-23, 2 digit minutes 00-59).
4825.ip $u
4826The recipient user.
4827.ip $v
4828The version number of the
4829.i sendmail
4830binary.
4831.ip $w\(dd
4832The hostname of this site.
4833This is the root name of this host (but see below for caveats).
4834.ip $x
4835The full name of the sender.
4836.ip $z
4837The home directory of the recipient.
4838.ip $_
4839The validated sender address.
4840See also
4841.b ${client_resolve} .
4842.ip ${addr_type}
4843The type of the address which is currently being rewritten.
4844This macro contains up to three characters, the first
4845is either `e' or `h' for envelope/header address,
4846the second is a space,
4847and the third is either `s' or `r' for sender/recipient address.
4848.ip ${alg_bits}
4849The maximum keylength (in bits) of the symmetric encryption algorithm
4850used for a TLS connection.
4851This may be less than the effective keylength,
4852which is stored in
4853.b ${cipher_bits} ,
4854for ``export controlled'' algorithms.
4855.ip ${auth_authen}
4856The client's authentication credentials as determined by authentication
4857(only set if successful).
4858The format depends on the mechanism used, it might be just `user',
4859or `user@realm', or something similar (SMTP AUTH only).
4860.ip ${auth_author}
4861The authorization identity, i.e. the AUTH= parameter of the
4862.sm "SMTP MAIL"
4863command if supplied.
4864.ip ${auth_type}
4865The mechanism used for SMTP authentication
4866(only set if successful).
4867.ip ${auth_ssf}
4868The keylength (in bits) of the symmetric encryption algorithm
4869used for the security layer of a SASL mechanism.
4870.ip ${bodytype}
4871The message body type
4872(7BIT or 8BITMIME),
4873as determined from the envelope.
4874.ip ${cert_issuer}
4875The DN (distinguished name) of the CA (certificate authority)
4876that signed the presented certificate (the cert issuer)
4877(STARTTLS only).
4878.ip ${cert_md5}
4879The MD5 hash of the presented certificate (STARTTLS only).
4880.ip ${cert_subject}
4881The DN of the presented certificate (called the cert subject)
4882(STARTTLS only).
4883.ip ${cipher}
4884The cipher suite used for the connection, e.g., EDH-DSS-DES-CBC3-SHA,
4885EDH-RSA-DES-CBC-SHA, DES-CBC-MD5, DES-CBC3-SHA
4886(STARTTLS only).
4887.ip ${cipher_bits}
4888The effective keylength (in bits) of the symmetric encryption algorithm
4889used for a TLS connection.
4890.ip ${client_addr}
4891The IP address of the SMTP client.
4892IPv6 addresses are tagged with "IPv6:" before the address.
4893Defined in the SMTP server only.
4894.ip ${client_connections}
4895The number of open connections in the SMTP server for the client IP address.
4896.ip ${client_flags}
4897The flags specified by the
4898Modifier= part of
4899.b ClientPortOptions
4900where flags are separated from each other by spaces
4901and upper case flags are doubled.
4902That is,
4903Modifier=hA
4904will be represented as
4905"h AA" in
4906.b ${client_flags} ,
4907which is required for testing the flags in rulesets.
4908.ip ${client_name}
4909The host name of the SMTP client.
4910This may be the client's bracketed IP address
4911in the form [ nnn.nnn.nnn.nnn ] for IPv4
4912and [ IPv6:nnnn:...:nnnn ] for IPv6
4913if the client's
4914IP address is not resolvable, or if it is resolvable
4915but the IP address of the resolved hostname
4916doesn't match the original IP address.
4917Defined in the SMTP server only.
4918See also
4919.b ${client_resolve} .
4920.ip ${client_port}
4921The port number of the SMTP client.
4922Defined in the SMTP server only.
4923.ip ${client_ptr}
4924The result of the PTR lookup for the client IP address.
4925Note: this is the same as
4926.b ${client_name}
4927if and only if
4928.b ${client_resolve}
4929is OK.
4930Defined in the SMTP server only.
4931.ip ${client_rate}
4932The number of incoming connections for the client IP address
4933over the time interval specified by ConnectionRateWindowSize.
4934.ip ${client_resolve}
4935Holds the result of the resolve call for
4936.b ${client_name} .
4937Possible values are:
4938.(b
4939.ta 10n
4940OK resolved successfully
4941FAIL permanent lookup failure
4942FORGED forward lookup doesn't match reverse lookup
4943TEMP temporary lookup failure
4944.)b
4945Defined in the SMTP server only.
4946.i sendmail
4947performs a hostname lookup on the IP address of the connecting client.
4948Next the IP addresses of that hostname are looked up.
4949If the client IP address does not appear in that list,
4950then the hostname is maybe forged.
4951This is reflected as the value FORGED for
4952.b ${client_resolve}
4953and it also shows up in
4954.b $_
4955as "(may be forged)".
4956.ip ${cn_issuer}
4957The CN (common name) of the CA that signed the presented certificate
4958(STARTTLS only).
4959Note: if the CN cannot be extracted properly it will be replaced by
4960one of these strings based on the encountered error:
4961.(b
4962.ta 25n
4963BadCertificateContainsNUL CN contains a NUL character
4964BadCertificateTooLong CN is too long
4965BadCertificateUnknown CN could not be extracted
4966.)b
4967In the last case, some other (unspecific) error occurred.
4968.ip ${cn_subject}
4969The CN (common name) of the presented certificate
4970(STARTTLS only).
4971See
4972.b ${cn_issuer}
4973for possible replacements.
4974.ip ${currHeader}
4975Header value as quoted string
4976(possibly truncated to
4977.b MAXNAME ).
4978This macro is only available in header check rulesets.
4979.ip ${daemon_addr}
4980The IP address the daemon is listening on for connections.
4981.ip ${daemon_family}
4982The network family
4983if the daemon is accepting network connections.
4984Possible values include
4985.q inet ,
4986.q inet6 ,
4987.q iso ,
4988.q ns ,
4989.q x.25
4990.ip ${daemon_flags}
4991The flags for the daemon as specified by the
4992Modifier= part of
4993.b DaemonPortOptions
4994whereby the flags are separated from each other by spaces,
4995and upper case flags are doubled.
4996That is,
4997Modifier=Ea
4998will be represented as
4999"EE a" in
5000.b ${daemon_flags} ,
5001which is required for testing the flags in rulesets.
5002.ip ${daemon_info}
5003Some information about a daemon as a text string.
5004For example,
5005.q SMTP+queueing@00:30:00 .
5006.ip ${daemon_name}
5007The name of the daemon from
5008.b DaemonPortOptions
5009Name= suboption.
5010If this suboption is not set,
5011"Daemon#",
5012where # is the daemon number,
5013is used.
5014.ip ${daemon_port}
5015The port the daemon is accepting connection on.
5016Unless
5017.b DaemonPortOptions
5018is set, this will most likely be
5019.q 25 .
5020.ip ${deliveryMode}
5021The current delivery mode sendmail is using.
5022It is initially set to the value of the
5023.b DeliveryMode
5024option.
5025.ip ${envid}
5026The envelope id parameter (ENVID=) passed to sendmail as part of the envelope.
5027.ip ${hdrlen}
5028The length of the header value which is stored in
5029${currHeader} (before possible truncation).
5030If this value is greater than or equal to
5031.b MAXNAME
5032the header has been truncated.
5033.ip ${hdr_name}
5034The name of the header field for which the current header
5035check ruleset has been called.
5036This is useful for a default header check ruleset to get
5037the name of the header;
5038the macro is only available in header check rulesets.
5039.ip ${if_addr}
5040The IP address of the interface of an incoming connection
5041unless it is in the loopback net.
5042IPv6 addresses are tagged with "IPv6:" before the address.
5043.ip ${if_addr_out}
5044The IP address of the interface of an outgoing connection
5045unless it is in the loopback net.
5046IPv6 addresses are tagged with "IPv6:" before the address.
5047.ip ${if_family}
5048The IP family of the interface of an incoming connection
5049unless it is in the loopback net.
5050.ip ${if_family_out}
5051The IP family of the interface of an outgoing connection
5052unless it is in the loopback net.
5053.ip ${if_name}
5054The hostname associated with the interface of an incoming connection.
5055This macro can be used for
5056SmtpGreetingMessage and HReceived for virtual hosting.
5057For example:
5058.(b
5059O SmtpGreetingMessage=$?{if_name}${if_name}$|$j$. MTA
5060.)b
5061.ip ${if_name_out}
5062The name of the interface of an outgoing connection.
5063.ip ${load_avg}
5064The current load average.
5065.ip ${mail_addr}
5066The address part of the resolved triple of the address given for the
5067.sm "SMTP MAIL"
5068command.
5069Defined in the SMTP server only.
5070.ip ${mail_host}
5071The host from the resolved triple of the address given for the
5072.sm "SMTP MAIL"
5073command.
5074Defined in the SMTP server only.
5075.ip ${mail_mailer}
5076The mailer from the resolved triple of the address given for the
5077.sm "SMTP MAIL"
5078command.
5079Defined in the SMTP server only.
5080.ip ${msg_id}
5081The value of the Message-Id: header.
5082.ip ${msg_size}
5083The value of the SIZE= parameter,
5084i.e., usually the size of the message (in an ESMTP dialogue),
5085before the message has been collected, thereafter
5086the message size as computed by
5087.i sendmail
5088(and can be used in check_compat).
5089.ip ${nbadrcpts}
5090The number of bad recipients for a single message.
5091.ip ${nrcpts}
5092The number of validated recipients for a single message.
5093Note: since recipient validation happens after
5094.i check_rcpt
5095has been called, the value in this ruleset
5096is one less than what might be expected.
5097.ip ${ntries}
5098The number of delivery attempts.
5099.ip ${opMode}
5100The current operation mode (from the
5101.b \-b
5102flag).
5103.ip ${quarantine}
5104The quarantine reason for the envelope,
5105if it is quarantined.
5106.ip ${queue_interval}
5107The queue run interval given by the
5108.b \-q
5109flag.
5110For example,
5111.b \-q30m
5112would set
5113.b ${queue_interval}
5114to
5115.q 00:30:00 .
5116.ip ${rcpt_addr}
5117The address part of the resolved triple of the address given for the
5118.sm "SMTP RCPT"
5119command.
5120Defined in the SMTP server only after a RCPT command.
5121.ip ${rcpt_host}
5122The host from the resolved triple of the address given for the
5123.sm "SMTP RCPT"
5124command.
5125Defined in the SMTP server only after a RCPT command.
5126.ip ${rcpt_mailer}
5127The mailer from the resolved triple of the address given for the
5128.sm "SMTP RCPT"
5129command.
5130Defined in the SMTP server only after a RCPT command.
5131.ip ${server_addr}
5132The address of the server of the current outgoing SMTP connection.
5133For LMTP delivery the macro is set to the name of the mailer.
5134.ip ${server_name}
5135The name of the server of the current outgoing SMTP or LMTP connection.
5136.ip ${time}
5137The output of the
5138.i time (3)
5139function, i.e., the number of seconds since 0 hours, 0 minutes,
51400 seconds, January 1, 1970, Coordinated Universal Time (UTC).
5141.ip ${tls_version}
5142The TLS/SSL version used for the connection, e.g., TLSv1, SSLv3, SSLv2;
5143defined after STARTTLS has been used.
5144.ip ${total_rate}
5145The total number of incoming connections over the time interval specified
5146by ConnectionRateWindowSize.
5147.ip ${verify}
5148The result of the verification of the presented cert;
5149only defined after STARTTLS has been used (or attempted).
5150Possible values are:
5151.(b
5152.ta 13n
5153OK verification succeeded.
5154NO no cert presented.
5155NOT no cert requested.
5156FAIL cert presented but could not be verified,
5157 e.g., the signing CA is missing.
5158NONE STARTTLS has not been performed.
5159TEMP temporary error occurred.
5160PROTOCOL some protocol error occurred
5161 at the ESMTP level (not TLS).
5162SOFTWARE STARTTLS handshake failed,
5163 which is a fatal error for this session,
5164 the e-mail will be queued.
5165.)b
5166.pp
5167There are three types of dates that can be used.
5168The
5169.b $a
5170and
5171.b $b
5172macros are in RFC 822 format;
5173.b $a
5174is the time as extracted from the
5175.q Date:
5176line of the message
5177(if there was one),
5178and
5179.b $b
5180is the current date and time
5181(used for postmarks).
5182If no
5183.q Date:
5184line is found in the incoming message,
5185.b $a
5186is set to the current time also.
5187The
5188.b $d
5189macro is equivalent to the
5190.b $b
5191macro in UNIX
5192(ctime)
5193format.
5194.pp
5195The macros
5196.b $w ,
5197.b $j ,
5198and
5199.b $m
5200are set to the identity of this host.
5201.i Sendmail
5202tries to find the fully qualified name of the host
5203if at all possible;
5204it does this by calling
5205.i gethostname (2)
5206to get the current hostname
5207and then passing that to
5208.i gethostbyname (3)
5209which is supposed to return the canonical version of that host name.\**
5210.(f
5211\**For example, on some systems
5212.i gethostname
5213might return
5214.q foo
5215which would be mapped to
5216.q foo.bar.com
5217by
5218.i gethostbyname .
5219.)f
5220Assuming this is successful,
5221.b $j
5222is set to the fully qualified name
5223and
5224.b $m
5225is set to the domain part of the name
5226(everything after the first dot).
5227The
5228.b $w
5229macro is set to the first word
5230(everything before the first dot)
5231if you have a level 5 or higher configuration file;
5232otherwise, it is set to the same value as
5233.b $j .
5234If the canonification is not successful,
5235it is imperative that the config file set
5236.b $j
5237to the fully qualified domain name\**.
5238.(f
5239\**Older versions of sendmail didn't pre-define
5240.b $j
5241at all, so up until 8.6,
5242config files
5243.i always
5244had to define
5245.b $j .
5246.)f
5247.pp
5248The
5249.b $f
5250macro is the id of the sender
5251as originally determined;
5252when mailing to a specific host
5253the
5254.b $g
5255macro is set to the address of the sender
5256.ul
5257relative to the recipient.
5258For example,
5259if I send to
5260.q bollard@matisse.CS.Berkeley.EDU
5261from the machine
5262.q vangogh.CS.Berkeley.EDU
5263the
5264.b $f
5265macro will be
5266.q eric
5267and the
5268.b $g
5269macro will be
5270.q eric@vangogh.CS.Berkeley.EDU.
5271.pp
5272The
5273.b $x
5274macro is set to the full name of the sender.
5275This can be determined in several ways.
5276It can be passed as flag to
5277.i sendmail .
5278It can be defined in the
5279.sm NAME
5280environment variable.
5281The third choice is the value of the
5282.q Full-Name:
5283line in the header if it exists,
5284and the fourth choice is the comment field
5285of a
5286.q From:
5287line.
5288If all of these fail,
5289and if the message is being originated locally,
5290the full name is looked up in the
5291.i /etc/passwd
5292file.
5293.pp
5294When sending,
5295the
5296.b $h ,
5297.b $u ,
5298and
5299.b $z
5300macros get set to the host, user, and home directory
5301(if local)
5302of the recipient.
5303The first two are set from the
5304.b $@
5305and
5306.b $:
5307part of the rewriting rules, respectively.
5308.pp
5309The
5310.b $p
5311and
5312.b $t
5313macros are used to create unique strings
5314(e.g., for the
5315.q Message-Id:
5316field).
5317The
5318.b $i
5319macro is set to the queue id on this host;
5320if put into the timestamp line
5321it can be extremely useful for tracking messages.
5322The
5323.b $v
5324macro is set to be the version number of
5325.i sendmail ;
5326this is normally put in timestamps
5327and has been proven extremely useful for debugging.
5328.pp
5329The
5330.b $c
5331field is set to the
5332.q "hop count,"
5333i.e., the number of times this message has been processed.
5334This can be determined
5335by the
5336.b \-h
5337flag on the command line
5338or by counting the timestamps in the message.
5339.pp
5340The
5341.b $r
5342and
5343.b $s
5344fields are set to the protocol used to communicate with
5345.i sendmail
5346and the sending hostname.
5347They can be set together using the
5348.b \-p
5349command line flag or separately using the
5350.b \-M
5351or
5352.b \-oM
5353flags.
5354.pp
5355The
5356.b $_
5357is set to a validated sender host name.
5358If the sender is running an RFC 1413 compliant IDENT server
5359and the receiver has the IDENT protocol turned on,
5360it will include the user name on that host.
5361.pp
5362The
5363.b ${client_name} ,
5364.b ${client_addr} ,
5365and
5366.b ${client_port}
5367macros
5368are set to the name, address, and port number of the SMTP client
5369who is invoking
5370.i sendmail
5371as a server.
5372These can be used in the
5373.i check_*
5374rulesets (using the
5375.b $&
5376deferred evaluation form, of course!).
5377.sh 2 "C and F \*- Define Classes"
5378.pp
5379Classes of phrases may be defined
5380to match on the left hand side of rewriting rules,
5381where a
5382.q phrase
5383is a sequence of characters that does not contain space characters.
5384For example
5385a class of all local names for this site
5386might be created
5387so that attempts to send to oneself
5388can be eliminated.
5389These can either be defined directly in the configuration file
5390or read in from another file.
5391Classes are named as a single letter or a word in {braces}.
5392Class names beginning with lower case letters
5393and special characters are reserved for system use.
5394Classes defined in config files may be given names
5395from the set of upper case letters for short names
5396or beginning with an upper case letter for long names.
5397.pp
5398The syntax is:
5399.(b F
5400.b C \c
5401.i c\|phrase1
5402.i phrase2...
5403.br
5404.b F \c
5405.i c\|file
5406.br
5407.b F \c
5408.i c\||program
5409.br
5410.b F \c
5411.i c\|[mapkey]@mapclass:mapspec
5412.)b
5413The first form defines the class
5414.i c
5415to match any of the named words.
5416If
5417.i phrase1
5418or
5419.i phrase2
5420is another class,
5421e.g.,
5422.i $=S ,
5423the contents of class
5424.i S
5425are added to class
5426.i c .
5427It is permissible to split them among multiple lines;
5428for example, the two forms:
5429.(b
5430CHmonet ucbmonet
5431.)b
5432and
5433.(b
5434CHmonet
5435CHucbmonet
5436.)b
5437are equivalent.
5438The ``F'' forms
5439read the elements of the class
5440.i c
5441from the named
5442.i file ,
5443.i program ,
5444or
5445.i "map specification" .
5446Each element should be listed on a separate line.
5447To specify an optional file, use ``\-o'' between the class
5448name and the file name, e.g.,
5449.(b
5450Fc \-o /path/to/file
5451.)b
5452If the file can't be used,
5453.i sendmail
5454will not complain but silently ignore it.
5455The map form should be an optional map key, an at sign,
5456and a map class followed by the specification for that map.
5457Examples include:
5458.(b
5459F{VirtHosts}@ldap:\-k (&(objectClass=virtHosts)(host=*)) \-v host
5460F{MyClass}foo@hash:/etc/mail/classes
5461.)b
5462will fill the class
5463.b $={VirtHosts}
5464from an LDAP map lookup and
5465.b $={MyClass}
5466from a hash database map lookup of the
5467.b foo .
5468There is also a built-in schema that can be accessed by only specifying:
5469.(b
5470F{\c
5471.i ClassName }@LDAP
5472.)b
5473This will tell sendmail to use the default schema:
5474.(b
5475\-k (&(objectClass=sendmailMTAClass)
5476 (sendmailMTAClassName=\c
5477.i ClassName )
5478 (|(sendmailMTACluster=${sendmailMTACluster})
5479 (sendmailMTAHost=$j)))
5480\-v sendmailMTAClassValue
5481.)b
5482Note that the lookup is only done when sendmail is initially started.
5483.pp
5484Elements of classes can be accessed in rules using
5485.b $=
5486or
5487.b $~ .
5488The
5489.b $~
5490(match entries not in class)
5491only matches a single word;
5492multi-word entries in the class are ignored in this context.
5493.pp
5494Some classes have internal meaning to
5495.i sendmail :
5496.nr ii 0.5i
5497.\".ip $=b
5498.\"A set of Content-Types that will not have the newline character
5499.\"translated to CR-LF before encoding into base64 MIME.
5500.\"The class can have major times
5501.\"(e.g.,
5502.\".q image )
5503.\"or full types
5504.\"(such as
5505.\".q application/octet-stream ).
5506.\"The class is initialized with
5507.\".q application/octet-stream ,
5508.\".q image ,
5509.\".q audio ,
5510.\"and
5511.\".q video .
5512.ip $=e
5513contains the Content-Transfer-Encodings that can be 8\(->7 bit encoded.
5514It is predefined to contain
5515.q 7bit ,
5516.q 8bit ,
5517and
5518.q binary .
5519.ip $=k
5520set to be the same as
5521.b $k ,
5522that is, the UUCP node name.
5523.ip $=m
5524set to the set of domains by which this host is known,
5525initially just
5526.b $m .
5527.ip $=n
5528can be set to the set of MIME body types
5529that can never be eight to seven bit encoded.
5530It defaults to
5531.q multipart/signed .
5532Message types
5533.q message/*
5534and
5535.q multipart/*
5536are never encoded directly.
5537Multipart messages are always handled recursively.
5538The handling of message/* messages
5539are controlled by class
5540.b $=s .
5541.ip $=q
5542A set of Content-Types that will never be encoded as base64
5543(if they have to be encoded, they will be encoded as quoted-printable).
5544It can have primary types
5545(e.g.,
5546.q text )
5547or full types
5548(such as
5549.q text/plain ).
| 94.rm Ve
95.sp
96For Sendmail Version 8.14
97.)l
98.(f
99Sendmail is a trademark of Sendmail, Inc.
100US Patent Numbers 6865671, 6986037.
101.)f
102.sp 2
103.pp
104.i Sendmail \u\s-2TM\s0\d
105implements a general purpose internetwork mail routing facility
106under the UNIX\(rg
107operating system.
108It is not tied to any one transport protocol \*-
109its function may be likened to a crossbar switch,
110relaying messages from one domain into another.
111In the process,
112it can do a limited amount of message header editing
113to put the message into a format that is appropriate
114for the receiving domain.
115All of this is done under the control of a configuration file.
116.pp
117Due to the requirements of flexibility
118for
119.i sendmail ,
120the configuration file can seem somewhat unapproachable.
121However, there are only a few basic configurations
122for most sites,
123for which standard configuration files have been supplied.
124Most other configurations
125can be built by adjusting an existing configuration file
126incrementally.
127.pp
128.i Sendmail
129is based on
130RFC 821 (Simple Mail Transport Protocol),
131RFC 822 (Internet Mail Headers Format),
132RFC 974 (MX routing),
133RFC 1123 (Internet Host Requirements),
134RFC 1413 (Identification server),
135RFC 1652 (SMTP 8BITMIME Extension),
136RFC 1869 (SMTP Service Extensions),
137RFC 1870 (SMTP SIZE Extension),
138RFC 1891 (SMTP Delivery Status Notifications),
139RFC 1892 (Multipart/Report),
140RFC 1893 (Enhanced Mail System Status Codes),
141RFC 1894 (Delivery Status Notifications),
142RFC 1985 (SMTP Service Extension for Remote Message Queue Starting),
143RFC 2033 (Local Message Transmission Protocol),
144RFC 2034 (SMTP Service Extension for Returning Enhanced Error Codes),
145RFC 2045 (MIME),
146RFC 2476 (Message Submission),
147RFC 2487 (SMTP Service Extension for Secure SMTP over TLS),
148RFC 2554 (SMTP Service Extension for Authentication),
149RFC 2821 (Simple Mail Transfer Protocol),
150RFC 2822 (Internet Message Format),
151RFC 2852 (Deliver By SMTP Service Extension),
152and
153RFC 2920 (SMTP Service Extension for Command Pipelining).
154However, since
155.i sendmail
156is designed to work in a wider world,
157in many cases it can be configured to exceed these protocols.
158These cases are described herein.
159.pp
160Although
161.i sendmail
162is intended to run
163without the need for monitoring,
164it has a number of features
165that may be used to monitor or adjust the operation
166under unusual circumstances.
167These features are described.
168.pp
169Section one describes how to do a basic
170.i sendmail
171installation.
172Section two
173explains the day-to-day information you should know
174to maintain your mail system.
175If you have a relatively normal site,
176these two sections should contain sufficient information
177for you to install
178.i sendmail
179and keep it happy.
180Section three
181has information regarding the command line arguments.
182Section four
183describes some parameters that may be safely tweaked.
184Section five
185contains the nitty-gritty information about the configuration
186file.
187This section is for masochists
188and people who must write their own configuration file.
189Section six
190describes configuration that can be done at compile time.
191The appendixes give a brief
192but detailed explanation of a number of features
193not described in the rest of the paper.
194.bp 7
195.sh 1 "BASIC INSTALLATION"
196.pp
197There are two basic steps to installing
198.i sendmail .
199First, you have to compile and install the binary.
200If
201.i sendmail
202has already been ported to your operating system
203that should be simple.
204Second, you must build a run-time configuration file.
205This is a file that
206.i sendmail
207reads when it starts up
208that describes the mailers it knows about,
209how to parse addresses,
210how to rewrite the message header,
211and the settings of various options.
212Although the configuration file can be quite complex,
213a configuration can usually be built
214using an M4-based configuration language.
215Assuming you have the standard
216.i sendmail
217distribution, see
218.i cf/README
219for further information.
220.pp
221The remainder of this section will describe the installation of
222.i sendmail
223assuming you can use one of the existing configurations
224and that the standard installation parameters are acceptable.
225All pathnames and examples
226are given from the root of the
227.i sendmail
228subtree,
229normally
230.i /usr/src/usr.\*(SD/sendmail
231on 4.4BSD-based systems.
232.pp
233Continue with the next section if you need/want to compile
234.i sendmail
235yourself.
236If you have a running binary already on your system,
237you should probably skip to section 1.2.
238.sh 2 "Compiling Sendmail"
239.pp
240All
241.i sendmail
242source is in the
243.i sendmail
244subdirectory.
245To compile sendmail,
246.q cd
247into the
248.i sendmail
249directory and type
250.(b
251\&./Build
252.)b
253This will leave the binary in an appropriately named subdirectory,
254e.g.,
255obj.BSD-OS.2.1.i386.
256It works for multiple object versions
257compiled out of the same directory.
258.sh 3 "Tweaking the Build Invocation"
259.pp
260You can give parameters on the
261.i Build
262command.
263In most cases these are only used when the
264.i obj.*
265directory is first created.
266To restart from scratch, use
267.i -c .
268These commands include:
269.nr ii 0.5i
270.ip "\-L \fIlibdirs\fP"
271A list of directories to search for libraries.
272.ip "\-I \fIincdirs\fP"
273A list of directories to search for include files.
274.ip "\-E \fIenvar\fP=\fIvalue\fP"
275Set an environment variable to an indicated
276.i value
277before compiling.
278.ip "\-c"
279Create a new
280.i obj.*
281tree before running.
282.ip "\-f \fIsiteconfig\fP"
283Read the indicated site configuration file.
284If this parameter is not specified,
285.i Build
286includes
287.i all
288of the files
289.i $BUILDTOOLS/Site/site.$oscf.m4
290and
291.i $BUILDTOOLS/Site/site.config.m4 ,
292where $BUILDTOOLS is normally
293.i \&../devtools
294and $oscf is the same name as used on the
295.i obj.*
296directory.
297See below for a description of the site configuration file.
298.ip "\-S"
299Skip auto-configuration.
300.i Build
301will avoid auto-detecting libraries if this is set.
302All libraries and map definitions must be specified
303in the site configuration file.
304.lp
305Most other parameters are passed to the
306.i make
307program; for details see
308.i $BUILDTOOLS/README .
309.sh 3 "Creating a Site Configuration File"
310.\"XXX
311.pp
312(This section is not yet complete.
313For now, see the file devtools/README for details.)
314See sendmail/README for various compilation flags that can be set.
315.sh 3 "Tweaking the Makefile"
316.pp
317.\" .b "XXX This should all be in the Site Configuration File section."
318.i Sendmail
319supports two different formats
320for the local (on disk) version of databases,
321notably the
322.i aliases
323database.
324At least one of these should be defined if at all possible.
325.nr ii 1i
326.ip NDBM
327The ``new DBM'' format,
328available on nearly all systems around today.
329This was the preferred format prior to 4.4BSD.
330It allows such complex things as multiple databases
331and closing a currently open database.
332.ip NEWDB
333The Berkeley DB package.
334If you have this, use it.
335It allows
336long records,
337multiple open databases,
338real in-memory caching,
339and so forth.
340You can define this in conjunction with
341.sm NDBM ;
342if you do,
343old alias databases are read,
344but when a new database is created it will be in NEWDB format.
345As a nasty hack,
346if you have NEWDB, NDBM, and NIS defined,
347and if the alias file name includes the substring
348.q /yp/ ,
349.i sendmail
350will create both new and old versions of the alias file
351during a
352.i newalias
353command.
354This is required because the Sun NIS/YP system
355reads the DBM version of the alias file.
356It's ugly as sin,
357but it works.
358.lp
359If neither of these are defined,
360.i sendmail
361reads the alias file into memory on every invocation.
362This can be slow and should be avoided.
363There are also several methods for remote database access:
364.ip LDAP
365Lightweight Directory Access Protocol.
366.ip NIS
367Sun's Network Information Services (formerly YP).
368.ip NISPLUS
369Sun's NIS+ services.
370.ip NETINFO
371NeXT's NetInfo service.
372.ip HESIOD
373Hesiod service (from Athena).
374.lp
375Other compilation flags are set in
376.i conf.h
377and should be predefined for you
378unless you are porting to a new environment.
379For more options see
380.i sendmail/README .
381.sh 3 "Compilation and installation"
382.pp
383After making the local system configuration described above,
384You should be able to compile and install the system.
385The script
386.q Build
387is the best approach on most systems:
388.(b
389\&./Build
390.)b
391This will use
392.i uname (1)
393to create a custom Makefile for your environment.
394.pp
395If you are installing in the standard places,
396you should be able to install using
397.(b
398\&./Build install
399.)b
400This should install the binary in
401/usr/\*(SD
402and create links from
403/usr/\*(SB/newaliases
404and
405/usr/\*(SB/mailq
406to
407/usr/\*(SD/sendmail.
408On most systems it will also format and install man pages.
409Notice: as of version 8.12
410.i sendmail
411will no longer be installed set-user-ID root by default.
412If you really want to use the old method, you can specify it as target:
413.(b
414\&./Build install-set-user-id
415.)b
416.sh 2 "Configuration Files"
417.pp
418.i Sendmail
419cannot operate without a configuration file.
420The configuration defines the mail delivery mechanisms understood at this site,
421how to access them,
422how to forward email to remote mail systems,
423and a number of tuning parameters.
424This configuration file is detailed
425in the later portion of this document.
426.pp
427The
428.i sendmail
429configuration can be daunting at first.
430The world is complex,
431and the mail configuration reflects that.
432The distribution includes an m4-based configuration package
433that hides a lot of the complexity.
434See
435.i cf/README
436for details.
437.pp
438Our configuration files are processed by
439.i m4
440to facilitate local customization;
441the directory
442.i cf
443of the
444.i sendmail
445distribution directory
446contains the source files.
447This directory contains several subdirectories:
448.nr ii 1i
449.ip cf
450Both site-dependent and site-independent descriptions of hosts.
451These can be literal host names
452(e.g.,
453.q ucbvax.mc )
454when the hosts are gateways
455or more general descriptions
456(such as
457.q "generic-solaris2.mc"
458as a general description of an SMTP-connected host
459running Solaris 2.x.
460Files ending
461.b \&.mc
462(``M4 Configuration'')
463are the input descriptions;
464the output is in the corresponding
465.b \&.cf
466file.
467The general structure of these files is described below.
468.ip domain
469Site-dependent subdomain descriptions.
470These are tied to the way your organization wants to do addressing.
471For example,
472.b domain/CS.Berkeley.EDU.m4
473is our description for hosts in the CS.Berkeley.EDU subdomain.
474These are referenced using the
475.sm DOMAIN
476.b m4
477macro in the
478.b \&.mc
479file.
480.ip feature
481Definitions of specific features that some particular host in your site
482might want.
483These are referenced using the
484.sm FEATURE
485.b m4
486macro.
487An example feature is
488use_cw_file
489(which tells
490.i sendmail
491to read an /etc/mail/local-host-names file on startup
492to find the set of local names).
493.ip hack
494Local hacks, referenced using the
495.sm HACK
496.b m4
497macro.
498Try to avoid these.
499The point of having them here is to make it clear that they smell.
500.ip m4
501Site-independent
502.i m4 (1)
503include files that have information common to all configuration files.
504This can be thought of as a
505.q #include
506directory.
507.ip mailer
508Definitions of mailers,
509referenced using the
510.sm MAILER
511.b m4
512macro.
513The mailer types that are known in this distribution are
514fax,
515local,
516smtp,
517uucp,
518and usenet.
519For example, to include support for the UUCP-based mailers,
520use
521.q MAILER(uucp) .
522.ip ostype
523Definitions describing various operating system environments
524(such as the location of support files).
525These are referenced using the
526.sm OSTYPE
527.b m4
528macro.
529.ip sh
530Shell files used by the
531.b m4
532build process.
533You shouldn't have to mess with these.
534.ip siteconfig
535Local UUCP connectivity information.
536This directory has been supplanted by the mailertable feature;
537any new configurations should use that feature to do UUCP
538(and other) routing.
539The use of this directory is deprecated.
540.pp
541If you are in a new domain
542(e.g., a company),
543you will probably want to create a
544cf/domain
545file for your domain.
546This consists primarily of relay definitions
547and features you want enabled site-wide:
548for example, Berkeley's domain definition
549defines relays for
550BitNET
551and UUCP.
552These are specific to Berkeley,
553and should be fully-qualified internet-style domain names.
554Please check to make certain they are reasonable for your domain.
555.pp
556Subdomains at Berkeley are also represented in the
557cf/domain
558directory.
559For example,
560the domain
561CS.Berkeley.EDU
562is the Computer Science subdomain,
563EECS.Berkeley.EDU
564is the Electrical Engineering and Computer Sciences subdomain,
565and
566S2K.Berkeley.EDU
567is the Sequoia 2000 subdomain.
568You will probably have to add an entry to this directory
569to be appropriate for your domain.
570.pp
571You will have to use or create
572.b \&.mc
573files in the
574.i cf/cf
575subdirectory for your hosts.
576This is detailed in the
577cf/README
578file.
579.sh 2 "Details of Installation Files"
580.pp
581This subsection describes the files that
582comprise the
583.i sendmail
584installation.
585.sh 3 "/usr/\*(SD/sendmail"
586.pp
587The binary for
588.i sendmail
589is located in /usr/\*(SD\**.
590.(f
591\**This is usually
592/usr/sbin
593on 4.4BSD and newer systems;
594many systems install it in
595/usr/lib.
596I understand it is in /usr/ucblib
597on System V Release 4.
598.)f
599It should be set-group-ID smmsp as described in
600sendmail/SECURITY.
601For security reasons,
602/, /usr, and /usr/\*(SD
603should be owned by root, mode 0755\**.
604.(f
605\**Some vendors ship them owned by bin;
606this creates a security hole that is not actually related to
607.i sendmail .
608Other important directories that should have restrictive ownerships
609and permissions are
610/bin, /usr/bin, /etc, /etc/mail, /usr/etc, /lib, and /usr/lib.
611.)f
612.sh 3 "/etc/mail/sendmail.cf"
613.pp
614This is the main configuration file for
615.i sendmail \**.
616.(f
617\**Actually, the pathname varies depending on the operating system;
618/etc/mail is the preferred directory.
619Some older systems install it in
620.b /usr/lib/sendmail.cf ,
621and I've also seen it in
622.b /usr/ucblib .
623If you want to move this file,
624add -D_PATH_SENDMAILCF=\e"/file/name\e"
625to the flags passed to the C compiler.
626Moving this file is not recommended:
627other programs and scripts know of this location.
628.)f
629This is one of the two non-library file names compiled into
630.i sendmail \**,
631the other is /etc/mail/submit.cf.
632.(f
633\**The system libraries can reference other files;
634in particular, system library subroutines that
635.i sendmail
636calls probably reference
637.i /etc/passwd
638and
639.i /etc/resolv.conf .
640.)f
641.pp
642The configuration file is normally created
643using the distribution files described above.
644If you have a particularly unusual system configuration
645you may need to create a special version.
646The format of this file is detailed in later sections
647of this document.
648.sh 3 "/etc/mail/submit.cf"
649.pp
650This is the configuration file for
651.i sendmail
652when it is used for initial mail submission, in which case
653it is also called ``Mail Submission Program'' (MSP)
654in contrast to ``Mail Transfer Agent'' (MTA).
655Starting with version 8.12,
656.i sendmail
657uses one of two different configuration files based on its operation mode
658(or the new
659.b \-A
660option).
661For initial mail submission, i.e., if one of the options
662.b \-bm
663(default),
664.b \-bs ,
665or
666.b \-t
667is specified, submit.cf is used (if available),
668for other operations sendmail.cf is used.
669Details can be found in
670.i sendmail/SECURITY .
671submit.cf is shipped with sendmail (in cf/cf/) and is installed by default.
672If changes to the configuration need to be made, start with
673cf/cf/submit.mc and follow the instruction in cf/README.
674.sh 3 "/usr/\*(SB/newaliases"
675.pp
676The
677.i newaliases
678command should just be a link to
679.i sendmail :
680.(b
681rm \-f /usr/\*(SB/newaliases
682ln \-s /usr/\*(SD/sendmail /usr/\*(SB/newaliases
683.)b
684This can be installed in whatever search path you prefer
685for your system.
686.sh 3 "/usr/\*(SB/hoststat"
687.pp
688The
689.i hoststat
690command should just be a link to
691.i sendmail ,
692in a fashion similar to
693.i newaliases .
694This command lists the status of the last mail transaction
695with all remote hosts. The
696.b \-v
697flag will prevent the status display from being truncated.
698It functions only when the
699.b HostStatusDirectory
700option is set.
701.sh 3 "/usr/\*(SB/purgestat"
702.pp
703This command is also a link to
704.i sendmail .
705It flushes expired (Timeout.hoststatus) information that is stored in the
706.b HostStatusDirectory
707tree.
708.sh 3 "/var/spool/mqueue"
709.pp
710The directory
711.i /var/spool/mqueue
712should be created to hold the mail queue.
713This directory should be mode 0700
714and owned by root.
715.pp
716The actual path of this directory
717is defined by the
718.b QueueDirectory
719option of the
720.i sendmail.cf
721file.
722To use multiple queues,
723supply a value ending with an asterisk.
724For example,
725.i /var/spool/mqueue/qd*
726will use all of the directories or symbolic links to directories
727beginning with `qd' in
728.i /var/spool/mqueue
729as queue directories.
730Do not change the queue directory structure
731while sendmail is running.
732.pp
733If these directories have subdirectories or symbolic links to directories
734named `qf', `df', and `xf', then these will be used for the different
735queue file types.
736That is, the data files are stored in the `df' subdirectory,
737the transcript files are stored in the `xf' subdirectory, and
738all others are stored in the `qf' subdirectory.
739.pp
740If shared memory support is compiled in,
741.i sendmail
742stores the available diskspace in a shared memory segment
743to make the values readily available to all children without
744incurring system overhead.
745In this case, only the daemon updates the data;
746i.e., the sendmail daemon creates the shared memory segment
747and deletes it if it is terminated.
748To use this,
749.i sendmail
750must have been compiled with support for shared memory
751(-DSM_CONF_SHM)
752and the option
753.b SharedMemoryKey
754must be set.
755Notice: do not use the same key for
756.i sendmail
757invocations with different queue directories
758or different queue group declarations.
759Access to shared memory is not controlled by locks,
760i.e., there is a race condition when data in the shared memory is updated.
761However, since operation of
762.i sendmail
763does not rely on the data in the shared memory, this does not negatively
764influence the behavior.
765.sh 3 "/var/spool/clientmqueue"
766.pp
767The directory
768.i /var/spool/clientmqueue
769should be created to hold the mail queue.
770This directory should be mode 0770
771and owned by user smmsp, group smmsp.
772.pp
773The actual path of this directory
774is defined by the
775.b QueueDirectory
776option of the
777.i submit.cf
778file.
779.sh 3 "/var/spool/mqueue/.hoststat"
780.pp
781This is a typical value for the
782.b HostStatusDirectory
783option,
784containing one file per host
785that this sendmail has chatted with recently.
786It is normally a subdirectory of
787.i mqueue .
788.sh 3 "/etc/mail/aliases*"
789.pp
790The system aliases are held in
791.q /etc/mail/aliases .
792A sample is given in
793.q sendmail/aliases
794which includes some aliases which
795.i must
796be defined:
797.(b
798cp sendmail/aliases /etc/mail/aliases
799.i "edit /etc/mail/aliases"
800.)b
801You should extend this file with any aliases that are apropos to your system.
802.pp
803Normally
804.i sendmail
805looks at a database version of the files,
806stored either in
807.q /etc/mail/aliases.dir
808and
809.q /etc/mail/aliases.pag
810or
811.q /etc/mail/aliases.db
812depending on which database package you are using.
813The actual path of this file
814is defined in the
815.b AliasFile
816option of the
817.i sendmail.cf
818file.
819.pp
820The permissions of the alias file and the database versions
821should be 0640 to prevent local denial of service attacks
822as explained in the top level
823.b README
824in the sendmail distribution.
825If the permissions 0640 are used, be sure that only trusted users belong
826to the group assigned to those files. Otherwise, files should not even
827be group readable.
828.sh 3 "/etc/rc or /etc/init.d/sendmail"
829.pp
830It will be necessary to start up the
831.i sendmail
832daemon when your system reboots.
833This daemon performs two functions:
834it listens on the SMTP socket for connections
835(to receive mail from a remote system)
836and it processes the queue periodically
837to insure that mail gets delivered when hosts come up.
838.pp
839If necessary, add the following lines to
840.q /etc/rc
841(or
842.q /etc/rc.local
843as appropriate)
844in the area where it is starting up the daemons
845on a BSD-base system,
846or on a System-V-based system
847in one of the startup files, typically
848.q /etc/init.d/sendmail :
849.(b
850if [ \-f /usr/\*(SD/sendmail \-a \-f /etc/mail/sendmail.cf ]; then
851 (cd /var/spool/mqueue; rm \-f xf*)
852 /usr/\*(SD/sendmail \-bd \-q30m &
853 echo \-n ' sendmail' >/dev/console
854fi
855.)b
856The
857.q cd
858and
859.q rm
860commands insure that all transcript files have been removed;
861extraneous transcript files may be left around
862if the system goes down in the middle of processing a message.
863The line that actually invokes
864.i sendmail
865has two flags:
866.q \-bd
867causes it to listen on the SMTP port,
868and
869.q \-q30m
870causes it to run the queue every half hour.
871.pp
872Some people use a more complex startup script,
873removing zero length qf/hf/Qf files and df files for which there is no
874qf/hf/Qf file.
875Note this is not advisable.
876For example, see Figure 1
877for an example of a complex script which does this clean up.
878.(z
879.hl
880#!/bin/sh
881# remove zero length qf/hf/Qf files
882for qffile in qf* hf* Qf*
883do
884 if [ \-r $qffile ]
885 then
886 if [ ! \-s $qffile ]
887 then
888 echo \-n " <zero: $qffile>" > /dev/console
889 rm \-f $qffile
890 fi
891 fi
892done
893# rename tf files to be qf if the qf does not exist
894for tffile in tf*
895do
896 qffile=`echo $tffile | sed 's/t/q/'`
897 if [ \-r $tffile \-a ! \-f $qffile ]
898 then
899 echo \-n " <recovering: $tffile>" > /dev/console
900 mv $tffile $qffile
901 else
902 if [ \-f $tffile ]
903 then
904 echo \-n " <extra: $tffile>" > /dev/console
905 rm \-f $tffile
906 fi
907 fi
908done
909# remove df files with no corresponding qf/hf/Qf files
910for dffile in df*
911do
912 qffile=`echo $dffile | sed 's/d/q/'`
913 hffile=`echo $dffile | sed 's/d/h/'`
914 Qffile=`echo $dffile | sed 's/d/Q/'`
915 if [ \-r $dffile \-a ! \-f $qffile \-a ! \-f $hffile \-a ! \-f $Qffile ]
916 then
917 echo \-n " <incomplete: $dffile>" > /dev/console
918 mv $dffile `echo $dffile | sed 's/d/D/'`
919 fi
920done
921# announce files that have been saved during disaster recovery
922for xffile in [A-Z]f*
923do
924 if [ \-f $xffile ]
925 then
926 echo \-n " <panic: $xffile>" > /dev/console
927 fi
928done
929.sp
930.ce
931Figure 1 \(em A complex startup script
932.hl
933.)z
934.sh 3 "/etc/mail/helpfile"
935.pp
936This is the help file used by the SMTP
937.b HELP
938command.
939It should be copied from
940.q sendmail/helpfile :
941.(b
942cp sendmail/helpfile /etc/mail/helpfile
943.)b
944The actual path of this file
945is defined in the
946.b HelpFile
947option of the
948.i sendmail.cf
949file.
950.sh 3 "/etc/mail/statistics"
951.pp
952If you wish to collect statistics
953about your mail traffic,
954you should create the file
955.q /etc/mail/statistics :
956.(b
957cp /dev/null /etc/mail/statistics
958chmod 0600 /etc/mail/statistics
959.)b
960This file does not grow.
961It is printed with the program
962.q mailstats/mailstats.c.
963The actual path of this file
964is defined in the
965.b S
966option of the
967.i sendmail.cf
968file.
969.sh 3 "/usr/\*(SB/mailq"
970.pp
971If
972.i sendmail
973is invoked as
974.q mailq,
975it will simulate the
976.b \-bp
977flag
978(i.e.,
979.i sendmail
980will print the contents of the mail queue;
981see below).
982This should be a link to /usr/\*(SD/sendmail.
983.sh 3 "sendmail.pid"
984.pp
985.i sendmail
986stores its current pid in the file specified by the
987.b PidFile
988option (default is _PATH_SENDMAILPID).
989.i sendmail
990uses
991.b TempFileMode
992(which defaults to 0600) as
993the permissions of that file
994to prevent local denial of service attacks
995as explained in the top level
996.b README
997in the sendmail distribution.
998If the file already exists, then it might be necessary to
999change the permissions accordingly, e.g.,
1000.(b
1001chmod 0600 /var/run/sendmail.pid
1002.)b
1003Note that as of version 8.13, this file is unlinked when
1004.i sendmail
1005exits.
1006As a result of this change, a script such as the following,
1007which may have worked prior to 8.13, will no longer work:
1008.(b
1009# stop & start sendmail
1010PIDFILE=/var/run/sendmail.pid
1011kill `head -1 $PIDFILE`
1012`tail -1 $PIDFILE`
1013.)b
1014because it assumes that the pidfile will still exist even
1015after killing the process to which it refers.
1016Below is a script which will work correctly
1017on both newer and older versions:
1018.(b
1019# stop & start sendmail
1020PIDFILE=/var/run/sendmail.pid
1021pid=`head -1 $PIDFILE`
1022cmd=`tail -1 $PIDFILE`
1023kill $pid
1024$cmd
1025.)b
1026This is just an example script, it does not perform any error checks,
1027e.g., whether the pidfile exists at all.
1028.sh 3 "Map Files"
1029.pp
1030To prevent local denial of service attacks
1031as explained in the top level
1032.b README
1033in the sendmail distribution,
1034the permissions of map files created by
1035.i makemap
1036should be 0640.
1037The use of 0640 implies that only trusted users belong to the group
1038assigned to those files.
1039If those files already exist, then it might be necessary to
1040change the permissions accordingly, e.g.,
1041.(b
1042cd /etc/mail
1043chmod 0640 *.db *.pag *.dir
1044.)b
1045.sh 1 "NORMAL OPERATIONS"
1046.sh 2 "The System Log"
1047.pp
1048The system log is supported by the
1049.i syslogd \|(8)
1050program.
1051All messages from
1052.i sendmail
1053are logged under the
1054.sm LOG_MAIL
1055facility\**.
1056.(f
1057\**Except on Ultrix,
1058which does not support facilities in the syslog.
1059.)f
1060.sh 3 "Format"
1061.pp
1062Each line in the system log
1063consists of a timestamp,
1064the name of the machine that generated it
1065(for logging from several machines
1066over the local area network),
1067the word
1068.q sendmail: ,
1069and a message\**.
1070.(f
1071\**This format may vary slightly if your vendor has changed
1072the syntax.
1073.)f
1074Most messages are a sequence of
1075.i name \c
1076=\c
1077.i value
1078pairs.
1079.pp
1080The two most common lines are logged when a message is processed.
1081The first logs the receipt of a message;
1082there will be exactly one of these per message.
1083Some fields may be omitted if they do not contain interesting information.
1084Fields are:
1085.ip from
1086The envelope sender address.
1087.ip size
1088The size of the message in bytes.
1089.ip class
1090The class (i.e., numeric precedence) of the message.
1091.ip pri
1092The initial message priority (used for queue sorting).
1093.ip nrcpts
1094The number of envelope recipients for this message
1095(after aliasing and forwarding).
1096.ip msgid
1097The message id of the message (from the header).
1098.ip bodytype
1099The message body type (7BIT or 8BITMIME),
1100as determined from the envelope.
1101.ip proto
1102The protocol used to receive this message (e.g., ESMTP or UUCP)
1103.ip daemon
1104The daemon name from the
1105.b DaemonPortOptions
1106setting.
1107.ip relay
1108The machine from which it was received.
1109.lp
1110There is also one line logged per delivery attempt
1111(so there can be several per message if delivery is deferred
1112or there are multiple recipients).
1113Fields are:
1114.ip to
1115A comma-separated list of the recipients to this mailer.
1116.ip ctladdr
1117The ``controlling user'', that is, the name of the user
1118whose credentials we use for delivery.
1119.ip delay
1120The total delay between the time this message was received
1121and the current delivery attempt.
1122.ip xdelay
1123The amount of time needed in this delivery attempt
1124(normally indicative of the speed of the connection).
1125.ip mailer
1126The name of the mailer used to deliver to this recipient.
1127.ip relay
1128The name of the host that actually accepted (or rejected) this recipient.
1129.ip dsn
1130The enhanced error code (RFC 2034) if available.
1131.ip stat
1132The delivery status.
1133.lp
1134Not all fields are present in all messages;
1135for example, the relay is usually not listed for local deliveries.
1136.sh 3 "Levels"
1137.pp
1138If you have
1139.i syslogd \|(8)
1140or an equivalent installed,
1141you will be able to do logging.
1142There is a large amount of information that can be logged.
1143The log is arranged as a succession of levels.
1144At the lowest level
1145only extremely strange situations are logged.
1146At the highest level,
1147even the most mundane and uninteresting events
1148are recorded for posterity.
1149As a convention,
1150log levels under ten
1151are considered generally
1152.q useful;
1153log levels above 64
1154are reserved for debugging purposes.
1155Levels from 11\-64 are reserved for verbose information
1156that some sites might want.
1157.pp
1158A complete description of the log levels
1159is given in section ``Log Level''.
1160.sh 2 "Dumping State"
1161.pp
1162You can ask
1163.i sendmail
1164to log a dump of the open files
1165and the connection cache
1166by sending it a
1167.sm SIGUSR1
1168signal.
1169The results are logged at
1170.sm LOG_DEBUG
1171priority.
1172.sh 2 "The Mail Queues"
1173.pp
1174Mail messages may either be delivered immediately or be held for later
1175delivery.
1176Held messages are placed into a holding directory called a mail queue.
1177.pp
1178A mail message may be queued for these reasons:
1179.bu
1180If a mail message is temporarily undeliverable, it is queued
1181and delivery is attempted later.
1182If the message is addressed to multiple recipients, it is queued
1183only for those recipients to whom delivery is not immediately possible.
1184.bu
1185If the SuperSafe option is set to true,
1186all mail messages are queued while delivery is attempted.
1187.bu
1188If the DeliveryMode option is set to queue-only or defer,
1189all mail is queued, and no immediate delivery is attempted.
1190.bu
1191If the load average becomes higher than the value of the QueueLA option
1192and the
1193.b QueueFactor
1194(\c
1195.b q )
1196option divided by the difference in the current load average and the
1197.b QueueLA
1198option plus one
1199is less than the priority of the message,
1200messages are queued rather than immediately delivered.
1201.bu
1202One or more addresses are marked as expensive and delivery is postponed
1203until the next queue run or one or more address are marked as held via
1204mailer which uses the hold mailer flag.
1205.bu
1206The mail message has been marked as quarantined via a mail filter or
1207rulesets.
1208.bu
1209.sh 3 "Queue Groups and Queue Directories"
1210.pp
1211There are one or more mail queues.
1212Each mail queue belongs to a queue group.
1213There is always a default queue group that is called ``mqueue''
1214(which is where messages go by default unless otherwise specified).
1215The directory or directories which comprise the default queue group
1216are specified by the QueueDirectory option.
1217There are zero or more
1218additional named queue groups declared using the
1219.b Q
1220command in the configuration file.
1221.pp
1222By default, a queued message is placed in the queue group
1223associated with the first recipient in the recipient list.
1224A recipient address is mapped to a queue group as follows.
1225First, if there is a ruleset called ``queuegroup'',
1226and if this ruleset maps the address to a queue group name,
1227then that queue group is chosen.
1228That is, the argument for the ruleset is the recipient address
1229and the result should be
1230.b $#
1231followed by the name of a queue group.
1232Otherwise, if the mailer associated with the address specifies
1233a queue group, then that queue group is chosen.
1234Otherwise, the default queue group is chosen.
1235.pp
1236A message with multiple recipients will be split
1237if different queue groups are chosen
1238by the mapping of recipients to queue groups.
1239.pp
1240When a message is placed in a queue group, and the queue group has
1241more than one queue, a queue is selected randomly.
1242.pp
1243If a message with multiple recipients is placed into a queue group
1244with the 'r' option (maximum number of recipients per message)
1245set to a positive value
1246.i N ,
1247and if there are more than
1248.i N
1249recipients
1250in the message, then the message will be split into multiple messages,
1251each of which have at most
1252.i N
1253recipients.
1254.pp
1255Notice: if multiple queue groups are used, do
1256.b not
1257move queue files around, e.g., into a different queue directory.
1258This may have weird effects and can cause mail not to be delivered.
1259Queue files and directories should be treated as opaque
1260and should not be manipulated directly.
1261.sh 3 "Queue Runs"
1262.pp
1263.i sendmail
1264has two different ways to process the queue(s).
1265The first one is to start queue runners after certain intervals
1266(``normal'' queue runners),
1267the second one is to keep queue runner processes around
1268(``persistent'' queue runners).
1269How to select either of these types is discussed in the appendix
1270``COMMAND LINE FLAGS''.
1271Persistent queue runners have the advantage that no new processes
1272need to be spawned at certain intervals; they just sleep for
1273a specified time after they finished a queue run.
1274Another advantage of persistent queue runners is that only one process
1275belonging to a workgroup (a workgroup is a set of queue groups)
1276collects the data for a queue run
1277and then multiple queue runner may go ahead using that data.
1278This can significantly reduce the disk I/O necessary to read the
1279queue files compared to starting multiple queue runners directly.
1280Their disadvantage is that a new queue run is only started
1281after all queue runners belonging to a group finished their tasks.
1282In case one of the queue runners tries delivery to a slow recipient site
1283at the end of a queue run, the next queue run may be substantially delayed.
1284In general this should be smoothed out due to the distribution of
1285those slow jobs, however, for sites with small number of
1286queue entries this might introduce noticable delays.
1287In general, persistent queue runners are only useful for
1288sites with big queues.
1289.sh 3 "Manual Intervention"
1290.pp
1291Under normal conditions the mail queue will be processed transparently.
1292However, you may find that manual intervention is sometimes necessary.
1293For example,
1294if a major host is down for a period of time
1295the queue may become clogged.
1296Although
1297.i sendmail
1298ought to recover gracefully when the host comes up,
1299you may find performance unacceptably bad in the meantime.
1300In that case you want to check the content of the queue
1301and manipulate it as explained in the next two sections.
1302.sh 3 "Printing the queue"
1303.pp
1304The contents of the queue(s) can be printed
1305using the
1306.i mailq
1307command
1308(or by specifying the
1309.b \-bp
1310flag to
1311.i sendmail ):
1312.(b
1313mailq
1314.)b
1315This will produce a listing of the queue id's,
1316the size of the message,
1317the date the message entered the queue,
1318and the sender and recipients.
1319If shared memory support is compiled in,
1320the flag
1321.b \-bP
1322can be used to print the number of entries in the queue(s),
1323provided a process updates the data.
1324However, as explained earlier, the output might be slightly wrong,
1325since access to the shared memory is not locked.
1326For example,
1327``unknown number of entries''
1328might be shown.
1329The internal counters are updated after each queue run
1330to the correct value again.
1331.sh 3 "Forcing the queue"
1332.pp
1333.i Sendmail
1334should run the queue automatically at intervals.
1335When using multiple queues,
1336a separate process will by default be created to
1337run each of the queues
1338unless the queue run is initiated by a user
1339with the verbose flag.
1340The algorithm is to read and sort the queue,
1341and then to attempt to process all jobs in order.
1342When it attempts to run the job,
1343.i sendmail
1344first checks to see if the job is locked.
1345If so, it ignores the job.
1346.pp
1347There is no attempt to insure that only one queue processor
1348exists at any time,
1349since there is no guarantee that a job cannot take forever
1350to process
1351(however,
1352.i sendmail
1353does include heuristics to try to abort jobs
1354that are taking absurd amounts of time;
1355technically, this violates RFC 821, but is blessed by RFC 1123).
1356Due to the locking algorithm,
1357it is impossible for one job to freeze the entire queue.
1358However,
1359an uncooperative recipient host
1360or a program recipient
1361that never returns
1362can accumulate many processes in your system.
1363Unfortunately,
1364there is no completely general way to solve this.
1365.pp
1366In some cases,
1367you may find that a major host going down
1368for a couple of days
1369may create a prohibitively large queue.
1370This will result in
1371.i sendmail
1372spending an inordinate amount of time
1373sorting the queue.
1374This situation can be fixed by moving the queue to a temporary place
1375and creating a new queue.
1376The old queue can be run later when the offending host returns to service.
1377.pp
1378To do this,
1379it is acceptable to move the entire queue directory:
1380.(b
1381cd /var/spool
1382mv mqueue omqueue; mkdir mqueue; chmod 0700 mqueue
1383.)b
1384You should then kill the existing daemon
1385(since it will still be processing in the old queue directory)
1386and create a new daemon.
1387.pp
1388To run the old mail queue, issue the following command:
1389.(b
1390/usr/\*(SD/sendmail \-C /etc/mail/queue.cf \-q
1391.)b
1392The
1393.b \-C
1394flag specifies an alternate configuration file
1395.b queue.cf
1396which should refer to the moved queue directory
1397.(b
1398O QueueDirectory=/var/spool/omqueue
1399.)b
1400and the
1401.b \-q
1402flag says to just run every job in the queue.
1403You can also specify the moved queue directory on the command line
1404.(b
1405/usr/\*(SD/sendmail \-oQ/var/spool/omqueue \-q
1406.)b
1407but this requires that you do not have
1408queue groups in the configuration file,
1409because those are not subdirectories of the moved directory.
1410See the section about ``Queue Group Declaration'' for details;
1411you most likely need a different configuration file to correctly deal
1412with this problem.
1413However, a proper configuration of queue groups should avoid
1414filling up queue directories, so you shouldn't run into
1415this problem.
1416If you have a tendency toward voyeurism,
1417you can use the
1418.b \-v
1419flag to watch what is going on.
1420.pp
1421When the queue is finally emptied,
1422you can remove the directory:
1423.(b
1424rmdir /var/spool/omqueue
1425.)b
1426.sh 3 "Quarantined Queue Items"
1427.pp
1428It is possible to "quarantine" mail messages,
1429otherwise known as envelopes.
1430Envelopes (queue files) are stored but not considered for delivery or
1431display unless the "quarantine" state of the envelope is undone or
1432delivery or display of quarantined items is requested.
1433Quarantined messages are tagged by using a different name for the queue
1434file, 'hf' instead of 'qf', and by adding the quarantine reason to the
1435queue file.
1436.pp
1437Delivery or display of quarantined items can be requested using the
1438.b \-qQ
1439flag to
1440.i sendmail
1441or
1442.i mailq .
1443Additionally, messages already in the queue can be quarantined or
1444unquarantined using the new
1445.b \-Q
1446flag to sendmail.
1447For example,
1448.(b
1449sendmail -Qreason -q[!][I|R|S][matchstring]
1450.)b
1451Quarantines the normal queue items matching the criteria specified by the
1452.b "-q[!][I|R|S][matchstring]"
1453using the reason given on the
1454.b \-Q
1455flag.
1456Likewise,
1457.(b
1458sendmail -qQ -Q[reason] -q[!][I|R|S|Q][matchstring]
1459.)b
1460Change the quarantine reason for the quarantined items matching the
1461criteria specified by the
1462.b "-q[!][I|R|S|Q][matchstring]"
1463using the reason given on the
1464.b \-Q
1465flag.
1466If there is no reason,
1467 unquarantine the matching items and make them normal queue items.
1468Note that the
1469.b \-qQ
1470flag tells sendmail to operate on quarantined items instead of normal items.
1471.sh 2 "Disk Based Connection Information"
1472.pp
1473.i Sendmail
1474stores a large amount of information about each remote system it
1475has connected to in memory. It is possible to preserve some
1476of this information on disk as well, by using the
1477.b HostStatusDirectory
1478option, so that it may be shared between several invocations of
1479.i sendmail .
1480This allows mail to be queued immediately or skipped during a queue run if
1481there has been a recent failure in connecting to a remote machine.
1482Note: information about a remote system is stored in a file
1483whose pathname consists of the components of the hostname in reverse order.
1484For example, the information for
1485.b host.example.com
1486is stored in
1487.b com./example./host .
1488For top-level domains like
1489.b com
1490this can create a large number of subdirectories
1491which on some filesystems can exhaust some limits.
1492Moreover, the performance of lookups in directory with thousands of entries
1493can be fairly slow depending on the filesystem implementation.
1494.pp
1495Additionally enabling
1496.b SingleThreadDelivery
1497has the added effect of single-threading mail delivery to a destination.
1498This can be quite helpful
1499if the remote machine is running an SMTP server that is easily overloaded
1500or cannot accept more than a single connection at a time,
1501but can cause some messages to be punted to a future queue run.
1502It also applies to
1503.i all
1504hosts, so setting this because you have one machine on site
1505that runs some software that is easily overrun
1506can cause mail to other hosts to be slowed down.
1507If this option is set,
1508you probably want to set the
1509.b MinQueueAge
1510option as well and run the queue fairly frequently;
1511this way jobs that are skipped because another
1512.i sendmail
1513is talking to the same host will be tried again quickly
1514rather than being delayed for a long time.
1515.pp
1516The disk based host information is stored in a subdirectory of the
1517.b mqueue
1518directory called
1519.b \&.hoststat \**.
1520.(f
1521\**This is the usual value of the
1522.b HostStatusDirectory
1523option;
1524it can, of course, go anywhere you like in your filesystem.
1525.)f
1526Removing this directory and its subdirectories has an effect similar to
1527the
1528.i purgestat
1529command and is completely safe.
1530However,
1531.i purgestat
1532only removes expired (Timeout.hoststatus) data.
1533The information in these directories can
1534be perused with the
1535.i hoststat
1536command, which will indicate the host name, the last access, and the
1537status of that access.
1538An asterisk in the left most column indicates that a
1539.i sendmail
1540process currently has the host locked for mail delivery.
1541.pp
1542The disk based connection information is treated the same way as memory based
1543connection information for the purpose of timeouts.
1544By default, information about host failures is valid for 30 minutes.
1545This can be adjusted with
1546the
1547.b Timeout.hoststatus
1548option.
1549.pp
1550The connection information stored on disk may be expired at any time
1551with the
1552.i purgestat
1553command or by invoking sendmail with the
1554.b \-bH
1555switch.
1556The connection information may be viewed with the
1557.i hoststat
1558command or by invoking sendmail with the
1559.b \-bh
1560switch.
1561.sh 2 "The Service Switch"
1562.pp
1563The implementation of certain system services
1564such as host and user name lookup
1565is controlled by the service switch.
1566If the host operating system supports such a switch,
1567and sendmail knows about it,
1568.i sendmail
1569will use the native version.
1570Ultrix, Solaris, and DEC OSF/1 are examples of such systems\**.
1571.(f
1572\**HP-UX 10 has service switch support,
1573but since the APIs are apparently not available in the libraries
1574.i sendmail
1575does not use the native service switch in this release.
1576.)f
1577.pp
1578If the underlying operating system does not support a service switch
1579(e.g., SunOS 4.X, HP-UX, BSD)
1580then
1581.i sendmail
1582will provide a stub implementation.
1583The
1584.b ServiceSwitchFile
1585option points to the name of a file that has the service definitions.
1586Each line has the name of a service
1587and the possible implementations of that service.
1588For example, the file:
1589.(b
1590hosts dns files nis
1591aliases files nis
1592.)b
1593will ask
1594.i sendmail
1595to look for hosts in the Domain Name System first.
1596If the requested host name is not found, it tries local files,
1597and if that fails it tries NIS.
1598Similarly, when looking for aliases
1599it will try the local files first followed by NIS.
1600.pp
1601Notice: since
1602.i sendmail
1603must access MX records for correct operation, it will use
1604DNS if it is configured in the
1605.b ServiceSwitchFile
1606file.
1607Hence an entry like
1608.(b
1609hosts files dns
1610.)b
1611will not avoid DNS lookups even if a host can be found
1612in /etc/hosts.
1613.pp
1614Service switches are not completely integrated.
1615For example, despite the fact that the host entry listed in the above example
1616specifies to look in NIS,
1617on SunOS this won't happen because the system implementation of
1618.i gethostbyname \|(3)
1619doesn't understand this.
1620.sh 2 "The Alias Database"
1621.pp
1622After recipient addresses are read from the SMTP connection
1623or command line
1624they are parsed by ruleset 0,
1625which must resolve to a
1626{\c
1627.i mailer ,
1628.i host ,
1629.i address }
1630triple.
1631If the flags selected by the
1632.i mailer
1633include the
1634.b A
1635(aliasable) flag,
1636the
1637.i address
1638part of the triple is looked up as the key
1639(i.e., the left hand side)
1640in the alias database.
1641If there is a match, the address is deleted from the send queue
1642and all addresses on the right hand side of the alias
1643are added in place of the alias that was found.
1644This is a recursive operation,
1645so aliases found in the right hand side of the alias
1646are similarly expanded.
1647.pp
1648The alias database exists in two forms.
1649One is a text form,
1650maintained in the file
1651.i /etc/mail/aliases.
1652The aliases are of the form
1653.(b
1654name: name1, name2, ...
1655.)b
1656Only local names may be aliased;
1657e.g.,
1658.(b
1659eric@prep.ai.MIT.EDU: eric@CS.Berkeley.EDU
1660.)b
1661will not have the desired effect
1662(except on prep.ai.MIT.EDU,
1663and they probably don't want me)\**.
1664.(f
1665\**Actually, any mailer that has the `A' mailer flag set
1666will permit aliasing;
1667this is normally limited to the local mailer.
1668.)f
1669Aliases may be continued by starting any continuation lines
1670with a space or a tab or by putting a backslash directly before
1671the newline.
1672Blank lines and lines beginning with a sharp sign
1673(\c
1674.q # )
1675are comments.
1676.pp
1677The second form is processed by the
1678.i ndbm \|(3)\**
1679.(f
1680\**The
1681.i gdbm
1682package does not work.
1683.)f
1684or the Berkeley DB library.
1685This form is in the file
1686.i /etc/mail/aliases.db
1687(if using NEWDB)
1688or
1689.i /etc/mail/aliases.dir
1690and
1691.i /etc/mail/aliases.pag
1692(if using NDBM).
1693This is the form that
1694.i sendmail
1695actually uses to resolve aliases.
1696This technique is used to improve performance.
1697.pp
1698The control of search order is actually set by the service switch.
1699Essentially, the entry
1700.(b
1701O AliasFile=switch:aliases
1702.)b
1703is always added as the first alias entry;
1704also, the first alias file name without a class
1705(e.g., without
1706.q nis:
1707on the front)
1708will be used as the name of the file for a ``files'' entry
1709in the aliases switch.
1710For example, if the configuration file contains
1711.(b
1712O AliasFile=/etc/mail/aliases
1713.)b
1714and the service switch contains
1715.(b
1716aliases nis files nisplus
1717.)b
1718then aliases will first be searched in the NIS database,
1719then in /etc/mail/aliases,
1720then in the NIS+ database.
1721.pp
1722You can also use
1723.sm NIS -based
1724alias files.
1725For example, the specification:
1726.(b
1727O AliasFile=/etc/mail/aliases
1728O AliasFile=nis:mail.aliases@my.nis.domain
1729.)b
1730will first search the /etc/mail/aliases file
1731and then the map named
1732.q mail.aliases
1733in
1734.q my.nis.domain .
1735Warning: if you build your own
1736.sm NIS -based
1737alias files,
1738be sure to provide the
1739.b \-l
1740flag to
1741.i makedbm (8)
1742to map upper case letters in the keys to lower case;
1743otherwise, aliases with upper case letters in their names
1744won't match incoming addresses.
1745.pp
1746Additional flags can be added after the colon
1747exactly like a
1748.b K
1749line \(em for example:
1750.(b
1751O AliasFile=nis:\-N mail.aliases@my.nis.domain
1752.)b
1753will search the appropriate NIS map and always include null bytes in the key.
1754Also:
1755.(b
1756O AliasFile=nis:\-f mail.aliases@my.nis.domain
1757.)b
1758will prevent sendmail from downcasing the key before the alias lookup.
1759.sh 3 "Rebuilding the alias database"
1760.pp
1761The
1762.i hash
1763or
1764.i dbm
1765version of the database
1766may be rebuilt explicitly by executing the command
1767.(b
1768newaliases
1769.)b
1770This is equivalent to giving
1771.i sendmail
1772the
1773.b \-bi
1774flag:
1775.(b
1776/usr/\*(SD/sendmail \-bi
1777.)b
1778.pp
1779If you have multiple aliases databases specified,
1780the
1781.b \-bi
1782flag rebuilds all the database types it understands
1783(for example, it can rebuild NDBM databases but not NIS databases).
1784.sh 3 "Potential problems"
1785.pp
1786There are a number of problems that can occur
1787with the alias database.
1788They all result from a
1789.i sendmail
1790process accessing the DBM version
1791while it is only partially built.
1792This can happen under two circumstances:
1793One process accesses the database
1794while another process is rebuilding it,
1795or the process rebuilding the database dies
1796(due to being killed or a system crash)
1797before completing the rebuild.
1798.pp
1799Sendmail has three techniques to try to relieve these problems.
1800First, it ignores interrupts while rebuilding the database;
1801this avoids the problem of someone aborting the process
1802leaving a partially rebuilt database.
1803Second,
1804it locks the database source file during the rebuild \(em
1805but that may not work over NFS or if the file is unwritable.
1806Third,
1807at the end of the rebuild
1808it adds an alias of the form
1809.(b
1810@: @
1811.)b
1812(which is not normally legal).
1813Before
1814.i sendmail
1815will access the database,
1816it checks to insure that this entry exists\**.
1817.(f
1818\**The
1819.b AliasWait
1820option is required in the configuration
1821for this action to occur.
1822This should normally be specified.
1823.)f
1824.sh 3 "List owners"
1825.pp
1826If an error occurs on sending to a certain address,
1827say
1828.q \fIx\fP ,
1829.i sendmail
1830will look for an alias
1831of the form
1832.q owner-\fIx\fP
1833to receive the errors.
1834This is typically useful
1835for a mailing list
1836where the submitter of the list
1837has no control over the maintenance of the list itself;
1838in this case the list maintainer would be the owner of the list.
1839For example:
1840.(b
1841unix-wizards: eric@ucbarpa, wnj@monet, nosuchuser,
1842 sam@matisse
1843owner-unix-wizards: unix-wizards-request
1844unix-wizards-request: eric@ucbarpa
1845.)b
1846would cause
1847.q eric@ucbarpa
1848to get the error that will occur
1849when someone sends to
1850unix-wizards
1851due to the inclusion of
1852.q nosuchuser
1853on the list.
1854.pp
1855List owners also cause the envelope sender address to be modified.
1856The contents of the owner alias are used if they point to a single user,
1857otherwise the name of the alias itself is used.
1858For this reason, and to obey Internet conventions,
1859the
1860.q owner-
1861address normally points at the
1862.q -request
1863address; this causes messages to go out with the typical Internet convention
1864of using ``\c
1865.i list -request''
1866as the return address.
1867.sh 2 "User Information Database"
1868.pp
1869This option is deprecated, use virtusertable and genericstable instead
1870as explained in
1871.i cf/README .
1872If you have a version of
1873.i sendmail
1874with the user information database
1875compiled in,
1876and you have specified one or more databases using the
1877.b U
1878option,
1879the databases will be searched for a
1880.i user :maildrop
1881entry.
1882If found, the mail will be sent to the specified address.
1883.sh 2 "Per-User Forwarding (.forward Files)"
1884.pp
1885As an alternative to the alias database,
1886any user may put a file with the name
1887.q .forward
1888in his or her home directory.
1889If this file exists,
1890.i sendmail
1891redirects mail for that user
1892to the list of addresses listed in the .forward file.
1893Note that aliases are fully expanded before forward files are referenced.
1894For example, if the home directory for user
1895.q mckusick
1896has a .forward file with contents:
1897.(b
1898mckusick@ernie
1899kirk@calder
1900.)b
1901then any mail arriving for
1902.q mckusick
1903will be redirected to the specified accounts.
1904.pp
1905Actually, the configuration file defines a sequence of filenames to check.
1906By default, this is the user's .forward file,
1907but can be defined to be more generally using the
1908.b ForwardPath
1909option.
1910If you change this,
1911you will have to inform your user base of the change;
1912\&.forward is pretty well incorporated into the collective subconscious.
1913.sh 2 "Special Header Lines"
1914.pp
1915Several header lines have special interpretations
1916defined by the configuration file.
1917Others have interpretations built into
1918.i sendmail
1919that cannot be changed without changing the code.
1920These built-ins are described here.
1921.sh 3 "Errors-To:"
1922.pp
1923If errors occur anywhere during processing,
1924this header will cause error messages to go to
1925the listed addresses.
1926This is intended for mailing lists.
1927.pp
1928The Errors-To: header was created in the bad old days
1929when UUCP didn't understand the distinction between an envelope and a header;
1930this was a hack to provide what should now be passed
1931as the envelope sender address.
1932It should go away.
1933It is only used if the
1934.b UseErrorsTo
1935option is set.
1936.pp
1937The Errors-To: header is officially deprecated
1938and will go away in a future release.
1939.sh 3 "Apparently-To:"
1940.pp
1941RFC 822 requires at least one recipient field
1942(To:, Cc:, or Bcc: line)
1943in every message.
1944If a message comes in with no recipients listed in the message
1945then
1946.i sendmail
1947will adjust the header based on the
1948.q NoRecipientAction
1949option.
1950One of the possible actions is to add an
1951.q "Apparently-To:"
1952header line for any recipients it is aware of.
1953.pp
1954The Apparently-To: header is non-standard
1955and is both deprecated and strongly discouraged.
1956.sh 3 "Precedence"
1957.pp
1958The Precedence: header can be used as a crude control of message priority.
1959It tweaks the sort order in the queue
1960and can be configured to change the message timeout values.
1961The precedence of a message also controls how
1962delivery status notifications (DSNs)
1963are processed for that message.
1964.sh 2 "IDENT Protocol Support"
1965.pp
1966.i Sendmail
1967supports the IDENT protocol as defined in RFC 1413.
1968Note that the RFC states
1969a client should wait at least 30 seconds for a response.
1970The default Timeout.ident is 5 seconds
1971as many sites have adopted the practice of dropping IDENT queries.
1972This has lead to delays processing mail.
1973Although this enhances identification
1974of the author of an email message
1975by doing a ``call back'' to the originating system to include
1976the owner of a particular TCP connection
1977in the audit trail
1978it is in no sense perfect;
1979a determined forger can easily spoof the IDENT protocol.
1980The following description is excerpted from RFC 1413:
1981.ba +5
1982.lp
19836. Security Considerations
1984.lp
1985The information returned by this protocol is at most as trustworthy
1986as the host providing it OR the organization operating the host. For
1987example, a PC in an open lab has few if any controls on it to prevent
1988a user from having this protocol return any identifier the user
1989wants. Likewise, if the host has been compromised the information
1990returned may be completely erroneous and misleading.
1991.lp
1992The Identification Protocol is not intended as an authorization or
1993access control protocol. At best, it provides some additional
1994auditing information with respect to TCP connections. At worst, it
1995can provide misleading, incorrect, or maliciously incorrect
1996information.
1997.lp
1998The use of the information returned by this protocol for other than
1999auditing is strongly discouraged. Specifically, using Identification
2000Protocol information to make access control decisions - either as the
2001primary method (i.e., no other checks) or as an adjunct to other
2002methods may result in a weakening of normal host security.
2003.lp
2004An Identification server may reveal information about users,
2005entities, objects or processes which might normally be considered
2006private. An Identification server provides service which is a rough
2007analog of the CallerID services provided by some phone companies and
2008many of the same privacy considerations and arguments that apply to
2009the CallerID service apply to Identification. If you wouldn't run a
2010"finger" server due to privacy considerations you may not want to run
2011this protocol.
2012.ba
2013.lp
2014In some cases your system may not work properly with IDENT support
2015due to a bug in the TCP/IP implementation.
2016The symptoms will be that for some hosts
2017the SMTP connection will be closed
2018almost immediately.
2019If this is true or if you do not want to use IDENT,
2020you should set the IDENT timeout to zero;
2021this will disable the IDENT protocol.
2022.sh 1 "ARGUMENTS"
2023.pp
2024The complete list of arguments to
2025.i sendmail
2026is described in detail in Appendix A.
2027Some important arguments are described here.
2028.sh 2 "Queue Interval"
2029.pp
2030The amount of time between forking a process
2031to run through the queue is defined by the
2032.b \-q
2033flag.
2034If you run with delivery mode set to
2035.b i
2036or
2037.b b
2038this can be relatively large, since it will only be relevant
2039when a host that was down comes back up.
2040If you run in
2041.b q
2042mode it should be relatively short,
2043since it defines the maximum amount of time that a message
2044may sit in the queue.
2045(See also the MinQueueAge option.)
2046.pp
2047RFC 1123 section 5.3.1.1 says that this value should be at least 30 minutes
2048(although that probably doesn't make sense if you use ``queue-only'' mode).
2049.pp
2050Notice: the meaning of the interval time depends on whether normal
2051queue runners or persistent queue runners are used.
2052For the former, it is the time between subsequent starts of a queue run.
2053For the latter, it is the time sendmail waits after a persistent queue
2054runner has finished its work to start the next one.
2055Hence for persistent queue runners this interval should be very low,
2056typically no more than two minutes.
2057.sh 2 "Daemon Mode"
2058.pp
2059If you allow incoming mail over an IPC connection,
2060you should have a daemon running.
2061This should be set by your
2062.i /etc/rc
2063file using the
2064.b \-bd
2065flag.
2066The
2067.b \-bd
2068flag and the
2069.b \-q
2070flag may be combined in one call:
2071.(b
2072/usr/\*(SD/sendmail \-bd \-q30m
2073.)b
2074.pp
2075An alternative approach is to invoke sendmail from
2076.i inetd (8)
2077(use the
2078.b \-bs \ \-Am
2079flags to ask sendmail to speak SMTP on its standard input and output
2080and to run as MTA).
2081This works and allows you to wrap
2082.i sendmail
2083in a TCP wrapper program,
2084but may be a bit slower since the configuration file
2085has to be re-read on every message that comes in.
2086If you do this, you still need to have a
2087.i sendmail
2088running to flush the queue:
2089.(b
2090/usr/\*(SD/sendmail \-q30m
2091.)b
2092.sh 2 "Forcing the Queue"
2093.pp
2094In some cases you may find that the queue has gotten clogged for some reason.
2095You can force a queue run
2096using the
2097.b \-q
2098flag (with no value).
2099It is entertaining to use the
2100.b \-v
2101flag (verbose)
2102when this is done to watch what happens:
2103.(b
2104/usr/\*(SD/sendmail \-q \-v
2105.)b
2106.pp
2107You can also limit the jobs to those with a particular queue identifier,
2108recipient, sender, quarantine reason, or queue group
2109using one of the queue modifiers.
2110For example,
2111.q \-qRberkeley
2112restricts the queue run to jobs that have the string
2113.q berkeley
2114somewhere in one of the recipient addresses.
2115Similarly,
2116.q \-qSstring
2117limits the run to particular senders,
2118.q \-qIstring
2119limits it to particular queue identifiers, and
2120.q \-qQstring
2121limits it to particular quarantined reasons and only operated on
2122quarantined queue items, and
2123.q \-qGstring
2124limits it to a particular queue group.
2125The named queue group will be run even if it is set to have 0 runners.
2126You may also place an
2127.b !
2128before the
2129.b I
2130or
2131.b R
2132or
2133.b S
2134or
2135.b Q
2136to indicate that jobs are limited to not including a particular queue
2137identifier, recipient or sender.
2138For example,
2139.q \-q!Rseattle
2140limits the queue run to jobs that do not have the string
2141.q seattle
2142somewhere in one of the recipient addresses.
2143Should you need to terminate the queue jobs currently active then a SIGTERM
2144to the parent of the process (or processes) will cleanly stop the jobs.
2145.sh 2 "Debugging"
2146.pp
2147There are a fairly large number of debug flags
2148built into
2149.i sendmail .
2150Each debug flag has a category and a level.
2151Higher levels increase the level of debugging activity;
2152in most cases, this means to print out more information.
2153The convention is that levels greater than nine are
2154.q absurd,
2155i.e.,
2156they print out so much information that you wouldn't normally
2157want to see them except for debugging that particular piece of code.
2158.pp
2159You should
2160.b never
2161run a production sendmail server in debug mode.
2162Many of the debug flags will result in debug output being sent over the
2163SMTP channel unless the option
2164.b \-D
2165is used.
2166This will confuse many mail programs.
2167However, for testing purposes, it can be useful
2168when sending mail manually via
2169telnet to the port you are using while debugging.
2170.pp
2171A debug category is either an integer, like 42,
2172or a name, like ANSI.
2173You can specify a range of numeric debug categories
2174using the syntax 17-42.
2175You can specify a set of named debug categories using
2176a glob pattern like
2177.q sm_trace_* .
2178At present, only
2179.q *
2180and
2181.q ?
2182are supported in these glob patterns.
2183.pp
2184Debug flags are set using the
2185.b \-d
2186option;
2187the syntax is:
2188.(b
2189.ta \w'debug-categories:M 'u
2190debug-flag: \fB\-d\fP debug-list
2191debug-list: debug-option [ , debug-option ]*
2192debug-option: debug-categories [ . debug-level ]
2193debug-categories: integer | integer \- integer | category-pattern
2194category-pattern: [a-zA-Z_*?][a-zA-Z0-9_*?]*
2195debug-level: integer
2196.)b
2197where spaces are for reading ease only.
2198For example,
2199.(b
2200\-d12 Set category 12 to level 1
2201\-d12.3 Set category 12 to level 3
2202\-d3\-17 Set categories 3 through 17 to level 1
2203\-d3\-17.4 Set categories 3 through 17 to level 4
2204\-dANSI Set category ANSI to level 1
2205\-dsm_trace_*.3 Set all named categories matching sm_trace_* to level 3
2206.)b
2207For a complete list of the available debug flags
2208you will have to look at the code
2209and the
2210.i TRACEFLAGS
2211file in the sendmail distribution
2212(they are too dynamic to keep this document up to date).
2213For a list of named debug categories in the sendmail binary, use
2214.(b
2215ident /usr/sbin/sendmail | grep Debug
2216.)b
2217.sh 2 "Changing the Values of Options"
2218.pp
2219Options can be overridden using the
2220.b \-o
2221or
2222.b \-O
2223command line flags.
2224For example,
2225.(b
2226/usr/\*(SD/sendmail \-oT2m
2227.)b
2228sets the
2229.b T
2230(timeout) option to two minutes
2231for this run only;
2232the equivalent line using the long option name is
2233.(b
2234/usr/\*(SD/sendmail -OTimeout.queuereturn=2m
2235.)b
2236.pp
2237Some options have security implications.
2238Sendmail allows you to set these,
2239but relinquishes its set-user-ID or set-group-ID permissions thereafter\**.
2240.(f
2241\**That is, it sets its effective uid to the real uid;
2242thus, if you are executing as root,
2243as from root's crontab file or during system startup
2244the root permissions will still be honored.
2245.)f
2246.sh 2 "Trying a Different Configuration File"
2247.pp
2248An alternative configuration file
2249can be specified using the
2250.b \-C
2251flag; for example,
2252.(b
2253/usr/\*(SD/sendmail \-Ctest.cf \-oQ/tmp/mqueue
2254.)b
2255uses the configuration file
2256.i test.cf
2257instead of the default
2258.i /etc/mail/sendmail.cf.
2259If the
2260.b \-C
2261flag has no value
2262it defaults to
2263.i sendmail.cf
2264in the current directory.
2265.pp
2266.i Sendmail
2267gives up set-user-ID root permissions
2268(if it has been installed set-user-ID root)
2269when you use this flag, so it is common to use a publicly writable directory
2270(such as /tmp)
2271as the queue directory (QueueDirectory or Q option) while testing.
2272.sh 2 "Logging Traffic"
2273.pp
2274Many SMTP implementations do not fully implement the protocol.
2275For example, some personal computer based SMTPs
2276do not understand continuation lines in reply codes.
2277These can be very hard to trace.
2278If you suspect such a problem, you can set traffic logging using the
2279.b \-X
2280flag.
2281For example,
2282.(b
2283/usr/\*(SD/sendmail \-X /tmp/traffic \-bd
2284.)b
2285will log all traffic in the file
2286.i /tmp/traffic .
2287.pp
2288This logs a lot of data very quickly and should
2289.b NEVER
2290be used
2291during normal operations.
2292After starting up such a daemon,
2293force the errant implementation to send a message to your host.
2294All message traffic in and out of
2295.i sendmail ,
2296including the incoming SMTP traffic,
2297will be logged in this file.
2298.sh 2 "Testing Configuration Files"
2299.pp
2300When you build a configuration table,
2301you can do a certain amount of testing
2302using the
2303.q "test mode"
2304of
2305.i sendmail .
2306For example,
2307you could invoke
2308.i sendmail
2309as:
2310.(b
2311sendmail \-bt \-Ctest.cf
2312.)b
2313which would read the configuration file
2314.q test.cf
2315and enter test mode.
2316In this mode,
2317you enter lines of the form:
2318.(b
2319rwset address
2320.)b
2321where
2322.i rwset
2323is the rewriting set you want to use
2324and
2325.i address
2326is an address to apply the set to.
2327Test mode shows you the steps it takes
2328as it proceeds,
2329finally showing you the address it ends up with.
2330You may use a comma separated list of rwsets
2331for sequential application of rules to an input.
2332For example:
2333.(b
23343,1,21,4 monet:bollard
2335.)b
2336first applies ruleset three to the input
2337.q monet:bollard.
2338Ruleset one is then applied to the output of ruleset three,
2339followed similarly by rulesets twenty-one and four.
2340.pp
2341If you need more detail,
2342you can also use the
2343.q \-d21
2344flag to turn on more debugging.
2345For example,
2346.(b
2347sendmail \-bt \-d21.99
2348.)b
2349turns on an incredible amount of information;
2350a single word address
2351is probably going to print out several pages worth of information.
2352.pp
2353You should be warned that internally,
2354.i sendmail
2355applies ruleset 3 to all addresses.
2356In test mode
2357you will have to do that manually.
2358For example, older versions allowed you to use
2359.(b
23600 bruce@broadcast.sony.com
2361.)b
2362This version requires that you use:
2363.(b
23643,0 bruce@broadcast.sony.com
2365.)b
2366.pp
2367As of version 8.7,
2368some other syntaxes are available in test mode:
2369.nr ii 1i
2370.ip \&.D\|x\|value
2371defines macro
2372.i x
2373to have the indicated
2374.i value .
2375This is useful when debugging rules that use the
2376.b $& \c
2377.i x
2378syntax.
2379.ip \&.C\|c\|value
2380adds the indicated
2381.i value
2382to class
2383.i c .
2384.ip \&=S\|ruleset
2385dumps the contents of the indicated ruleset.
2386.ip \-d\|debug-spec
2387is equivalent to the command-line flag.
2388.lp
2389Version 8.9 introduced more features:
2390.nr ii 1i
2391.ip ?
2392shows a help message.
2393.ip =M
2394display the known mailers.
2395.ip $m
2396print the value of macro m.
2397.ip $=c
2398print the contents of class c.
2399.ip /mx\ host
2400returns the MX records for `host'.
2401.ip /parse\ address
2402parse address, returning the value of
2403.i crackaddr ,
2404and the parsed address.
2405.ip /try\ mailer\ addr
2406rewrite address into the form it will have when
2407presented to the indicated mailer.
2408.ip /tryflags\ flags
2409set flags used by parsing. The flags can be `H' for
2410Header or `E' for Envelope, and `S' for Sender or `R'
2411for Recipient. These can be combined, `HR' sets
2412flags for header recipients.
2413.ip /canon\ hostname
2414try to canonify hostname.
2415.ip /map\ mapname\ key
2416look up `key' in the indicated `mapname'.
2417.ip /quit
2418quit address test mode.
2419.lp
2420.sh 2 "Persistent Host Status Information"
2421.pp
2422When
2423.b HostStatusDirectory
2424is enabled,
2425information about the status of hosts is maintained on disk
2426and can thus be shared between different instantiations of
2427.i sendmail .
2428The status of the last connection with each remote host
2429may be viewed with the command:
2430.(b
2431sendmail \-bh
2432.)b
2433This information may be flushed with the command:
2434.(b
2435sendmail \-bH
2436.)b
2437Flushing the information prevents new
2438.i sendmail
2439processes from loading it,
2440but does not prevent existing processes from using the status information
2441that they already have.
2442.sh 1 "TUNING"
2443.pp
2444There are a number of configuration parameters
2445you may want to change,
2446depending on the requirements of your site.
2447Most of these are set
2448using an option in the configuration file.
2449For example,
2450the line
2451.q "O Timeout.queuereturn=5d"
2452sets option
2453.q Timeout.queuereturn
2454to the value
2455.q 5d
2456(five days).
2457.pp
2458Most of these options have appropriate defaults for most sites.
2459However,
2460sites having very high mail loads may find they need to tune them
2461as appropriate for their mail load.
2462In particular,
2463sites experiencing a large number of small messages,
2464many of which are delivered to many recipients,
2465may find that they need to adjust the parameters
2466dealing with queue priorities.
2467.pp
2468All versions of
2469.i sendmail
2470prior to 8.7
2471had single character option names.
2472As of 8.7,
2473options have long (multi-character names).
2474Although old short names are still accepted,
2475most new options do not have short equivalents.
2476.pp
2477This section only describes the options you are most likely
2478to want to tweak;
2479read section
2480.\"XREF
24815
2482for more details.
2483.sh 2 "Timeouts"
2484.pp
2485All time intervals are set
2486using a scaled syntax.
2487For example,
2488.q 10m
2489represents ten minutes, whereas
2490.q 2h30m
2491represents two and a half hours.
2492The full set of scales is:
2493.(b
2494.ta 4n
2495s seconds
2496m minutes
2497h hours
2498d days
2499w weeks
2500.)b
2501.sh 3 "Queue interval"
2502.pp
2503The argument to the
2504.b \-q
2505flag specifies how often a sub-daemon will run the queue.
2506This is typically set to between fifteen minutes and one hour.
2507If not set, or set to zero,
2508the queue will not be run automatically.
2509RFC 1123 section 5.3.1.1 recommends that this be at least 30 minutes.
2510Should you need to terminate the queue jobs currently active then a SIGTERM
2511to the parent of the process (or processes) will cleanly stop the jobs.
2512.sh 3 "Read timeouts"
2513.pp
2514Timeouts all have option names
2515.q Timeout.\fIsuboption\fP .
2516Most of these control SMTP operations.
2517The recognized
2518.i suboption s,
2519their default values, and the minimum values
2520allowed by RFC 2821 section 4.5.3.2 (or RFC 1123 section 5.3.2) are:
2521.nr ii 1i
2522.ip connect
2523The time to wait for an SMTP connection to open
2524(the
2525.i connect (2)
2526system call)
2527[0, unspecified].
2528If zero, uses the kernel default.
2529In no case can this option extend the timeout
2530longer than the kernel provides, but it can shorten it.
2531This is to get around kernels that provide an absurdly long connection timeout
2532(90 minutes in one case).
2533.ip iconnect
2534The same as
2535.i connect,
2536except it applies only to the initial attempt to connect to a host
2537for a given message
2538[0, unspecified].
2539The concept is that this should be very short (a few seconds);
2540hosts that are well connected and responsive will thus be serviced immediately.
2541Hosts that are slow will not hold up other deliveries in the initial
2542delivery attempt.
2543.ip aconnect
2544[0, unspecified]
2545The overall timeout waiting for all connection for a single delivery
2546attempt to succeed.
2547If 0, no overall limit is applied.
2548This can be used to restrict the total amount of time trying to connect to
2549a long list of host that could accept an e-mail for the recipient.
2550This timeout does not apply to
2551.b FallbackMXhost ,
2552i.e., if the time is exhausted, the
2553.b FallbackMXhost
2554is tried next.
2555.ip initial
2556The wait for the initial 220 greeting message
2557[5m, 5m].
2558.ip helo
2559The wait for a reply from a HELO or EHLO command
2560[5m, unspecified].
2561This may require a host name lookup, so
2562five minutes is probably a reasonable minimum.
2563.ip mail\(dg
2564The wait for a reply from a MAIL command
2565[10m, 5m].
2566.ip rcpt\(dg
2567The wait for a reply from a RCPT command
2568[1h, 5m].
2569This should be long
2570because it could be pointing at a list
2571that takes a long time to expand
2572(see below).
2573.ip datainit\(dg
2574The wait for a reply from a DATA command
2575[5m, 2m].
2576.ip datablock\(dg\(dd
2577The wait for reading a data block
2578(that is, the body of the message).
2579[1h, 3m].
2580This should be long because it also applies to programs
2581piping input to
2582.i sendmail
2583which have no guarantee of promptness.
2584.ip datafinal\(dg
2585The wait for a reply from the dot terminating a message.
2586[1h, 10m].
2587If this is shorter than the time actually needed
2588for the receiver to deliver the message,
2589duplicates will be generated.
2590This is discussed in RFC 1047.
2591.ip rset
2592The wait for a reply from a RSET command
2593[5m, unspecified].
2594.ip quit
2595The wait for a reply from a QUIT command
2596[2m, unspecified].
2597.ip misc
2598The wait for a reply from miscellaneous (but short) commands
2599such as NOOP (no-operation) and VERB (go into verbose mode).
2600[2m, unspecified].
2601.ip command\(dg\(dd
2602In server SMTP,
2603the time to wait for another command.
2604[1h, 5m].
2605.ip ident\(dd
2606The timeout waiting for a reply to an IDENT query
2607[5s\**, unspecified].
2608.(f
2609\**On some systems the default is zero to turn the protocol off entirely.
2610.)f
2611.ip lhlo
2612The wait for a reply to an LMTP LHLO command
2613[2m, unspecified].
2614.ip auth
2615The timeout for a reply in an SMTP AUTH dialogue
2616[10m, unspecified].
2617.ip starttls
2618The timeout for a reply to an SMTP STARTTLS command and the TLS handshake
2619[1h, unspecified].
2620.ip fileopen\(dd
2621The timeout for opening .forward and :include: files [60s, none].
2622.ip control\(dd
2623The timeout for a complete control socket transaction to complete [2m, none].
2624.ip hoststatus\(dd
2625How long status information about a host
2626(e.g., host down)
2627will be cached before it is considered stale
2628[30m, unspecified].
2629.ip resolver.retrans\(dd
2630The resolver's
2631retransmission time interval
2632(in seconds)
2633[varies].
2634Sets both
2635.i Timeout.resolver.retrans.first
2636and
2637.i Timeout.resolver.retrans.normal .
2638.ip resolver.retrans.first\(dd
2639The resolver's
2640retransmission time interval
2641(in seconds)
2642for the first attempt to
2643deliver a message
2644[varies].
2645.ip resolver.retrans.normal\(dd
2646The resolver's
2647retransmission time interval
2648(in seconds)
2649for all resolver lookups
2650except the first delivery attempt
2651[varies].
2652.ip resolver.retry\(dd
2653The number of times
2654to retransmit a resolver query.
2655Sets both
2656.i Timeout.resolver.retry.first
2657and
2658.i Timeout.resolver.retry.normal
2659[varies].
2660.ip resolver.retry.first\(dd
2661The number of times
2662to retransmit a resolver query
2663for the first attempt
2664to deliver a message
2665[varies].
2666.ip resolver.retry.normal\(dd
2667The number of times
2668to retransmit a resolver query
2669for all resolver lookups
2670 except the first delivery attempt
2671[varies].
2672.lp
2673For compatibility with old configuration files,
2674if no
2675.i suboption
2676is specified,
2677all the timeouts marked with
2678.DG
2679(\(dg) are set to the indicated value.
2680All but those marked with
2681.DD
2682(\(dd) apply to client SMTP.
2683.pp
2684For example, the lines:
2685.(b
2686O Timeout.command=25m
2687O Timeout.datablock=3h
2688.)b
2689sets the server SMTP command timeout to 25 minutes
2690and the input data block timeout to three hours.
2691.sh 3 "Message timeouts"
2692.pp
2693After sitting in the queue for a few days,
2694an undeliverable message will time out.
2695This is to insure that at least the sender is aware
2696of the inability to send a message.
2697The timeout is typically set to five days.
2698It is sometimes considered convenient to also send a warning message
2699if the message is in the queue longer than a few hours
2700(assuming you normally have good connectivity;
2701if your messages normally took several hours to send
2702you wouldn't want to do this because it wouldn't be an unusual event).
2703These timeouts are set using the
2704.b Timeout.queuereturn
2705and
2706.b Timeout.queuewarn
2707options in the configuration file
2708(previously both were set using the
2709.b T
2710option).
2711.pp
2712If the message is submitted using the
2713.sm NOTIFY
2714.sm SMTP
2715extension,
2716warning messages will only be sent if
2717.sm NOTIFY=DELAY
2718is specified.
2719The queuereturn and queuewarn timeouts
2720can be further qualified with a tag based on the Precedence: field
2721in the message;
2722they must be one of
2723.q urgent
2724(indicating a positive non-zero precedence),
2725.q normal
2726(indicating a zero precedence), or
2727.q non-urgent
2728(indicating negative precedences).
2729For example, setting
2730.q Timeout.queuewarn.urgent=1h
2731sets the warning timeout for urgent messages only
2732to one hour.
2733The default if no precedence is indicated
2734is to set the timeout for all precedences.
2735If the message has a normal (default) precedence
2736and it is a delivery status notification (DSN),
2737.b Timeout.queuereturn.dsn
2738and
2739.b Timeout.queuewarn.dsn
2740can be used to give an alternative warn and return time
2741for DSNs.
2742The value "now" can be used for
2743-O Timeout.queuereturn
2744to return entries immediately during a queue run,
2745e.g., to bounce messages independent of their time in the queue.
2746.pp
2747Since these options are global,
2748and since you cannot know
2749.i "a priori"
2750how long another host outside your domain will be down,
2751a five day timeout is recommended.
2752This allows a recipient to fix the problem even if it occurs
2753at the beginning of a long weekend.
2754RFC 1123 section 5.3.1.1 says that this parameter
2755should be ``at least 4\-5 days''.
2756.pp
2757The
2758.b Timeout.queuewarn
2759value can be piggybacked on the
2760.b T
2761option by indicating a time after which
2762a warning message should be sent;
2763the two timeouts are separated by a slash.
2764For example, the line
2765.(b
2766OT5d/4h
2767.)b
2768causes email to fail after five days,
2769but a warning message will be sent after four hours.
2770This should be large enough that the message will have been tried
2771several times.
2772.sh 2 "Forking During Queue Runs"
2773.pp
2774By setting the
2775.b ForkEachJob
2776(\c
2777.b Y )
2778option,
2779.i sendmail
2780will fork before each individual message
2781while running the queue.
2782This option was used with earlier releases to prevent
2783.i sendmail
2784from consuming large amounts of memory.
2785It should no longer be necessary with
2786.i sendmail
27878.12.
2788If the
2789.b ForkEachJob
2790option is not set,
2791.i sendmail
2792will keep track of hosts that are down during a queue run,
2793which can improve performance dramatically.
2794.pp
2795If the
2796.b ForkEachJob
2797option is set,
2798.i sendmail
2799cannot use connection caching.
2800.sh 2 "Queue Priorities"
2801.pp
2802Every message is assigned a priority when it is first instantiated,
2803consisting of the message size (in bytes)
2804offset by the message class
2805(which is determined from the Precedence: header)
2806times the
2807.q "work class factor"
2808and the number of recipients times the
2809.q "work recipient factor."
2810The priority is used to order the queue.
2811Higher numbers for the priority mean that the message will be processed later
2812when running the queue.
2813.pp
2814The message size is included so that large messages are penalized
2815relative to small messages.
2816The message class allows users to send
2817.q "high priority"
2818messages by including a
2819.q Precedence:
2820field in their message;
2821the value of this field is looked up in the
2822.b P
2823lines of the configuration file.
2824Since the number of recipients affects the amount of load a message presents
2825to the system,
2826this is also included into the priority.
2827.pp
2828The recipient and class factors
2829can be set in the configuration file using the
2830.b RecipientFactor
2831(\c
2832.b y )
2833and
2834.b ClassFactor
2835(\c
2836.b z )
2837options respectively.
2838They default to 30000 (for the recipient factor)
2839and 1800
2840(for the class factor).
2841The initial priority is:
2842.EQ
2843pri = msgsize - (class times bold ClassFactor) + (nrcpt times bold RecipientFactor)
2844.EN
2845(Remember, higher values for this parameter actually mean
2846that the job will be treated with lower priority.)
2847.pp
2848The priority of a job can also be adjusted each time it is processed
2849(that is, each time an attempt is made to deliver it)
2850using the
2851.q "work time factor,"
2852set by the
2853.b RetryFactor
2854(\c
2855.b Z )
2856option.
2857This is added to the priority,
2858so it normally decreases the precedence of the job,
2859on the grounds that jobs that have failed many times
2860will tend to fail again in the future.
2861The
2862.b RetryFactor
2863option defaults to 90000.
2864.sh 2 "Load Limiting"
2865.pp
2866.i Sendmail
2867can be asked to queue (but not deliver) mail
2868if the system load average gets too high using the
2869.b QueueLA
2870(\c
2871.b x )
2872option.
2873When the load average exceeds the value of the
2874.b QueueLA
2875option, the delivery mode is set to
2876.b q
2877(queue only) if the
2878.b QueueFactor
2879(\c
2880.b q )
2881option divided by the difference in the current load average and the
2882.b QueueLA
2883option plus one
2884is less than the priority of the message \(em
2885that is, the message is queued iff:
2886.EQ
2887pri > { bold QueueFactor } over { LA - { bold QueueLA } + 1 }
2888.EN
2889The
2890.b QueueFactor
2891option defaults to 600000,
2892so each point of load average is worth 600000 priority points
2893(as described above).
2894.pp
2895For drastic cases, the
2896.b RefuseLA
2897(\c
2898.b X )
2899option defines a load average at which
2900.i sendmail
2901will refuse to accept network connections.
2902Locally generated mail, i.e., mail which is not submitted via SMTP
2903(including incoming UUCP mail),
2904is still accepted.
2905Notice that the MSP submits mail to the MTA via SMTP, and hence
2906mail will be queued in the client queue in such a case.
2907Therefore it is necessary to run the client mail queue periodically.
2908.sh 2 "Resource Limits"
2909.pp
2910.i Sendmail
2911has several parameters to control resource usage.
2912Besides those mentionted in the previous section, there are at least
2913.b MaxDaemonChildren ,
2914.b ConnectionRateThrottle ,
2915.b MaxQueueChildren ,
2916and
2917.b MaxRunnersPerQueue .
2918The latter two limit the number of
2919.i sendmail
2920processes that operate on the queue.
2921These are discussed in the section
2922``Queue Group Declaration''.
2923The former two can be used to limit the number of incoming connections.
2924Their appropriate values depend on the host operating system and
2925the hardware, e.g., amount of memory.
2926In many situations it might be useful to set limits to prevent
2927to have too many
2928.i sendmail
2929processes, however, these limits can be abused to mount a
2930denial of service attack.
2931For example, if
2932.b MaxDaemonChildren=10
2933then an attacker needs to open only 10 SMTP sessions to the server,
2934leave them idle for most of the time,
2935and no more connections will be accepted.
2936If this option is set then the timeouts used in a SMTP session
2937should be lowered from their default values to
2938their minimum values as specified in RFC 2821 and listed in
2939section
2940.\"XREF
29414.1.2.
2942.sh 2 "Measures against Denial of Service Attacks"
2943.pp
2944.i Sendmail
2945has some built-in measures against simple denial of service (DoS) attacks.
2946The SMTP server by default slows down if too many bad commands are
2947issued or if some commands are repeated too often within a session.
2948Details can be found in the source file
2949.b sendmail/srvrsmtp.c
2950by looking for the macro definitions of
2951.b MAXBADCOMMANDS ,
2952.b MAXNOOPCOMMANDS ,
2953.b MAXHELOCOMMANDS ,
2954.b MAXVRFYCOMMANDS ,
2955and
2956.b MAXETRNCOMMANDS .
2957If an SMTP command is issued more often than the corresponding
2958.b MAXcmdCOMMANDS
2959value, then the response is delayed exponentially,
2960starting with a sleep time of one second,
2961up to a maximum of four minutes (as defined by
2962.b MAXTIMEOUT ).
2963If the option
2964.b MaxDaemonChildren
2965is set to a value greater than zero,
2966then this could make a DoS attack even worse since it
2967keeps a connection open longer than necessary.
2968Therefore a connection is terminated with a 421 SMTP reply code
2969if the number of commands exceeds the limit by a factor of two and
2970.b MAXBADCOMMANDS
2971is set to a value greater than zero (the default is 25).
2972.sh 2 "Delivery Mode"
2973.pp
2974There are a number of delivery modes that
2975.i sendmail
2976can operate in,
2977set by the
2978.b DeliveryMode
2979(\c
2980.b d )
2981configuration option.
2982These modes
2983specify how quickly mail will be delivered.
2984Legal modes are:
2985.(b
2986.ta 4n
2987i deliver interactively (synchronously)
2988b deliver in background (asynchronously)
2989q queue only (don't deliver)
2990d defer delivery attempts (don't deliver)
2991.)b
2992There are tradeoffs.
2993Mode
2994.q i
2995gives the sender the quickest feedback,
2996but may slow down some mailers and
2997is hardly ever necessary.
2998Mode
2999.q b
3000delivers promptly but
3001can cause large numbers of processes
3002if you have a mailer that takes a long time to deliver a message.
3003Mode
3004.q q
3005minimizes the load on your machine,
3006but means that delivery may be delayed for up to the queue interval.
3007Mode
3008.q d
3009is identical to mode
3010.q q
3011except that it also prevents lookups in maps including the
3012.b -D
3013flag from working during the initial queue phase;
3014it is intended for ``dial on demand'' sites where DNS lookups
3015might cost real money.
3016Some simple error messages
3017(e.g., host unknown during the SMTP protocol)
3018will be delayed using this mode.
3019Mode
3020.q b
3021is the usual default.
3022.pp
3023If you run in mode
3024.q q
3025(queue only),
3026.q d
3027(defer),
3028or
3029.q b
3030(deliver in background)
3031.i sendmail
3032will not expand aliases and follow .forward files
3033upon initial receipt of the mail.
3034This speeds up the response to RCPT commands.
3035Mode
3036.q i
3037should not be used by the SMTP server.
3038.sh 2 "Log Level"
3039.pp
3040The level of logging can be set for
3041.i sendmail .
3042The default using a standard configuration table is level 9.
3043The levels are as follows:
3044.nr ii 0.5i
3045.ip 0
3046Minimal logging.
3047.ip 1
3048Serious system failures and potential security problems.
3049.ip 2
3050Lost communications (network problems) and protocol failures.
3051.ip 3
3052Other serious failures, malformed addresses, transient forward/include
3053errors, connection timeouts.
3054.ip 4
3055Minor failures, out of date alias databases, connection rejections
3056via check_ rulesets.
3057.ip 5
3058Message collection statistics.
3059.ip 6
3060Creation of error messages,
3061VRFY and EXPN commands.
3062.ip 7
3063Delivery failures (host or user unknown, etc.).
3064.ip 8
3065Successful deliveries and alias database rebuilds.
3066.ip 9
3067Messages being deferred
3068(due to a host being down, etc.).
3069.ip 10
3070Database expansion (alias, forward, and userdb lookups)
3071and authentication information.
3072.ip 11
3073NIS errors and end of job processing.
3074.ip 12
3075Logs all SMTP connections.
3076.ip 13
3077Log bad user shells, files with improper permissions, and other
3078questionable situations.
3079.ip 14
3080Logs refused connections.
3081.ip 15
3082Log all incoming and outgoing SMTP commands.
3083.ip 20
3084Logs attempts to run locked queue files.
3085These are not errors,
3086but can be useful to note if your queue appears to be clogged.
3087.ip 30
3088Lost locks (only if using lockf instead of flock).
3089.lp
3090Additionally,
3091values above 64 are reserved for extremely verbose debugging output.
3092No normal site would ever set these.
3093.sh 2 "File Modes"
3094.pp
3095The modes used for files depend on what functionality you want
3096and the level of security you require.
3097In many cases
3098.i sendmail
3099does careful checking of the modes
3100of files and directories
3101to avoid accidental compromise;
3102if you want to make it possible to have group-writable support files
3103you may need to use the
3104.b DontBlameSendmail
3105option to turn off some of these checks.
3106.sh 3 "To suid or not to suid?"
3107.pp
3108.i Sendmail
3109is no longer installed
3110set-user-ID to root.
3111sendmail/SECURITY
3112explains how to configure and install
3113.i sendmail
3114without set-user-ID to root but set-group-ID
3115which is the default configuration starting with 8.12.
3116.pp
3117The daemon usually runs as root, unless other measures are taken.
3118At the point where
3119.i sendmail
3120is about to
3121.i exec \|(2)
3122a mailer,
3123it checks to see if the userid is zero (root);
3124if so,
3125it resets the userid and groupid to a default
3126(set by the
3127.b U=
3128equate in the mailer line;
3129if that is not set, the
3130.b DefaultUser
3131option is used).
3132This can be overridden
3133by setting the
3134.b S
3135flag to the mailer
3136for mailers that are trusted
3137and must be called as root.
3138However,
3139this will cause mail processing
3140to be accounted
3141(using
3142.i sa \|(8))
3143to root
3144rather than to the user sending the mail.
3145.pp
3146A middle ground is to set the
3147.b RunAsUser
3148option.
3149This causes
3150.i sendmail
3151to become the indicated user as soon as it has done the startup
3152that requires root privileges
3153(primarily, opening the
3154.sm SMTP
3155socket).
3156If you use
3157.b RunAsUser ,
3158the queue directory
3159(normally
3160.i /var/spool/mqueue )
3161should be owned by that user,
3162and all files and databases
3163(including user
3164.i \&.forward
3165files,
3166alias files,
3167:include: files,
3168and external databases)
3169must be readable by that user.
3170Also, since sendmail will not be able to change its uid,
3171delivery to programs or files will be marked as unsafe,
3172e.g., undeliverable,
3173in
3174.i \&.forward ,
3175aliases,
3176and :include: files.
3177Administrators can override this by setting the
3178.b DontBlameSendmail
3179option to the setting
3180.b NonRootSafeAddr .
3181.b RunAsUser
3182is probably best suited for firewall configurations
3183that don't have regular user logins.
3184If the option is used on a system which performs local delivery,
3185then the local delivery agent must have the proper permissions
3186(i.e., usually set-user-ID root)
3187since it will be invoked by the
3188.b RunAsUser ,
3189not by root.
3190.sh 3 "Turning off security checks"
3191.pp
3192.i Sendmail
3193is very particular about the modes of files that it reads or writes.
3194For example, by default it will refuse to read most files
3195that are group writable
3196on the grounds that they might have been tampered with
3197by someone other than the owner;
3198it will even refuse to read files in group writable directories.
3199Also, sendmail will refuse to create a new aliases database in an
3200unsafe directory. You can get around this by manually creating the
3201database file as a trusted user ahead of time and then rebuilding the
3202aliases database with
3203.b newaliases .
3204.pp
3205If you are
3206.i quite
3207sure that your configuration is safe and you want
3208.i sendmail
3209to avoid these security checks,
3210you can turn off certain checks using the
3211.b DontBlameSendmail
3212option.
3213This option takes one or more names that disable checks.
3214In the descriptions that follow,
3215.q "unsafe directory"
3216means a directory that is writable by anyone other than the owner.
3217The values are:
3218.nr ii 0.5i
3219.ip Safe
3220No special handling.
3221.ip AssumeSafeChown
3222Assume that the
3223.i chown
3224system call is restricted to root.
3225Since some versions of UNIX permit regular users
3226to give away their files to other users on some filesystems,
3227.i sendmail
3228often cannot assume that a given file was created by the owner,
3229particularly when it is in a writable directory.
3230You can set this flag if you know that file giveaway is restricted
3231on your system.
3232.ip ClassFileInUnsafeDirPath
3233When reading class files (using the
3234.b F
3235line in the configuration file),
3236allow files that are in unsafe directories.
3237.ip DontWarnForwardFileInUnsafeDirPath
3238Prevent logging of
3239unsafe directory path warnings
3240for non-existent forward files.
3241.ip ErrorHeaderInUnsafeDirPath
3242Allow the file named in the
3243.b ErrorHeader
3244option to be in an unsafe directory.
3245.ip FileDeliveryToHardLink
3246Allow delivery to files that are hard links.
3247.ip FileDeliveryToSymLink
3248Allow delivery to files that are symbolic links.
3249.ip ForwardFileInGroupWritableDirPath
3250Allow
3251.i \&.forward
3252files in group writable directories.
3253.ip ForwardFileInUnsafeDirPath
3254Allow
3255.i \&.forward
3256files in unsafe directories.
3257.ip ForwardFileInUnsafeDirPathSafe
3258Allow a
3259.i \&.forward
3260file that is in an unsafe directory to include references
3261to program and files.
3262.ip GroupReadableKeyFile
3263Accept a group-readable key file for STARTTLS.
3264.ip GroupReadableSASLDBFile
3265Accept a group-readable Cyrus SASL password file.
3266.ip GroupWritableAliasFile
3267Allow group-writable alias files.
3268.ip GroupWritableDirPathSafe
3269Change the definition of
3270.q "unsafe directory"
3271to consider group-writable directories to be safe.
3272World-writable directories are always unsafe.
3273.ip GroupWritableForwardFile
3274Allow group writable
3275.i \&.forward
3276files.
3277.ip GroupWritableForwardFileSafe
3278Accept group-writable
3279.i \&.forward
3280files as safe for program and file delivery.
3281.ip GroupWritableIncludeFile
3282Allow group wriable
3283.i :include:
3284files.
3285.ip GroupWritableIncludeFileSafe
3286Accept group-writable
3287.i :include:
3288files as safe for program and file delivery.
3289.ip GroupWritableSASLDBFile
3290Accept a group-writable Cyrus SASL password file.
3291.ip HelpFileInUnsafeDirPath
3292Allow the file named in the
3293.b HelpFile
3294option to be in an unsafe directory.
3295.ip IncludeFileInGroupWritableDirPath
3296Allow
3297.i :include:
3298files in group writable directories.
3299.ip IncludeFileInUnsafeDirPath
3300Allow
3301.i :include:
3302files in unsafe directories.
3303.ip IncludeFileInUnsafeDirPathSafe
3304Allow a
3305.i :include:
3306file that is in an unsafe directory to include references
3307to program and files.
3308.ip InsufficientEntropy
3309Try to use STARTTLS even if the PRNG for OpenSSL is not properly seeded
3310despite the security problems.
3311.ip LinkedAliasFileInWritableDir
3312Allow an alias file that is a link in a writable directory.
3313.ip LinkedClassFileInWritableDir
3314Allow class files that are links in writable directories.
3315.ip LinkedForwardFileInWritableDir
3316Allow
3317.i \&.forward
3318files that are links in writable directories.
3319.ip LinkedIncludeFileInWritableDir
3320Allow
3321.i :include:
3322files that are links in writable directories.
3323.ip LinkedMapInWritableDir
3324Allow map files that are links in writable directories.
3325This includes alias database files.
3326.ip LinkedServiceSwitchFileInWritableDir
3327Allow the service switch file to be a link
3328even if the directory is writable.
3329.ip MapInUnsafeDirPath
3330Allow maps (e.g.,
3331.i hash ,
3332.i btree ,
3333and
3334.i dbm
3335files)
3336in unsafe directories.
3337This includes alias database files.
3338.ip NonRootSafeAddr
3339Do not mark file and program deliveries as unsafe
3340if sendmail is not running with root privileges.
3341.ip RunProgramInUnsafeDirPath
3342Run programs that are in writable directories without logging a warning.
3343.ip RunWritableProgram
3344Run programs that are group- or world-writable without logging a warning.
3345.ip TrustStickyBit
3346Allow group or world writable directories
3347if the sticky bit is set on the directory.
3348Do not set this on systems which do not honor
3349the sticky bit on directories.
3350.ip WorldWritableAliasFile
3351Accept world-writable alias files.
3352.ip WorldWritableForwardfile
3353Allow world writable
3354.i \&.forward
3355files.
3356.ip WorldWritableIncludefile
3357Allow world wriable
3358.i :include:
3359files.
3360.ip WriteMapToHardLink
3361Allow writes to maps that are hard links.
3362.ip WriteMapToSymLink
3363Allow writes to maps that are symbolic links.
3364.ip WriteStatsToHardLink
3365Allow the status file to be a hard link.
3366.ip WriteStatsToSymLink
3367Allow the status file to be a symbolic link.
3368.sh 2 "Connection Caching"
3369.pp
3370When processing the queue,
3371.i sendmail
3372will try to keep the last few open connections open
3373to avoid startup and shutdown costs.
3374This only applies to IPC and LPC connections.
3375.pp
3376When trying to open a connection
3377the cache is first searched.
3378If an open connection is found, it is probed to see if it is still active
3379by sending a
3380.sm RSET
3381command.
3382It is not an error if this fails;
3383instead, the connection is closed and reopened.
3384.pp
3385Two parameters control the connection cache.
3386The
3387.b ConnectionCacheSize
3388(\c
3389.b k )
3390option defines the number of simultaneous open connections
3391that will be permitted.
3392If it is set to zero,
3393connections will be closed as quickly as possible.
3394The default is one.
3395This should be set as appropriate for your system size;
3396it will limit the amount of system resources that
3397.i sendmail
3398will use during queue runs.
3399Never set this higher than 4.
3400.pp
3401The
3402.b ConnectionCacheTimeout
3403(\c
3404.b K )
3405option specifies the maximum time that any cached connection
3406will be permitted to idle.
3407When the idle time exceeds this value
3408the connection is closed.
3409This number should be small
3410(under ten minutes)
3411to prevent you from grabbing too many resources
3412from other hosts.
3413The default is five minutes.
3414.sh 2 "Name Server Access"
3415.pp
3416Control of host address lookups is set by the
3417.b hosts
3418service entry in your service switch file.
3419If you are on a system that has built-in service switch support
3420(e.g., Ultrix, Solaris, or DEC OSF/1)
3421then your system is probably configured properly already.
3422Otherwise,
3423.i sendmail
3424will consult the file
3425.b /etc/mail/service.switch ,
3426which should be created.
3427.i Sendmail
3428only uses two entries:
3429.b hosts
3430and
3431.b aliases ,
3432although system routines may use other services
3433(notably the
3434.b passwd
3435service for user name lookups by
3436.i getpwname ).
3437.pp
3438However, some systems (such as SunOS 4.X)
3439will do DNS lookups
3440regardless of the setting of the service switch entry.
3441In particular, the system routine
3442.i gethostbyname (3)
3443is used to look up host names,
3444and many vendor versions try some combination of DNS, NIS,
3445and file lookup in /etc/hosts
3446without consulting a service switch.
3447.i Sendmail
3448makes no attempt to work around this problem,
3449and the DNS lookup will be done anyway.
3450If you do not have a nameserver configured at all,
3451such as at a UUCP-only site,
3452.i sendmail
3453will get a
3454.q "connection refused"
3455message when it tries to connect to the name server.
3456If the
3457.b hosts
3458switch entry has the service
3459.q dns
3460listed somewhere in the list,
3461.i sendmail
3462will interpret this to mean a temporary failure
3463and will queue the mail for later processing;
3464otherwise, it ignores the name server data.
3465.pp
3466The same technique is used to decide whether to do MX lookups.
3467If you want MX support, you
3468.i must
3469have
3470.q dns
3471listed as a service in the
3472.b hosts
3473switch entry.
3474.pp
3475The
3476.b ResolverOptions
3477(\c
3478.b I )
3479option allows you to tweak name server options.
3480The command line takes a series of flags as documented in
3481.i resolver (3)
3482(with the leading
3483.q RES_
3484deleted).
3485Each can be preceded by an optional `+' or `\(mi'.
3486For example, the line
3487.(b
3488O ResolverOptions=+AAONLY \(miDNSRCH
3489.)b
3490turns on the AAONLY (accept authoritative answers only)
3491and turns off the DNSRCH (search the domain path) options.
3492Most resolver libraries default DNSRCH, DEFNAMES, and RECURSE
3493flags on and all others off.
3494If NETINET6 is enabled, most libraries default to USE_INET6 as well.
3495You can also include
3496.q HasWildcardMX
3497to specify that there is a wildcard MX record matching your domain;
3498this turns off MX matching when canonifying names,
3499which can lead to inappropriate canonifications.
3500Use
3501.q WorkAroundBrokenAAAA
3502when faced with a broken nameserver that returns SERVFAIL
3503(a temporary failure)
3504on T_AAAA (IPv6) lookups
3505during hostname canonification.
3506Notice: it might be necessary to apply the same (or similar) options to
3507.i submit.cf
3508too.
3509.pp
3510Version level 1 configurations (see the section about
3511``Configuration Version Level'')
3512turn DNSRCH and DEFNAMES off when doing delivery lookups,
3513but leave them on everywhere else.
3514Version 8 of
3515.i sendmail
3516ignores them when doing canonification lookups
3517(that is, when using $[ ... $]),
3518and always does the search.
3519If you don't want to do automatic name extension,
3520don't call $[ ... $].
3521.pp
3522The search rules for $[ ... $] are somewhat different than usual.
3523If the name being looked up
3524has at least one dot, it always tries the unmodified name first.
3525If that fails, it tries the reduced search path,
3526and lastly tries the unmodified name
3527(but only for names without a dot,
3528since names with a dot have already been tried).
3529This allows names such as
3530``utc.CS''
3531to match the site in Czechoslovakia
3532rather than the site in your local Computer Science department.
3533It also prefers A and CNAME records over MX records \*-
3534that is, if it finds an MX record it makes note of it,
3535but keeps looking.
3536This way, if you have a wildcard MX record matching your domain,
3537it will not assume that all names match.
3538.pp
3539To completely turn off all name server access
3540on systems without service switch support
3541(such as SunOS 4.X)
3542you will have to recompile with
3543\-DNAMED_BIND=0
3544and remove \-lresolv from the list of libraries to be searched
3545when linking.
3546.sh 2 "Moving the Per-User Forward Files"
3547.pp
3548Some sites mount each user's home directory
3549from a local disk on their workstation,
3550so that local access is fast.
3551However, the result is that .forward file lookups
3552from a central mail server are slow.
3553In some cases,
3554mail can even be delivered on machines inappropriately
3555because of a file server being down.
3556The performance can be especially bad if you run the automounter.
3557.pp
3558The
3559.b ForwardPath
3560(\c
3561.b J )
3562option allows you to set a path of forward files.
3563For example, the config file line
3564.(b
3565O ForwardPath=/var/forward/$u:$z/.forward.$w
3566.)b
3567would first look for a file with the same name as the user's login
3568in /var/forward;
3569if that is not found (or is inaccessible)
3570the file
3571``.forward.\c
3572.i machinename ''
3573in the user's home directory is searched.
3574A truly perverse site could also search by sender
3575by using $r, $s, or $f.
3576.pp
3577If you create a directory such as /var/forward,
3578it should be mode 1777
3579(that is, the sticky bit should be set).
3580Users should create the files mode 0644.
3581Note that you must use the
3582ForwardFileInUnsafeDirPath and
3583ForwardFileInUnsafeDirPathSafe
3584flags with the
3585.b DontBlameSendmail
3586option to allow forward files in a world writable directory.
3587This might also be used as a denial of service attack
3588(users could create forward files for other users);
3589a better approach might be to create
3590/var/forward
3591mode 0755
3592and create empty files for each user,
3593owned by that user,
3594mode 0644.
3595If you do this, you don't have to set the DontBlameSendmail options
3596indicated above.
3597.sh 2 "Free Space"
3598.pp
3599On systems that have one of the system calls in the
3600.i statfs (2)
3601family
3602(including
3603.i statvfs
3604and
3605.i ustat ),
3606you can specify a minimum number of free blocks on the queue filesystem
3607using the
3608.b MinFreeBlocks
3609(\c
3610.b b )
3611option.
3612If there are fewer than the indicated number of blocks free
3613on the filesystem on which the queue is mounted
3614the SMTP server will reject mail
3615with the
3616452 error code.
3617This invites the SMTP client to try again later.
3618.pp
3619Beware of setting this option too high;
3620it can cause rejection of email
3621when that mail would be processed without difficulty.
3622.sh 2 "Maximum Message Size"
3623.pp
3624To avoid overflowing your system with a large message,
3625the
3626.b MaxMessageSize
3627option can be set to set an absolute limit
3628on the size of any one message.
3629This will be advertised in the ESMTP dialogue
3630and checked during message collection.
3631.sh 2 "Privacy Flags"
3632.pp
3633The
3634.b PrivacyOptions
3635(\c
3636.b p )
3637option allows you to set certain
3638``privacy''
3639flags.
3640Actually, many of them don't give you any extra privacy,
3641rather just insisting that client SMTP servers
3642use the HELO command
3643before using certain commands
3644or adding extra headers to indicate possible spoof attempts.
3645.pp
3646The option takes a series of flag names;
3647the final privacy is the inclusive or of those flags.
3648For example:
3649.(b
3650O PrivacyOptions=needmailhelo, noexpn
3651.)b
3652insists that the HELO or EHLO command be used before a MAIL command is accepted
3653and disables the EXPN command.
3654.pp
3655The flags are detailed in section
3656.\"XREF
36575.6.
3658.sh 2 "Send to Me Too"
3659.pp
3660Beginning with version 8.10,
3661.i sendmail
3662includes by default the (envelope) sender in any list expansions.
3663For example, if
3664.q matt
3665sends to a list that contains
3666.q matt
3667as one of the members he will get a copy of the message.
3668If the
3669.b MeToo
3670option is set to
3671.sm FALSE
3672(in the configuration file or via the command line),
3673this behavior is changed, i.e.,
3674the (envelope) sender is excluded in list expansions.
3675.sh 1 "THE WHOLE SCOOP ON THE CONFIGURATION FILE"
3676.pp
3677This section describes the configuration file
3678in detail.
3679.pp
3680There is one point that should be made clear immediately:
3681the syntax of the configuration file
3682is designed to be reasonably easy to parse,
3683since this is done every time
3684.i sendmail
3685starts up,
3686rather than easy for a human to read or write.
3687The configuration file should be generated via the method described in
3688.b cf/README ,
3689it should not be edited directly unless someone is familiar
3690with the internals of the syntax described here and it is
3691not possible to achieve the desired result via the default method.
3692.pp
3693The configuration file is organized as a series of lines,
3694each of which begins with a single character
3695defining the semantics for the rest of the line.
3696Lines beginning with a space or a tab
3697are continuation lines
3698(although the semantics are not well defined in many places).
3699Blank lines and lines beginning with a sharp symbol
3700(`#')
3701are comments.
3702.sh 2 "R and S \*- Rewriting Rules"
3703.pp
3704The core of address parsing
3705are the rewriting rules.
3706These are an ordered production system.
3707.i Sendmail
3708scans through the set of rewriting rules
3709looking for a match on the left hand side
3710(LHS)
3711of the rule.
3712When a rule matches,
3713the address is replaced by the right hand side
3714(RHS)
3715of the rule.
3716.pp
3717There are several sets of rewriting rules.
3718Some of the rewriting sets are used internally
3719and must have specific semantics.
3720Other rewriting sets
3721do not have specifically assigned semantics,
3722and may be referenced by the mailer definitions
3723or by other rewriting sets.
3724.pp
3725The syntax of these two commands are:
3726.(b F
3727.b S \c
3728.i n
3729.)b
3730Sets the current ruleset being collected to
3731.i n .
3732If you begin a ruleset more than once
3733it appends to the old definition.
3734.(b F
3735.b R \c
3736.i lhs
3737.i rhs
3738.i comments
3739.)b
3740The
3741fields must be separated
3742by at least one tab character;
3743there may be embedded spaces
3744in the fields.
3745The
3746.i lhs
3747is a pattern that is applied to the input.
3748If it matches,
3749the input is rewritten to the
3750.i rhs .
3751The
3752.i comments
3753are ignored.
3754.pp
3755Macro expansions of the form
3756.b $ \c
3757.i x
3758are performed when the configuration file is read.
3759A literal
3760.b $
3761can be included using
3762.b $$ .
3763Expansions of the form
3764.b $& \c
3765.i x
3766are performed at run time using a somewhat less general algorithm.
3767This is intended only for referencing internally defined macros
3768such as
3769.b $h
3770that are changed at runtime.
3771.sh 3 "The left hand side"
3772.pp
3773The left hand side of rewriting rules contains a pattern.
3774Normal words are simply matched directly.
3775Metasyntax is introduced using a dollar sign.
3776The metasymbols are:
3777.(b
3778.ta \w'\fB$=\fP\fIx\fP 'u
3779\fB$*\fP Match zero or more tokens
3780\fB$+\fP Match one or more tokens
3781\fB$\-\fP Match exactly one token
3782\fB$=\fP\fIx\fP Match any phrase in class \fIx\fP
3783\fB$~\fP\fIx\fP Match any word not in class \fIx\fP
3784.)b
3785If any of these match,
3786they are assigned to the symbol
3787.b $ \c
3788.i n
3789for replacement on the right hand side,
3790where
3791.i n
3792is the index in the LHS.
3793For example,
3794if the LHS:
3795.(b
3796$\-:$+
3797.)b
3798is applied to the input:
3799.(b
3800UCBARPA:eric
3801.)b
3802the rule will match, and the values passed to the RHS will be:
3803.(b
3804.ta 4n
3805$1 UCBARPA
3806$2 eric
3807.)b
3808.pp
3809Additionally, the LHS can include
3810.b $@
3811to match zero tokens.
3812This is
3813.i not
3814bound to a
3815.b $ \c
3816.i n
3817on the RHS, and is normally only used when it stands alone
3818in order to match the null input.
3819.sh 3 "The right hand side"
3820.pp
3821When the left hand side of a rewriting rule matches,
3822the input is deleted and replaced by the right hand side.
3823Tokens are copied directly from the RHS
3824unless they begin with a dollar sign.
3825Metasymbols are:
3826.(b
3827.ta \w'$#mailer\0\0\0'u
3828\fB$\fP\fIn\fP Substitute indefinite token \fIn\fP from LHS
3829\fB$[\fP\fIname\fP\fB$]\fP Canonicalize \fIname\fP
3830\fB$(\fP\fImap key\fP \fB$@\fP\fIarguments\fP \fB$:\fP\fIdefault\fP \fB$)\fP
3831 Generalized keyed mapping function
3832\fB$>\fP\fIn\fP \*(lqCall\*(rq ruleset \fIn\fP
3833\fB$#\fP\fImailer\fP Resolve to \fImailer\fP
3834\fB$@\fP\fIhost\fP Specify \fIhost\fP
3835\fB$:\fP\fIuser\fP Specify \fIuser\fP
3836.)b
3837.pp
3838The
3839.b $ \c
3840.i n
3841syntax substitutes the corresponding value from a
3842.b $+ ,
3843.b $\- ,
3844.b $* ,
3845.b $= ,
3846or
3847.b $~
3848match on the LHS.
3849It may be used anywhere.
3850.pp
3851A host name enclosed between
3852.b $[
3853and
3854.b $]
3855is looked up in the host database(s)
3856and replaced by the canonical name\**.
3857.(f
3858\**This is actually
3859completely equivalent
3860to $(host \fIhostname\fP$).
3861In particular, a
3862.b $:
3863default can be used.
3864.)f
3865For example,
3866.q $[ftp$]
3867might become
3868.q ftp.CS.Berkeley.EDU
3869and
3870.q $[[128.32.130.2]$]
3871would become
3872.q vangogh.CS.Berkeley.EDU.
3873.i Sendmail
3874recognizes its numeric IP address
3875without calling the name server
3876and replaces it with its canonical name.
3877.pp
3878The
3879.b $(
3880\&...
3881.b $)
3882syntax is a more general form of lookup;
3883it uses a named map instead of an implicit map.
3884If no lookup is found, the indicated
3885.i default
3886is inserted;
3887if no default is specified and no lookup matches,
3888the value is left unchanged.
3889The
3890.i arguments
3891are passed to the map for possible use.
3892.pp
3893The
3894.b $> \c
3895.i n
3896syntax
3897causes the remainder of the line to be substituted as usual
3898and then passed as the argument to ruleset
3899.i n .
3900The final value of ruleset
3901.i n
3902then becomes
3903the substitution for this rule.
3904The
3905.b $>
3906syntax expands everything after the ruleset name
3907to the end of the replacement string
3908and then passes that as the initial input to the ruleset.
3909Recursive calls are allowed.
3910For example,
3911.(b
3912$>0 $>3 $1
3913.)b
3914expands $1, passes that to ruleset 3, and then passes the result
3915of ruleset 3 to ruleset 0.
3916.pp
3917The
3918.b $#
3919syntax should
3920.i only
3921be used in ruleset zero,
3922a subroutine of ruleset zero,
3923or rulesets that return decisions (e.g., check_rcpt).
3924It causes evaluation of the ruleset to terminate immediately,
3925and signals to
3926.i sendmail
3927that the address has completely resolved.
3928The complete syntax for ruleset 0 is:
3929.(b
3930\fB$#\fP\fImailer\fP \fB$@\fP\fIhost\fP \fB$:\fP\fIuser\fP
3931.)b
3932This specifies the
3933{mailer, host, user}
39343-tuple necessary to direct the mailer.
3935Note: the third element (
3936.i user
3937) is often also called
3938.i address
3939part.
3940If the mailer is local
3941the host part may be omitted\**.
3942.(f
3943\**You may want to use it for special
3944.q "per user"
3945extensions.
3946For example, in the address
3947.q jgm+foo@CMU.EDU ;
3948the
3949.q +foo
3950part is not part of the user name,
3951and is passed to the local mailer for local use.
3952.)f
3953The
3954.i mailer
3955must be a single word,
3956but the
3957.i host
3958and
3959.i user
3960may be multi-part.
3961If the
3962.i mailer
3963is the built-in IPC mailer,
3964the
3965.i host
3966may be a colon-separated list of hosts
3967that are searched in order for the first working address
3968(exactly like MX records).
3969The
3970.i user
3971is later rewritten by the mailer-specific envelope rewriting set
3972and assigned to the
3973.b $u
3974macro.
3975As a special case, if the mailer specified has the
3976.b F=@
3977flag specified
3978and the first character of the
3979.b $:
3980value is
3981.q @ ,
3982the
3983.q @
3984is stripped off, and a flag is set in the address descriptor
3985that causes sendmail to not do ruleset 5 processing.
3986.pp
3987Normally, a rule that matches is retried,
3988that is,
3989the rule loops until it fails.
3990A RHS may also be preceded by a
3991.b $@
3992or a
3993.b $:
3994to change this behavior.
3995A
3996.b $@
3997prefix causes the ruleset to return with the remainder of the RHS
3998as the value.
3999A
4000.b $:
4001prefix causes the rule to terminate immediately,
4002but the ruleset to continue;
4003this can be used to avoid continued application of a rule.
4004The prefix is stripped before continuing.
4005.pp
4006The
4007.b $@
4008and
4009.b $:
4010prefixes may precede a
4011.b $>
4012spec;
4013for example:
4014.(b
4015.ta 8n
4016R$+ $: $>7 $1
4017.)b
4018matches anything,
4019passes that to ruleset seven,
4020and continues;
4021the
4022.b $:
4023is necessary to avoid an infinite loop.
4024.pp
4025Substitution occurs in the order described,
4026that is,
4027parameters from the LHS are substituted,
4028hostnames are canonicalized,
4029.q subroutines
4030are called,
4031and finally
4032.b $# ,
4033.b $@ ,
4034and
4035.b $:
4036are processed.
4037.sh 3 "Semantics of rewriting rule sets"
4038.pp
4039There are six rewriting sets
4040that have specific semantics.
4041Five of these are related as depicted by figure 1.
4042.(z
4043.hl
4044.ie n \{\
4045.(c
4046 +---+
4047 -->| 0 |-->resolved address
4048 / +---+
4049 / +---+ +---+
4050 / ---->| 1 |-->| S |--
4051 +---+ / +---+ / +---+ +---+ \e +---+
4052addr-->| 3 |-->| D |-- --->| 4 |-->msg
4053 +---+ +---+ \e +---+ +---+ / +---+
4054 --->| 2 |-->| R |--
4055 +---+ +---+
4056.)c
4057
4058.\}
4059.el \{\
4060.ie !"\*(.T"" \{\
4061.PS
4062boxwid = 0.3i
4063boxht = 0.3i
4064movewid = 0.3i
4065moveht = 0.3i
4066linewid = 0.3i
4067lineht = 0.3i
4068
4069 box invis "addr"; arrow
4070Box3: box "3"
4071A1: arrow
4072BoxD: box "D"; line; L1: Here
4073C: [
4074 C1: arrow; box "1"; arrow; box "S"; line; E1: Here
4075 move to C1 down 0.5; right
4076 C2: arrow; box "2"; arrow; box "R"; line; E2: Here
4077 ] with .w at L1 + (0.5, 0)
4078 move to C.e right 0.5
4079L4: arrow; box "4"; arrow; box invis "msg"
4080 line from L1 to C.C1
4081 line from L1 to C.C2
4082 line from C.E1 to L4
4083 line from C.E2 to L4
4084 move to BoxD.n up 0.6; right
4085Box0: arrow; box "0"
4086 arrow; box invis "resolved address" width 1.3
4087 line from 1/3 of the way between A1 and BoxD.w to Box0
4088.PE
4089.\}
4090.el .sp 2i
4091.\}
4092.ce
4093Figure 1 \*- Rewriting set semantics
4094.(c
4095D \*- sender domain addition
4096S \*- mailer-specific sender rewriting
4097R \*- mailer-specific recipient rewriting
4098.)c
4099.hl
4100.)z
4101.pp
4102Ruleset three
4103should turn the address into
4104.q "canonical form."
4105This form should have the basic syntax:
4106.(b
4107local-part@host-domain-spec
4108.)b
4109Ruleset three
4110is applied by
4111.i sendmail
4112before doing anything with any address.
4113.pp
4114If no
4115.q @
4116sign is specified,
4117then the
4118host-domain-spec
4119.i may
4120be appended (box
4121.q D
4122in Figure 1)
4123from the
4124sender address
4125(if the
4126.b C
4127flag is set in the mailer definition
4128corresponding to the
4129.i sending
4130mailer).
4131.pp
4132Ruleset zero
4133is applied after ruleset three
4134to addresses that are going to actually specify recipients.
4135It must resolve to a
4136.i "{mailer, host, address}"
4137triple.
4138The
4139.i mailer
4140must be defined in the mailer definitions
4141from the configuration file.
4142The
4143.i host
4144is defined into the
4145.b $h
4146macro
4147for use in the argv expansion of the specified mailer.
4148Notice: since the envelope sender address will be used if
4149a delivery status notification must be send,
4150i.e., is may specify a recipient,
4151it is also run through ruleset zero.
4152If ruleset zero returns a temporary error
4153.b 4xy
4154then delivery is deferred.
4155This can be used to temporarily disable delivery,
4156e.g., based on the time of the day or other varying parameters.
4157It should not be used to quarantine e-mails.
4158.pp
4159Rulesets one and two
4160are applied to all sender and recipient addresses respectively.
4161They are applied before any specification
4162in the mailer definition.
4163They must never resolve.
4164.pp
4165Ruleset four is applied to all addresses
4166in the message.
4167It is typically used
4168to translate internal to external form.
4169.pp
4170In addition,
4171ruleset 5 is applied to all local addresses
4172(specifically, those that resolve to a mailer with the `F=5'
4173flag set)
4174that do not have aliases.
4175This allows a last minute hook for local names.
4176.sh 3 "Ruleset hooks"
4177.pp
4178A few extra rulesets are defined as
4179.q hooks
4180that can be defined to get special features.
4181They are all named rulesets.
4182The
4183.q check_*
4184forms all give accept/reject status;
4185falling off the end or returning normally is an accept,
4186and resolving to
4187.b $#error
4188is a reject or quarantine.
4189Quarantining is chosen by specifying
4190.b quarantine
4191in the second part of the mailer triplet:
4192.(b
4193$#error $@ quarantine $: Reason for quarantine
4194.)b
4195Many of these can also resolve to the special mailer name
4196.b $#discard ;
4197this accepts the message as though it were successful
4198but then discards it without delivery.
4199Note,
4200this mailer cannot be chosen as a mailer in ruleset 0.
4201Note also that all
4202.q check_*
4203rulesets have to deal with temporary failures, especially for map lookups,
4204themselves, i.e., they should return a temporary error code
4205or at least they should make a proper decision in those cases.
4206.sh 4 "check_relay"
4207.pp
4208The
4209.i check_relay
4210ruleset is called after a connection is accepted by the daemon.
4211It is not called when sendmail is started using the
4212.b \-bs
4213option.
4214It is passed
4215.(b
4216client.host.name $| client.host.address
4217.)b
4218where
4219.b $|
4220is a metacharacter separating the two parts.
4221This ruleset can reject connections from various locations.
4222Note that it only checks the connecting SMTP client IP address and hostname.
4223It does not check for third party message relaying.
4224The
4225.i check_rcpt
4226ruleset discussed below usually does third party message relay checking.
4227.sh 4 "check_mail"
4228.pp
4229The
4230.i check_mail
4231ruleset is passed the user name parameter of the
4232.sm "SMTP MAIL"
4233command.
4234It can accept or reject the address.
4235.sh 4 "check_rcpt"
4236.pp
4237The
4238.i check_rcpt
4239ruleset is passed the user name parameter of the
4240.sm "SMTP RCPT"
4241command.
4242It can accept or reject the address.
4243.sh 4 "check_data"
4244.pp
4245The
4246.i check_data
4247ruleset is called after the
4248.sm "SMTP DATA"
4249command, its parameter is the number of recipients.
4250It can accept or reject the command.
4251.sh 4 "check_compat"
4252.pp
4253The
4254.i check_compat
4255ruleset is passed
4256.(b
4257sender-address $| recipient-address
4258.)b
4259where
4260.b $|
4261is a metacharacter separating the addresses.
4262It can accept or reject mail transfer between these two addresses
4263much like the
4264.i checkcompat()
4265function.
4266Note:
4267while other
4268.i check_*
4269rulesets are invoked during the SMTP mail receiption stage
4270(i.e., in the SMTP server),
4271.i check_compat
4272is invoked during the mail delivery stage.
4273.sh 4 "check_eoh"
4274.pp
4275The
4276.i check_eoh
4277ruleset is passed
4278.(b
4279number-of-headers $| size-of-headers
4280.)b
4281where
4282.b $|
4283is a metacharacter separating the numbers.
4284These numbers can be used for size comparisons with the
4285.b arith
4286map.
4287The ruleset is triggered after
4288all of the headers have been read.
4289It can be used to correlate information gathered
4290from those headers using the
4291.b macro
4292storage map.
4293One possible use is to check for a missing header.
4294For example:
4295.(b
4296.ta 1.5i
4297Kstorage macro
4298HMessage-Id: $>CheckMessageId
4299
4300SCheckMessageId
4301# Record the presence of the header
4302R$* $: $(storage {MessageIdCheck} $@ OK $) $1
4303R< $+ @ $+ > $@ OK
4304R$* $#error $: 553 Header Error
4305
4306Scheck_eoh
4307# Check the macro
4308R$* $: < $&{MessageIdCheck} >
4309# Clear the macro for the next message
4310R$* $: $(storage {MessageIdCheck} $) $1
4311# Has a Message-Id: header
4312R< $+ > $@ OK
4313# Allow missing Message-Id: from local mail
4314R$* $: < $&{client_name} >
4315R< > $@ OK
4316R< $=w > $@ OK
4317# Otherwise, reject the mail
4318R$* $#error $: 553 Header Error
4319.)b
4320Keep in mind the Message-Id: header is not a required header and
4321is not a guaranteed spam indicator.
4322This ruleset is an example and
4323should probably not be used in production.
4324.sh 4 "check_eom"
4325.pp
4326The
4327.i check_eom
4328ruleset is called after the end of a message,
4329its parameter is the message size.
4330It can accept or reject the message.
4331.sh 4 "check_etrn"
4332.pp
4333The
4334.i check_etrn
4335ruleset is passed the parameter of the
4336.sm "SMTP ETRN"
4337command.
4338It can accept or reject the command.
4339.sh 4 "check_expn"
4340.pp
4341The
4342.i check_expn
4343ruleset is passed the user name parameter of the
4344.sm "SMTP EXPN"
4345command.
4346It can accept or reject the address.
4347.sh 4 "check_vrfy"
4348.pp
4349The
4350.i check_vrfy
4351ruleset is passed the user name parameter of the
4352.sm "SMTP VRFY"
4353command.
4354It can accept or reject the command.
4355.sh 4 "trust_auth"
4356.pp
4357The
4358.i trust_auth
4359ruleset is passed the AUTH= parameter of the
4360.sm "SMTP MAIL"
4361command.
4362It is used to determine whether this value should be
4363trusted. In order to make this decision, the ruleset
4364may make use of the various
4365.b ${auth_*}
4366macros.
4367If the ruleset does resolve to the
4368.q error
4369mailer the AUTH= parameter is not trusted and hence
4370not passed on to the next relay.
4371.sh 4 "tls_client"
4372.pp
4373The
4374.i tls_client
4375ruleset is called when sendmail acts as server, after a STARTTLS command
4376has been issued, and from
4377.i check_mail.
4378The parameter is the value of
4379.b ${verify}
4380and STARTTLS or MAIL, respectively.
4381If the ruleset does resolve to the
4382.q error
4383mailer, the appropriate error code is returned to the client.
4384.sh 4 "tls_server"
4385.pp
4386The
4387.i tls_server
4388ruleset is called when sendmail acts as client after a STARTTLS command
4389(should) have been issued.
4390The parameter is the value of
4391.b ${verify} .
4392If the ruleset does resolve to the
4393.q error
4394mailer, the connection is aborted
4395(treated as non-deliverable with a permanent or temporary error).
4396.sh 4 "tls_rcpt"
4397.pp
4398The
4399.i tls_rcpt
4400ruleset is called each time before a RCPT TO command is sent.
4401The parameter is the current recipient.
4402If the ruleset does resolve to the
4403.q error
4404mailer, the RCPT TO command is suppressed
4405(treated as non-deliverable with a permanent or temporary error).
4406This ruleset allows to require encryption or verification of
4407the recipient's MTA even if the mail is somehow redirected
4408to another host.
4409For example, sending mail to
4410.i luke@endmail.org
4411may get redirected to a host named
4412.i death.star
4413and hence the tls_server ruleset won't apply.
4414By introducing per recipient restrictions such attacks
4415(e.g., via DNS spoofing) can be made impossible.
4416See
4417.i cf/README
4418how this ruleset can be used.
4419.sh 4 "srv_features"
4420.pp
4421The
4422.i srv_features
4423ruleset is called with the connecting client's host name
4424when a client connects to sendmail.
4425This ruleset should return
4426.b $#
4427followed by a list of options (single characters
4428delimited by white space).
4429If the return value starts with anything else it is silently ignored.
4430Generally upper case characters turn off a feature
4431while lower case characters turn it on.
4432Option `S' causes the server not to offer STARTTLS,
4433which is useful to interact with MTAs/MUAs that have broken
4434STARTTLS implementations by simply not offering it.
4435`V' turns off the request for a client certificate during the TLS handshake.
4436Options `A' and `P' suppress SMTP AUTH and PIPELINING, respectively.
4437`c' is the equivalent to AuthOptions=p, i.e.,
4438it doesn't permit mechanisms susceptible to simple
4439passive attack (e.g., PLAIN, LOGIN), unless a security layer is active.
4440Option `l' requires SMTP AUTH for a connection.
4441Options 'B', 'D', 'E', and 'X' suppress SMTP VERB, DSN, ETRN, and EXPN,
4442respectively.
4443.(b
4444.ta 9n
4445A Do not offer AUTH
4446a Offer AUTH (default)
4447B Do not offer VERB
4448b Offer VERB (default)
4449C Do not require security layer for
4450 plaintext AUTH (default)
4451c Require security layer for plaintext AUTH
4452D Do not offer DSN
4453d Offer DSN (default)
4454E Do not offer ETRN
4455e Offer ETRN (default)
4456L Do not require AUTH (default)
4457l Require AUTH
4458P Do not offer PIPELINING
4459p Offer PIPELINING (default)
4460S Do not offer STARTTLS
4461s Offer STARTTLS (default)
4462V Do not request a client certificate
4463v Request a client certificate (default)
4464X Do not offer EXPN
4465x Offer EXPN (default)
4466.)b
4467Note: the entries marked as ``(default)'' may require that some
4468configuration has been made, e.g., SMTP AUTH is only available if
4469properly configured.
4470Moreover, many options can be changed on a global basis via other
4471settings as explained in this document, e.g., via DaemonPortOptions.
4472.pp
4473The ruleset may return `$#temp' to indicate that there is a temporary
4474problem determining the correct features, e.g., if a map is unavailable.
4475In that case, the SMTP server issues a temporary failure and does not
4476accept email.
4477.sh 4 "try_tls"
4478.pp
4479The
4480.i try_tls
4481ruleset is called when sendmail connects to another MTA.
4482If the ruleset does resolve to the
4483.q error
4484mailer, sendmail does not try STARTTLS even if it is offered.
4485This is useful to interact with MTAs that have broken
4486STARTTLS implementations by simply not using it.
4487.sh 4 "authinfo"
4488.pp
4489The
4490.i authinfo
4491ruleset is called when sendmail tries to authenticate to another MTA.
4492It should return
4493.b $#
4494followed by a list of tokens that are used for SMTP AUTH.
4495If the return value starts with anything else it is silently ignored.
4496Each token is a tagged string of the form:
4497"TDstring"
4498(including the quotes), where
4499.(b
4500.ta 9n
4501T Tag which describes the item
4502D Delimiter: ':' simple text follows
4503 '=' string is base64 encoded
4504string Value of the item
4505.)b
4506Valid values for the tag are:
4507.(b
4508.ta 9n
4509U user (authorization) id
4510I authentication id
4511P password
4512R realm
4513M list of mechanisms delimited by spaces
4514.)b
4515If this ruleset is defined, the option
4516.b DefaultAuthInfo
4517is ignored (even if the ruleset does not return a ``useful'' result).
4518.sh 4 "queuegroup"
4519.pp
4520The
4521.i queuegroup
4522ruleset is used to map a recipient address to a queue group name.
4523The input for the ruleset is a recipient address as specified by the
4524.sm "SMTP RCPT"
4525command.
4526The ruleset should return
4527.b $#
4528followed by the name of a queue group.
4529If the return value starts with anything else it is silently ignored.
4530See the section about ``Queue Groups and Queue Directories''
4531for further information.
4532.sh 4 "greet_pause"
4533.pp
4534The
4535.i greet_pause
4536ruleset is used to specify the amount of time to pause before sending the
4537initial SMTP 220 greeting.
4538If any traffic is received during that pause, an SMTP 554 rejection
4539response is given instead of the 220 greeting and all SMTP commands are
4540rejected during that connection.
4541This helps protect sites from open proxies and SMTP slammers.
4542The ruleset should return
4543.b $#
4544followed by the number of milliseconds (thousandths of a second) to
4545pause.
4546If the return value starts with anything else or is not a number,
4547it is silently ignored.
4548Note: this ruleset is not invoked (and hence the feature is disabled)
4549when the smtps (SMTP over SSL) is used, i.e.,
4550the
4551.i s
4552modifier is set for the daemon via
4553.b DaemonPortOptions ,
4554because in this case the SSL handshake is performed before
4555the greeting is sent.
4556.sh 3 "IPC mailers"
4557.pp
4558Some special processing occurs
4559if the ruleset zero resolves to an IPC mailer
4560(that is, a mailer that has
4561.q [IPC]
4562listed as the Path in the
4563.b M
4564configuration line.
4565The host name passed after
4566.q $@
4567has MX expansion performed if not delivering via a named socket;
4568this looks the name up in DNS to find alternate delivery sites.
4569.pp
4570The host name can also be provided as a dotted quad
4571or an IPv6 address in square brackets;
4572for example:
4573.(b
4574[128.32.149.78]
4575.)b
4576or
4577.(b
4578[IPv6:2002:c0a8:51d2::23f4]
4579.)b
4580This causes direct conversion of the numeric value
4581to an IP host address.
4582.pp
4583The host name passed in after the
4584.q $@
4585may also be a colon-separated list of hosts.
4586Each is separately MX expanded and the results are concatenated
4587to make (essentially) one long MX list.
4588The intent here is to create
4589.q fake
4590MX records that are not published in DNS
4591for private internal networks.
4592.pp
4593As a final special case, the host name can be passed in
4594as a text string
4595in square brackets:
4596.(b
4597[ucbvax.berkeley.edu]
4598.)b
4599This form avoids the MX mapping.
4600.b N.B.:
4601.i
4602This is intended only for situations where you have a network firewall
4603or other host that will do special processing for all your mail,
4604so that your MX record points to a gateway machine;
4605this machine could then do direct delivery to machines
4606within your local domain.
4607Use of this feature directly violates RFC 1123 section 5.3.5:
4608it should not be used lightly.
4609.r
4610.sh 2 "D \*- Define Macro"
4611.pp
4612Macros are named with a single character
4613or with a word in {braces}.
4614The names ``x'' and ``{x}'' denote the same macro
4615for every single character ``x''.
4616Single character names may be selected from the entire ASCII set,
4617but user-defined macros
4618should be selected from the set of upper case letters only.
4619Lower case letters
4620and special symbols
4621are used internally.
4622Long names beginning with a lower case letter or a punctuation character
4623are reserved for use by sendmail,
4624so user-defined long macro names should begin with an upper case letter.
4625.pp
4626The syntax for macro definitions is:
4627.(b F
4628.b D \c
4629.i x\|val
4630.)b
4631where
4632.i x
4633is the name of the macro
4634(which may be a single character
4635or a word in braces)
4636and
4637.i val
4638is the value it should have.
4639There should be no spaces given
4640that do not actually belong in the macro value.
4641.pp
4642Macros are interpolated
4643using the construct
4644.b $ \c
4645.i x ,
4646where
4647.i x
4648is the name of the macro to be interpolated.
4649This interpolation is done when the configuration file is read,
4650except in
4651.b M
4652lines.
4653The special construct
4654.b $& \c
4655.i x
4656can be used in
4657.b R
4658lines to get deferred interpolation.
4659.pp
4660Conditionals can be specified using the syntax:
4661.(b
4662$?x text1 $| text2 $.
4663.)b
4664This interpolates
4665.i text1
4666if the macro
4667.b $x
4668is set and non-null,
4669and
4670.i text2
4671otherwise.
4672The
4673.q else
4674(\c
4675.b $| )
4676clause may be omitted.
4677.pp
4678The following macros are defined and/or used internally by
4679.i sendmail
4680for interpolation into argv's for mailers
4681or for other contexts.
4682The ones marked \(dg are information passed into sendmail\**,
4683.(f
4684\**As of version 8.6,
4685all of these macros have reasonable defaults.
4686Previous versions required that they be defined.
4687.)f
4688the ones marked \(dd are information passed both in and out of sendmail,
4689and the unmarked macros are passed out of sendmail
4690but are not otherwise used internally.
4691These macros are:
4692.nr ii 5n
4693.ip $a
4694The origination date in RFC 822 format.
4695This is extracted from the Date: line.
4696.ip $b
4697The current date in RFC 822 format.
4698.ip $c
4699The hop count.
4700This is a count of the number of Received: lines
4701plus the value of the
4702.b \-h
4703command line flag.
4704.ip $d
4705The current date in UNIX (ctime) format.
4706.ip $e\(dg
4707(Obsolete; use SmtpGreetingMessage option instead.)
4708The SMTP entry message.
4709This is printed out when SMTP starts up.
4710The first word must be the
4711.b $j
4712macro as specified by RFC 821.
4713Defaults to
4714.q "$j Sendmail $v ready at $b" .
4715Commonly redefined to include the configuration version number, e.g.,
4716.q "$j Sendmail $v/$Z ready at $b"
4717.ip $f
4718The envelope sender (from) address.
4719.ip $g
4720The sender address relative to the recipient.
4721For example, if
4722.b $f
4723is
4724.q foo ,
4725.b $g
4726will be
4727.q host!foo ,
4728.q foo@host.domain ,
4729or whatever is appropriate for the receiving mailer.
4730.ip $h
4731The recipient host.
4732This is set in ruleset 0 from the $@ field of a parsed address.
4733.ip $i
4734The queue id,
4735e.g.,
4736.q f344MXxp018717 .
4737.ip $j\(dd
4738The \*(lqofficial\*(rq domain name for this site.
4739This is fully qualified if the full qualification can be found.
4740It
4741.i must
4742be redefined to be the fully qualified domain name
4743if your system is not configured so that information can find
4744it automatically.
4745.ip $k
4746The UUCP node name (from the uname system call).
4747.ip $l\(dg
4748(Obsolete; use UnixFromLine option instead.)
4749The format of the UNIX from line.
4750Unless you have changed the UNIX mailbox format,
4751you should not change the default,
4752which is
4753.q "From $g $d" .
4754.ip $m
4755The domain part of the \fIgethostname\fP return value.
4756Under normal circumstances,
4757.b $j
4758is equivalent to
4759.b $w.$m .
4760.ip $n\(dg
4761The name of the daemon (for error messages).
4762Defaults to
4763.q MAILER-DAEMON .
4764.ip $o\(dg
4765(Obsolete: use OperatorChars option instead.)
4766The set of \*(lqoperators\*(rq in addresses.
4767A list of characters
4768which will be considered tokens
4769and which will separate tokens
4770when doing parsing.
4771For example, if
4772.q @
4773were in the
4774.b $o
4775macro, then the input
4776.q a@b
4777would be scanned as three tokens:
4778.q a,
4779.q @,
4780and
4781.q b.
4782Defaults to
4783.q ".:@[]" ,
4784which is the minimum set necessary to do RFC 822 parsing;
4785a richer set of operators is
4786.q ".:%@!/[]" ,
4787which adds support for UUCP, the %-hack, and X.400 addresses.
4788.ip $p
4789Sendmail's process id.
4790.ip $q\(dg
4791Default format of sender address.
4792The
4793.b $q
4794macro specifies how an address should appear in a message
4795when it is defaulted.
4796Defaults to
4797.q "<$g>" .
4798It is commonly redefined to be
4799.q "$?x$x <$g>$|$g$."
4800or
4801.q "$g$?x ($x)$." ,
4802corresponding to the following two formats:
4803.(b
4804Eric Allman <eric@CS.Berkeley.EDU>
4805eric@CS.Berkeley.EDU (Eric Allman)
4806.)b
4807.i Sendmail
4808properly quotes names that have special characters
4809if the first form is used.
4810.ip $r
4811Protocol used to receive the message.
4812Set from the
4813.b \-p
4814command line flag or by the SMTP server code.
4815.ip $s
4816Sender's host name.
4817Set from the
4818.b \-p
4819command line flag or by the SMTP server code
4820(in which case it is set to the EHLO/HELO parameter).
4821.ip $t
4822A numeric representation of the current time in the format YYYYMMDDHHmm
4823(4 digit year 1900-9999, 2 digit month 01-12, 2 digit day 01-31,
48242 digit hours 00-23, 2 digit minutes 00-59).
4825.ip $u
4826The recipient user.
4827.ip $v
4828The version number of the
4829.i sendmail
4830binary.
4831.ip $w\(dd
4832The hostname of this site.
4833This is the root name of this host (but see below for caveats).
4834.ip $x
4835The full name of the sender.
4836.ip $z
4837The home directory of the recipient.
4838.ip $_
4839The validated sender address.
4840See also
4841.b ${client_resolve} .
4842.ip ${addr_type}
4843The type of the address which is currently being rewritten.
4844This macro contains up to three characters, the first
4845is either `e' or `h' for envelope/header address,
4846the second is a space,
4847and the third is either `s' or `r' for sender/recipient address.
4848.ip ${alg_bits}
4849The maximum keylength (in bits) of the symmetric encryption algorithm
4850used for a TLS connection.
4851This may be less than the effective keylength,
4852which is stored in
4853.b ${cipher_bits} ,
4854for ``export controlled'' algorithms.
4855.ip ${auth_authen}
4856The client's authentication credentials as determined by authentication
4857(only set if successful).
4858The format depends on the mechanism used, it might be just `user',
4859or `user@realm', or something similar (SMTP AUTH only).
4860.ip ${auth_author}
4861The authorization identity, i.e. the AUTH= parameter of the
4862.sm "SMTP MAIL"
4863command if supplied.
4864.ip ${auth_type}
4865The mechanism used for SMTP authentication
4866(only set if successful).
4867.ip ${auth_ssf}
4868The keylength (in bits) of the symmetric encryption algorithm
4869used for the security layer of a SASL mechanism.
4870.ip ${bodytype}
4871The message body type
4872(7BIT or 8BITMIME),
4873as determined from the envelope.
4874.ip ${cert_issuer}
4875The DN (distinguished name) of the CA (certificate authority)
4876that signed the presented certificate (the cert issuer)
4877(STARTTLS only).
4878.ip ${cert_md5}
4879The MD5 hash of the presented certificate (STARTTLS only).
4880.ip ${cert_subject}
4881The DN of the presented certificate (called the cert subject)
4882(STARTTLS only).
4883.ip ${cipher}
4884The cipher suite used for the connection, e.g., EDH-DSS-DES-CBC3-SHA,
4885EDH-RSA-DES-CBC-SHA, DES-CBC-MD5, DES-CBC3-SHA
4886(STARTTLS only).
4887.ip ${cipher_bits}
4888The effective keylength (in bits) of the symmetric encryption algorithm
4889used for a TLS connection.
4890.ip ${client_addr}
4891The IP address of the SMTP client.
4892IPv6 addresses are tagged with "IPv6:" before the address.
4893Defined in the SMTP server only.
4894.ip ${client_connections}
4895The number of open connections in the SMTP server for the client IP address.
4896.ip ${client_flags}
4897The flags specified by the
4898Modifier= part of
4899.b ClientPortOptions
4900where flags are separated from each other by spaces
4901and upper case flags are doubled.
4902That is,
4903Modifier=hA
4904will be represented as
4905"h AA" in
4906.b ${client_flags} ,
4907which is required for testing the flags in rulesets.
4908.ip ${client_name}
4909The host name of the SMTP client.
4910This may be the client's bracketed IP address
4911in the form [ nnn.nnn.nnn.nnn ] for IPv4
4912and [ IPv6:nnnn:...:nnnn ] for IPv6
4913if the client's
4914IP address is not resolvable, or if it is resolvable
4915but the IP address of the resolved hostname
4916doesn't match the original IP address.
4917Defined in the SMTP server only.
4918See also
4919.b ${client_resolve} .
4920.ip ${client_port}
4921The port number of the SMTP client.
4922Defined in the SMTP server only.
4923.ip ${client_ptr}
4924The result of the PTR lookup for the client IP address.
4925Note: this is the same as
4926.b ${client_name}
4927if and only if
4928.b ${client_resolve}
4929is OK.
4930Defined in the SMTP server only.
4931.ip ${client_rate}
4932The number of incoming connections for the client IP address
4933over the time interval specified by ConnectionRateWindowSize.
4934.ip ${client_resolve}
4935Holds the result of the resolve call for
4936.b ${client_name} .
4937Possible values are:
4938.(b
4939.ta 10n
4940OK resolved successfully
4941FAIL permanent lookup failure
4942FORGED forward lookup doesn't match reverse lookup
4943TEMP temporary lookup failure
4944.)b
4945Defined in the SMTP server only.
4946.i sendmail
4947performs a hostname lookup on the IP address of the connecting client.
4948Next the IP addresses of that hostname are looked up.
4949If the client IP address does not appear in that list,
4950then the hostname is maybe forged.
4951This is reflected as the value FORGED for
4952.b ${client_resolve}
4953and it also shows up in
4954.b $_
4955as "(may be forged)".
4956.ip ${cn_issuer}
4957The CN (common name) of the CA that signed the presented certificate
4958(STARTTLS only).
4959Note: if the CN cannot be extracted properly it will be replaced by
4960one of these strings based on the encountered error:
4961.(b
4962.ta 25n
4963BadCertificateContainsNUL CN contains a NUL character
4964BadCertificateTooLong CN is too long
4965BadCertificateUnknown CN could not be extracted
4966.)b
4967In the last case, some other (unspecific) error occurred.
4968.ip ${cn_subject}
4969The CN (common name) of the presented certificate
4970(STARTTLS only).
4971See
4972.b ${cn_issuer}
4973for possible replacements.
4974.ip ${currHeader}
4975Header value as quoted string
4976(possibly truncated to
4977.b MAXNAME ).
4978This macro is only available in header check rulesets.
4979.ip ${daemon_addr}
4980The IP address the daemon is listening on for connections.
4981.ip ${daemon_family}
4982The network family
4983if the daemon is accepting network connections.
4984Possible values include
4985.q inet ,
4986.q inet6 ,
4987.q iso ,
4988.q ns ,
4989.q x.25
4990.ip ${daemon_flags}
4991The flags for the daemon as specified by the
4992Modifier= part of
4993.b DaemonPortOptions
4994whereby the flags are separated from each other by spaces,
4995and upper case flags are doubled.
4996That is,
4997Modifier=Ea
4998will be represented as
4999"EE a" in
5000.b ${daemon_flags} ,
5001which is required for testing the flags in rulesets.
5002.ip ${daemon_info}
5003Some information about a daemon as a text string.
5004For example,
5005.q SMTP+queueing@00:30:00 .
5006.ip ${daemon_name}
5007The name of the daemon from
5008.b DaemonPortOptions
5009Name= suboption.
5010If this suboption is not set,
5011"Daemon#",
5012where # is the daemon number,
5013is used.
5014.ip ${daemon_port}
5015The port the daemon is accepting connection on.
5016Unless
5017.b DaemonPortOptions
5018is set, this will most likely be
5019.q 25 .
5020.ip ${deliveryMode}
5021The current delivery mode sendmail is using.
5022It is initially set to the value of the
5023.b DeliveryMode
5024option.
5025.ip ${envid}
5026The envelope id parameter (ENVID=) passed to sendmail as part of the envelope.
5027.ip ${hdrlen}
5028The length of the header value which is stored in
5029${currHeader} (before possible truncation).
5030If this value is greater than or equal to
5031.b MAXNAME
5032the header has been truncated.
5033.ip ${hdr_name}
5034The name of the header field for which the current header
5035check ruleset has been called.
5036This is useful for a default header check ruleset to get
5037the name of the header;
5038the macro is only available in header check rulesets.
5039.ip ${if_addr}
5040The IP address of the interface of an incoming connection
5041unless it is in the loopback net.
5042IPv6 addresses are tagged with "IPv6:" before the address.
5043.ip ${if_addr_out}
5044The IP address of the interface of an outgoing connection
5045unless it is in the loopback net.
5046IPv6 addresses are tagged with "IPv6:" before the address.
5047.ip ${if_family}
5048The IP family of the interface of an incoming connection
5049unless it is in the loopback net.
5050.ip ${if_family_out}
5051The IP family of the interface of an outgoing connection
5052unless it is in the loopback net.
5053.ip ${if_name}
5054The hostname associated with the interface of an incoming connection.
5055This macro can be used for
5056SmtpGreetingMessage and HReceived for virtual hosting.
5057For example:
5058.(b
5059O SmtpGreetingMessage=$?{if_name}${if_name}$|$j$. MTA
5060.)b
5061.ip ${if_name_out}
5062The name of the interface of an outgoing connection.
5063.ip ${load_avg}
5064The current load average.
5065.ip ${mail_addr}
5066The address part of the resolved triple of the address given for the
5067.sm "SMTP MAIL"
5068command.
5069Defined in the SMTP server only.
5070.ip ${mail_host}
5071The host from the resolved triple of the address given for the
5072.sm "SMTP MAIL"
5073command.
5074Defined in the SMTP server only.
5075.ip ${mail_mailer}
5076The mailer from the resolved triple of the address given for the
5077.sm "SMTP MAIL"
5078command.
5079Defined in the SMTP server only.
5080.ip ${msg_id}
5081The value of the Message-Id: header.
5082.ip ${msg_size}
5083The value of the SIZE= parameter,
5084i.e., usually the size of the message (in an ESMTP dialogue),
5085before the message has been collected, thereafter
5086the message size as computed by
5087.i sendmail
5088(and can be used in check_compat).
5089.ip ${nbadrcpts}
5090The number of bad recipients for a single message.
5091.ip ${nrcpts}
5092The number of validated recipients for a single message.
5093Note: since recipient validation happens after
5094.i check_rcpt
5095has been called, the value in this ruleset
5096is one less than what might be expected.
5097.ip ${ntries}
5098The number of delivery attempts.
5099.ip ${opMode}
5100The current operation mode (from the
5101.b \-b
5102flag).
5103.ip ${quarantine}
5104The quarantine reason for the envelope,
5105if it is quarantined.
5106.ip ${queue_interval}
5107The queue run interval given by the
5108.b \-q
5109flag.
5110For example,
5111.b \-q30m
5112would set
5113.b ${queue_interval}
5114to
5115.q 00:30:00 .
5116.ip ${rcpt_addr}
5117The address part of the resolved triple of the address given for the
5118.sm "SMTP RCPT"
5119command.
5120Defined in the SMTP server only after a RCPT command.
5121.ip ${rcpt_host}
5122The host from the resolved triple of the address given for the
5123.sm "SMTP RCPT"
5124command.
5125Defined in the SMTP server only after a RCPT command.
5126.ip ${rcpt_mailer}
5127The mailer from the resolved triple of the address given for the
5128.sm "SMTP RCPT"
5129command.
5130Defined in the SMTP server only after a RCPT command.
5131.ip ${server_addr}
5132The address of the server of the current outgoing SMTP connection.
5133For LMTP delivery the macro is set to the name of the mailer.
5134.ip ${server_name}
5135The name of the server of the current outgoing SMTP or LMTP connection.
5136.ip ${time}
5137The output of the
5138.i time (3)
5139function, i.e., the number of seconds since 0 hours, 0 minutes,
51400 seconds, January 1, 1970, Coordinated Universal Time (UTC).
5141.ip ${tls_version}
5142The TLS/SSL version used for the connection, e.g., TLSv1, SSLv3, SSLv2;
5143defined after STARTTLS has been used.
5144.ip ${total_rate}
5145The total number of incoming connections over the time interval specified
5146by ConnectionRateWindowSize.
5147.ip ${verify}
5148The result of the verification of the presented cert;
5149only defined after STARTTLS has been used (or attempted).
5150Possible values are:
5151.(b
5152.ta 13n
5153OK verification succeeded.
5154NO no cert presented.
5155NOT no cert requested.
5156FAIL cert presented but could not be verified,
5157 e.g., the signing CA is missing.
5158NONE STARTTLS has not been performed.
5159TEMP temporary error occurred.
5160PROTOCOL some protocol error occurred
5161 at the ESMTP level (not TLS).
5162SOFTWARE STARTTLS handshake failed,
5163 which is a fatal error for this session,
5164 the e-mail will be queued.
5165.)b
5166.pp
5167There are three types of dates that can be used.
5168The
5169.b $a
5170and
5171.b $b
5172macros are in RFC 822 format;
5173.b $a
5174is the time as extracted from the
5175.q Date:
5176line of the message
5177(if there was one),
5178and
5179.b $b
5180is the current date and time
5181(used for postmarks).
5182If no
5183.q Date:
5184line is found in the incoming message,
5185.b $a
5186is set to the current time also.
5187The
5188.b $d
5189macro is equivalent to the
5190.b $b
5191macro in UNIX
5192(ctime)
5193format.
5194.pp
5195The macros
5196.b $w ,
5197.b $j ,
5198and
5199.b $m
5200are set to the identity of this host.
5201.i Sendmail
5202tries to find the fully qualified name of the host
5203if at all possible;
5204it does this by calling
5205.i gethostname (2)
5206to get the current hostname
5207and then passing that to
5208.i gethostbyname (3)
5209which is supposed to return the canonical version of that host name.\**
5210.(f
5211\**For example, on some systems
5212.i gethostname
5213might return
5214.q foo
5215which would be mapped to
5216.q foo.bar.com
5217by
5218.i gethostbyname .
5219.)f
5220Assuming this is successful,
5221.b $j
5222is set to the fully qualified name
5223and
5224.b $m
5225is set to the domain part of the name
5226(everything after the first dot).
5227The
5228.b $w
5229macro is set to the first word
5230(everything before the first dot)
5231if you have a level 5 or higher configuration file;
5232otherwise, it is set to the same value as
5233.b $j .
5234If the canonification is not successful,
5235it is imperative that the config file set
5236.b $j
5237to the fully qualified domain name\**.
5238.(f
5239\**Older versions of sendmail didn't pre-define
5240.b $j
5241at all, so up until 8.6,
5242config files
5243.i always
5244had to define
5245.b $j .
5246.)f
5247.pp
5248The
5249.b $f
5250macro is the id of the sender
5251as originally determined;
5252when mailing to a specific host
5253the
5254.b $g
5255macro is set to the address of the sender
5256.ul
5257relative to the recipient.
5258For example,
5259if I send to
5260.q bollard@matisse.CS.Berkeley.EDU
5261from the machine
5262.q vangogh.CS.Berkeley.EDU
5263the
5264.b $f
5265macro will be
5266.q eric
5267and the
5268.b $g
5269macro will be
5270.q eric@vangogh.CS.Berkeley.EDU.
5271.pp
5272The
5273.b $x
5274macro is set to the full name of the sender.
5275This can be determined in several ways.
5276It can be passed as flag to
5277.i sendmail .
5278It can be defined in the
5279.sm NAME
5280environment variable.
5281The third choice is the value of the
5282.q Full-Name:
5283line in the header if it exists,
5284and the fourth choice is the comment field
5285of a
5286.q From:
5287line.
5288If all of these fail,
5289and if the message is being originated locally,
5290the full name is looked up in the
5291.i /etc/passwd
5292file.
5293.pp
5294When sending,
5295the
5296.b $h ,
5297.b $u ,
5298and
5299.b $z
5300macros get set to the host, user, and home directory
5301(if local)
5302of the recipient.
5303The first two are set from the
5304.b $@
5305and
5306.b $:
5307part of the rewriting rules, respectively.
5308.pp
5309The
5310.b $p
5311and
5312.b $t
5313macros are used to create unique strings
5314(e.g., for the
5315.q Message-Id:
5316field).
5317The
5318.b $i
5319macro is set to the queue id on this host;
5320if put into the timestamp line
5321it can be extremely useful for tracking messages.
5322The
5323.b $v
5324macro is set to be the version number of
5325.i sendmail ;
5326this is normally put in timestamps
5327and has been proven extremely useful for debugging.
5328.pp
5329The
5330.b $c
5331field is set to the
5332.q "hop count,"
5333i.e., the number of times this message has been processed.
5334This can be determined
5335by the
5336.b \-h
5337flag on the command line
5338or by counting the timestamps in the message.
5339.pp
5340The
5341.b $r
5342and
5343.b $s
5344fields are set to the protocol used to communicate with
5345.i sendmail
5346and the sending hostname.
5347They can be set together using the
5348.b \-p
5349command line flag or separately using the
5350.b \-M
5351or
5352.b \-oM
5353flags.
5354.pp
5355The
5356.b $_
5357is set to a validated sender host name.
5358If the sender is running an RFC 1413 compliant IDENT server
5359and the receiver has the IDENT protocol turned on,
5360it will include the user name on that host.
5361.pp
5362The
5363.b ${client_name} ,
5364.b ${client_addr} ,
5365and
5366.b ${client_port}
5367macros
5368are set to the name, address, and port number of the SMTP client
5369who is invoking
5370.i sendmail
5371as a server.
5372These can be used in the
5373.i check_*
5374rulesets (using the
5375.b $&
5376deferred evaluation form, of course!).
5377.sh 2 "C and F \*- Define Classes"
5378.pp
5379Classes of phrases may be defined
5380to match on the left hand side of rewriting rules,
5381where a
5382.q phrase
5383is a sequence of characters that does not contain space characters.
5384For example
5385a class of all local names for this site
5386might be created
5387so that attempts to send to oneself
5388can be eliminated.
5389These can either be defined directly in the configuration file
5390or read in from another file.
5391Classes are named as a single letter or a word in {braces}.
5392Class names beginning with lower case letters
5393and special characters are reserved for system use.
5394Classes defined in config files may be given names
5395from the set of upper case letters for short names
5396or beginning with an upper case letter for long names.
5397.pp
5398The syntax is:
5399.(b F
5400.b C \c
5401.i c\|phrase1
5402.i phrase2...
5403.br
5404.b F \c
5405.i c\|file
5406.br
5407.b F \c
5408.i c\||program
5409.br
5410.b F \c
5411.i c\|[mapkey]@mapclass:mapspec
5412.)b
5413The first form defines the class
5414.i c
5415to match any of the named words.
5416If
5417.i phrase1
5418or
5419.i phrase2
5420is another class,
5421e.g.,
5422.i $=S ,
5423the contents of class
5424.i S
5425are added to class
5426.i c .
5427It is permissible to split them among multiple lines;
5428for example, the two forms:
5429.(b
5430CHmonet ucbmonet
5431.)b
5432and
5433.(b
5434CHmonet
5435CHucbmonet
5436.)b
5437are equivalent.
5438The ``F'' forms
5439read the elements of the class
5440.i c
5441from the named
5442.i file ,
5443.i program ,
5444or
5445.i "map specification" .
5446Each element should be listed on a separate line.
5447To specify an optional file, use ``\-o'' between the class
5448name and the file name, e.g.,
5449.(b
5450Fc \-o /path/to/file
5451.)b
5452If the file can't be used,
5453.i sendmail
5454will not complain but silently ignore it.
5455The map form should be an optional map key, an at sign,
5456and a map class followed by the specification for that map.
5457Examples include:
5458.(b
5459F{VirtHosts}@ldap:\-k (&(objectClass=virtHosts)(host=*)) \-v host
5460F{MyClass}foo@hash:/etc/mail/classes
5461.)b
5462will fill the class
5463.b $={VirtHosts}
5464from an LDAP map lookup and
5465.b $={MyClass}
5466from a hash database map lookup of the
5467.b foo .
5468There is also a built-in schema that can be accessed by only specifying:
5469.(b
5470F{\c
5471.i ClassName }@LDAP
5472.)b
5473This will tell sendmail to use the default schema:
5474.(b
5475\-k (&(objectClass=sendmailMTAClass)
5476 (sendmailMTAClassName=\c
5477.i ClassName )
5478 (|(sendmailMTACluster=${sendmailMTACluster})
5479 (sendmailMTAHost=$j)))
5480\-v sendmailMTAClassValue
5481.)b
5482Note that the lookup is only done when sendmail is initially started.
5483.pp
5484Elements of classes can be accessed in rules using
5485.b $=
5486or
5487.b $~ .
5488The
5489.b $~
5490(match entries not in class)
5491only matches a single word;
5492multi-word entries in the class are ignored in this context.
5493.pp
5494Some classes have internal meaning to
5495.i sendmail :
5496.nr ii 0.5i
5497.\".ip $=b
5498.\"A set of Content-Types that will not have the newline character
5499.\"translated to CR-LF before encoding into base64 MIME.
5500.\"The class can have major times
5501.\"(e.g.,
5502.\".q image )
5503.\"or full types
5504.\"(such as
5505.\".q application/octet-stream ).
5506.\"The class is initialized with
5507.\".q application/octet-stream ,
5508.\".q image ,
5509.\".q audio ,
5510.\"and
5511.\".q video .
5512.ip $=e
5513contains the Content-Transfer-Encodings that can be 8\(->7 bit encoded.
5514It is predefined to contain
5515.q 7bit ,
5516.q 8bit ,
5517and
5518.q binary .
5519.ip $=k
5520set to be the same as
5521.b $k ,
5522that is, the UUCP node name.
5523.ip $=m
5524set to the set of domains by which this host is known,
5525initially just
5526.b $m .
5527.ip $=n
5528can be set to the set of MIME body types
5529that can never be eight to seven bit encoded.
5530It defaults to
5531.q multipart/signed .
5532Message types
5533.q message/*
5534and
5535.q multipart/*
5536are never encoded directly.
5537Multipart messages are always handled recursively.
5538The handling of message/* messages
5539are controlled by class
5540.b $=s .
5541.ip $=q
5542A set of Content-Types that will never be encoded as base64
5543(if they have to be encoded, they will be encoded as quoted-printable).
5544It can have primary types
5545(e.g.,
5546.q text )
5547or full types
5548(such as
5549.q text/plain ).
|
5550The class is initialized to have
5551.q text/plain
5552only.
| |
5553.ip $=s
5554contains the set of subtypes of message that can be treated recursively.
5555By default it contains only
5556.q rfc822 .
5557Other
5558.q message/*
5559types cannot be 8\(->7 bit encoded.
5560If a message containing eight bit data is sent to a seven bit host,
5561and that message cannot be encoded into seven bits,
5562it will be stripped to 7 bits.
5563.ip $=t
5564set to the set of trusted users by the
5565.b T
5566configuration line.
5567If you want to read trusted users from a file, use
5568.b Ft \c
5569.i /file/name .
5570.ip $=w
5571set to be the set of all names
5572this host is known by.
5573This can be used to match local hostnames.
5574.ip $={persistentMacros}
5575set to the macros that should be saved across queue runs.
5576Care should be taken when adding macro names to this class.
5577.pp
5578.i Sendmail
5579can be compiled to allow a
5580.i scanf (3)
5581string on the
5582.b F
5583line.
5584This lets you do simplistic parsing of text files.
5585For example, to read all the user names in your system
5586.i /etc/passwd
5587file into a class, use
5588.(b
5589FL/etc/passwd %[^:]
5590.)b
5591which reads every line up to the first colon.
5592.sh 2 "M \*- Define Mailer"
5593.pp
5594Programs and interfaces to mailers
5595are defined in this line.
5596The format is:
5597.(b F
5598.b M \c
5599.i name ,
5600{\c
5601.i field =\c
5602.i value \|}*
5603.)b
5604where
5605.i name
5606is the name of the mailer
5607(used internally only)
5608and the
5609.q field=name
5610pairs define attributes of the mailer.
5611Fields are:
5612.(b
5613.ta 1i
5614Path The pathname of the mailer
5615Flags Special flags for this mailer
5616Sender Rewriting set(s) for sender addresses
5617Recipient Rewriting set(s) for recipient addresses
5618recipients Maximum number of recipients per connection
5619Argv An argument vector to pass to this mailer
5620Eol The end-of-line string for this mailer
5621Maxsize The maximum message length to this mailer
5622maxmessages The maximum message deliveries per connection
5623Linelimit The maximum line length in the message body
5624Directory The working directory for the mailer
5625Userid The default user and group id to run as
5626Nice The nice(2) increment for the mailer
5627Charset The default character set for 8-bit characters
5628Type Type information for DSN diagnostics
5629Wait The maximum time to wait for the mailer
5630Queuegroup The default queue group for the mailer
5631/ The root directory for the mailer
5632.)b
5633Only the first character of the field name is checked
5634(it's case-sensitive).
5635.pp
5636The following flags may be set in the mailer description.
5637Any other flags may be used freely
5638to conditionally assign headers to messages
5639destined for particular mailers.
5640Flags marked with \(dg
5641are not interpreted by the
5642.i sendmail
5643binary;
5644these are the conventionally used to correlate to the flags portion
5645of the
5646.b H
5647line.
5648Flags marked with \(dd
5649apply to the mailers for the sender address
5650rather than the usual recipient mailers.
5651.nr ii 4n
5652.ip a
5653Run Extended SMTP (ESMTP) protocol (defined in RFCs 1869, 1652, and 1870).
5654This flag defaults on if the SMTP greeting message includes the word
5655.q ESMTP .
5656.ip A
5657Look up the user (address) part of the resolved mailer triple,
5658in the alias database.
5659Normally this is only set for local mailers.
5660.ip b
5661Force a blank line on the end of a message.
5662This is intended to work around some stupid versions of
5663/bin/mail
5664that require a blank line, but do not provide it themselves.
5665It would not normally be used on network mail.
5666.ip B
5667Strip leading backslashes (\e) off of the address;
5668this is a subset of the functionality of the
5669.b s
5670flag.
5671.ip c
5672Do not include comments in addresses.
5673This should only be used if you have to work around
5674a remote mailer that gets confused by comments.
5675This strips addresses of the form
5676.q "Phrase <address>"
5677or
5678.q "address (Comment)"
5679down to just
5680.q address .
5681.ip C\(dd
5682If mail is
5683.i received
5684from a mailer with this flag set,
5685any addresses in the header that do not have an at sign
5686(\c
5687.q @ )
5688after being rewritten by ruleset three
5689will have the
5690.q @domain
5691clause from the sender envelope address
5692tacked on.
5693This allows mail with headers of the form:
5694.(b
5695From: usera@hosta
5696To: userb@hostb, userc
5697.)b
5698to be rewritten as:
5699.(b
5700From: usera@hosta
5701To: userb@hostb, userc@hosta
5702.)b
5703automatically.
5704However, it doesn't really work reliably.
5705.ip d
5706Do not include angle brackets around route-address syntax addresses.
5707This is useful on mailers that are going to pass addresses to a shell
5708that might interpret angle brackets as I/O redirection.
5709However, it does not protect against other shell metacharacters.
5710Therefore, passing addresses to a shell should not be considered secure.
5711.ip D\(dg
5712This mailer wants a
5713.q Date:
5714header line.
5715.ip e
5716This mailer is expensive to connect to,
5717so try to avoid connecting normally;
5718any necessary connection will occur during a queue run.
5719See also option
5720.b HoldExpensive .
5721.ip E
5722Escape lines beginning with
5723.q From\0
5724in the message with a `>' sign.
5725.ip f
5726The mailer wants a
5727.b \-f
5728.i from
5729flag,
5730but only if this is a network forward operation
5731(i.e.,
5732the mailer will give an error
5733if the executing user
5734does not have special permissions).
5735.ip F\(dg
5736This mailer wants a
5737.q From:
5738header line.
5739.ip g
5740Normally,
5741.i sendmail
5742sends internally generated email (e.g., error messages)
5743using the null return address
5744as required by RFC 1123.
5745However, some mailers don't accept a null return address.
5746If necessary,
5747you can set the
5748.b g
5749flag to prevent
5750.i sendmail
5751from obeying the standards;
5752error messages will be sent as from the MAILER-DAEMON
5753(actually, the value of the
5754.b $n
5755macro).
5756.ip h
5757Upper case should be preserved in host names
5758(the $@ portion of the mailer triplet resolved from ruleset 0)
5759for this mailer.
5760.ip i
5761Do User Database rewriting on envelope sender address.
5762.ip I
5763This mailer will be speaking SMTP
5764to another
5765.i sendmail
5766\*-
5767as such it can use special protocol features.
5768This flag should not be used except for debugging purposes
5769because it uses
5770.b VERB
5771as SMTP command.
5772.ip j
5773Do User Database rewriting on recipients as well as senders.
5774.ip k
5775Normally when
5776.i sendmail
5777connects to a host via SMTP,
5778it checks to make sure that this isn't accidently the same host name
5779as might happen if
5780.i sendmail
5781is misconfigured or if a long-haul network interface is set in loopback mode.
5782This flag disables the loopback check.
5783It should only be used under very unusual circumstances.
5784.ip K
5785Currently unimplemented.
5786Reserved for chunking.
5787.ip l
5788This mailer is local
5789(i.e.,
5790final delivery will be performed).
5791.ip L
5792Limit the line lengths as specified in RFC 821.
5793This deprecated option should be replaced by the
5794.b L=
5795mail declaration.
5796For historic reasons, the
5797.b L
5798flag also sets the
5799.b 7
5800flag.
5801.ip m
5802This mailer can send to multiple users
5803on the same host
5804in one transaction.
5805When a
5806.b $u
5807macro occurs in the
5808.i argv
5809part of the mailer definition,
5810that field will be repeated as necessary
5811for all qualifying users.
5812Removing this flag can defeat duplicate supression on a remote site
5813as each recipient is sent in a separate transaction.
5814.ip M\(dg
5815This mailer wants a
5816.q Message-Id:
5817header line.
5818.ip n
5819Do not insert a UNIX-style
5820.q From
5821line on the front of the message.
5822.ip o
5823Always run as the owner of the recipient mailbox.
5824Normally
5825.i sendmail
5826runs as the sender for locally generated mail
5827or as
5828.q daemon
5829(actually, the user specified in the
5830.b u
5831option)
5832when delivering network mail.
5833The normal behavior is required by most local mailers,
5834which will not allow the envelope sender address
5835to be set unless the mailer is running as daemon.
5836This flag is ignored if the
5837.b S
5838flag is set.
5839.ip p
5840Use the route-addr style reverse-path in the SMTP
5841.q "MAIL FROM:"
5842command
5843rather than just the return address;
5844although this is required in RFC 821 section 3.1,
5845many hosts do not process reverse-paths properly.
5846Reverse-paths are officially discouraged by RFC 1123.
5847.ip P\(dg
5848This mailer wants a
5849.q Return-Path:
5850line.
5851.ip q
5852When an address that resolves to this mailer is verified
5853(SMTP VRFY command),
5854generate 250 responses instead of 252 responses.
5855This will imply that the address is local.
5856.ip r
5857Same as
5858.b f ,
5859but sends a
5860.b \-r
5861flag.
5862.ip R
5863Open SMTP connections from a
5864.q secure
5865port.
5866Secure ports aren't
5867(secure, that is)
5868except on UNIX machines,
5869so it is unclear that this adds anything.
5870.i sendmail
5871must be running as root to be able to use this flag.
5872.ip s
5873Strip quote characters (" and \e) off of the address
5874before calling the mailer.
5875.ip S
5876Don't reset the userid
5877before calling the mailer.
5878This would be used in a secure environment
5879where
5880.i sendmail
5881ran as root.
5882This could be used to avoid forged addresses.
5883If the
5884.b U=
5885field is also specified,
5886this flag causes the effective user id to be set to that user.
5887.ip u
5888Upper case should be preserved in user names for this mailer. Standards
5889require preservation of case in the local part of addresses, except for
5890those address for which your system accepts responsibility.
5891RFC 2142 provides a long list of addresses which should be case
5892insensitive.
5893If you use this flag, you may be violating RFC 2142.
5894Note that postmaster is always treated as a case insensitive address
5895regardless of this flag.
5896.ip U
5897This mailer wants UUCP-style
5898.q From
5899lines with the ugly
5900.q "remote from <host>"
5901on the end.
5902.ip w
5903The user must have a valid account on this machine,
5904i.e.,
5905.i getpwnam
5906must succeed.
5907If not, the mail is bounced.
5908See also the
5909.b MailBoxDatabase
5910option.
5911This is required to get
5912.q \&.forward
5913capability.
5914.ip W
5915Ignore long term host status information (see Section
5916"Persistent Host Status Information").
5917.ip x\(dg
5918This mailer wants a
5919.q Full-Name:
5920header line.
5921.ip X
5922This mailer wants to use the hidden dot algorithm as specified in RFC 821;
5923basically, any line beginning with a dot will have an extra dot prepended
5924(to be stripped at the other end).
5925This insures that lines in the message containing a dot
5926will not terminate the message prematurely.
5927.ip z
5928Run Local Mail Transfer Protocol (LMTP)
5929between
5930.i sendmail
5931and the local mailer.
5932This is a variant on SMTP
5933defined in RFC 2033
5934that is specifically designed for delivery to a local mailbox.
5935.ip Z
5936Apply DialDelay (if set) to this mailer.
5937.ip 0
5938Don't look up MX records for hosts sent via SMTP/LMTP.
5939Do not apply
5940.b FallbackMXhost
5941either.
5942.ip 1
5943Don't send null characters ('\\0') to this mailer.
5944.ip 2
5945Don't use ESMTP even if offered; this is useful for broken
5946systems that offer ESMTP but fail on EHLO (without recovering
5947when HELO is tried next).
5948.ip 3
5949Extend the list of characters converted to =XX notation
5950when converting to Quoted-Printable
5951to include those that don't map cleanly between ASCII and EBCDIC.
5952Useful if you have IBM mainframes on site.
5953.ip 5
5954If no aliases are found for this address,
5955pass the address through ruleset 5 for possible alternate resolution.
5956This is intended to forward the mail to an alternate delivery spot.
5957.ip 6
5958Strip headers to seven bits.
5959.ip 7
5960Strip all output to seven bits.
5961This is the default if the
5962.b L
5963flag is set.
5964Note that clearing this option is not
5965sufficient to get full eight bit data passed through
5966.i sendmail .
5967If the
5968.b 7
5969option is set, this is essentially always set,
5970since the eighth bit was stripped on input.
5971Note that this option will only impact messages
5972that didn't have 8\(->7 bit MIME conversions performed.
5973.ip 8
5974If set,
5975it is acceptable to send eight bit data to this mailer;
5976the usual attempt to do 8\(->7 bit MIME conversions will be bypassed.
5977.ip 9
5978If set,
5979do
5980.i limited
59817\(->8 bit MIME conversions.
5982These conversions are limited to text/plain data.
5983.ip :
5984Check addresses to see if they begin
5985.q :include: ;
5986if they do, convert them to the
5987.q *include*
5988mailer.
5989.ip |
5990Check addresses to see if they begin with a `|';
5991if they do, convert them to the
5992.q prog
5993mailer.
5994.ip /
5995Check addresses to see if they begin with a `/';
5996if they do, convert them to the
5997.q *file*
5998mailer.
5999.ip @
6000Look up addresses in the user database.
6001.ip %
6002Do not attempt delivery on initial receipt of a message
6003or on queue runs
6004unless the queued message is selected
6005using one of the -qI/-qR/-qS queue run modifiers
6006or an ETRN request.
6007.pp
6008Configuration files prior to level 6
6009assume the `A', `w', `5', `:', `|', `/', and `@' options
6010on the mailer named
6011.q local .
6012.pp
6013The mailer with the special name
6014.q error
6015can be used to generate a user error.
6016The (optional) host field is an exit status to be returned,
6017and the user field is a message to be printed.
6018The exit status may be numeric or one of the values
6019USAGE, NOUSER, NOHOST, UNAVAILABLE, SOFTWARE, TEMPFAIL, PROTOCOL, or CONFIG
6020to return the corresponding EX_ exit code,
6021or an enhanced error code as described in RFC 1893,
6022.ul
6023Enhanced Mail System Status Codes.
6024For example, the entry:
6025.(b
6026$#error $@ NOHOST $: Host unknown in this domain
6027.)b
6028on the RHS of a rule
6029will cause the specified error to be generated
6030and the
6031.q "Host unknown"
6032exit status to be returned
6033if the LHS matches.
6034This mailer is only functional in rulesets 0, 5,
6035or one of the check_* rulesets.
6036The host field can also contain the special token
6037.b quarantine
6038which instructs sendmail to quarantine the current message.
6039.pp
6040The mailer with the special name
6041.q discard
6042causes any mail sent to it to be discarded
6043but otherwise treated as though it were successfully delivered.
6044This mailer cannot be used in ruleset 0,
6045only in the various address checking rulesets.
6046.pp
6047The mailer named
6048.q local
6049.i must
6050be defined in every configuration file.
6051This is used to deliver local mail,
6052and is treated specially in several ways.
6053Additionally, three other mailers named
6054.q prog ,
6055.q *file* ,
6056and
6057.q *include*
6058may be defined to tune the delivery of messages to programs,
6059files,
6060and :include: lists respectively.
6061They default to:
6062.(b
6063Mprog, P=/bin/sh, F=lsoDq9, T=DNS/RFC822/X-Unix, A=sh \-c $u
6064M*file*, P=[FILE], F=lsDFMPEouq9, T=DNS/RFC822/X-Unix, A=FILE $u
6065M*include*, P=/dev/null, F=su, A=INCLUDE $u
6066.)b
6067.pp
6068Builtin pathnames are [FILE] and [IPC], the former is used for
6069delivery to files, the latter for delivery via interprocess communication.
6070For mailers that use [IPC] as pathname the argument vector (A=)
6071must start with TCP or FILE for delivery via a TCP or a Unix domain socket.
6072If TCP is used, the second argument must be the name of the host
6073to contact.
6074Optionally a third argument can be used to specify a port,
6075the default is smtp (port 25).
6076If FILE is used, the second argument must be the name of
6077the Unix domain socket.
6078.pp
6079If the argument vector does not contain $u then
6080.i sendmail
6081will speak SMTP (or LMTP if the mailer flag z is specified) to the mailer.
6082.pp
6083If no Eol field is defined, then the default is "\\r\\n" for
6084SMTP mailers and "\\n" of others.
6085.pp
6086The Sender and Recipient rewriting sets
6087may either be a simple ruleset id
6088or may be two ids separated by a slash;
6089if so, the first rewriting set is applied to envelope
6090addresses
6091and the second is applied to headers.
6092Setting any value to zero disables corresponding mailer-specific rewriting.
6093.pp
6094The Directory
6095is actually a colon-separated path of directories to try.
6096For example, the definition
6097.q D=$z:/
6098first tries to execute in the recipient's home directory;
6099if that is not available,
6100it tries to execute in the root of the filesystem.
6101This is intended to be used only on the
6102.q prog
6103mailer,
6104since some shells (such as
6105.i csh )
6106refuse to execute if they cannot read the current directory.
6107Since the queue directory is not normally readable by unprivileged users
6108.i csh
6109scripts as recipients can fail.
6110.pp
6111The Userid
6112specifies the default user and group id to run as,
6113overriding the
6114.b DefaultUser
6115option (q.v.).
6116If the
6117.b S
6118mailer flag is also specified,
6119this user and group will be set as the
6120effective uid and gid for the process.
6121This may be given as
6122.i user:group
6123to set both the user and group id;
6124either may be an integer or a symbolic name to be looked up
6125in the
6126.i passwd
6127and
6128.i group
6129files respectively.
6130If only a symbolic user name is specified,
6131the group id in the
6132.i passwd
6133file for that user is used as the group id.
6134.pp
6135The Charset field
6136is used when converting a message to MIME;
6137this is the character set used in the
6138Content-Type: header.
6139If this is not set, the
6140.b DefaultCharset
6141option is used,
6142and if that is not set, the value
6143.q unknown-8bit
6144is used.
6145.b WARNING:
6146this field applies to the sender's mailer,
6147not the recipient's mailer.
6148For example, if the envelope sender address
6149lists an address on the local network
6150and the recipient is on an external network,
6151the character set will be set from the Charset= field
6152for the local network mailer,
6153not that of the external network mailer.
6154.pp
6155The Type= field
6156sets the type information
6157used in MIME error messages
6158as defined by
6159RFC 1894.
6160It is actually three values separated by slashes:
6161the MTA-type (that is, the description of how hosts are named),
6162the address type (the description of e-mail addresses),
6163and the diagnostic type (the description of error diagnostic codes).
6164Each of these must be a registered value
6165or begin with
6166.q X\- .
6167The default is
6168.q dns/rfc822/smtp .
6169.pp
6170The m= field specifies the maximum number of messages
6171to attempt to deliver on a single SMTP or LMTP connection.
6172The default is infinite.
6173.pp
6174The r= field specifies the maximum number of recipients
6175to attempt to deliver in a single envelope.
6176It defaults to 100.
6177.pp
6178The /= field specifies a new root directory for the mailer. The path is
6179macro expanded and then passed to the
6180.q chroot
6181system call. The root directory is changed before the Directory field is
6182consulted or the uid is changed.
6183.pp
6184The Wait= field specifies the maximum time to wait for the
6185mailer to return after sending all data to it.
6186This applies to mailers that have been forked by
6187.i sendmail .
6188.pp
6189The Queuegroup= field specifies the default queue group in which
6190received mail should be queued.
6191This can be overridden by other means as explained in section
6192``Queue Groups and Queue Directories''.
6193.sh 2 "H \*- Define Header"
6194.pp
6195The format of the header lines that
6196.i sendmail
6197inserts into the message
6198are defined by the
6199.b H
6200line.
6201The syntax of this line is one of the following:
6202.(b F
6203.b H \c
6204.i hname \c
6205.b :
6206.i htemplate
6207.)b
6208.(b F
6209.b H [\c
6210.b ? \c
6211.i mflags \c
6212.b ? \c
6213.b ]\c
6214.i hname \c
6215.b :
6216.i htemplate
6217.)b
6218.(b F
6219.b H [\c
6220.b ?$ \c
6221.i {macro} \c
6222.b ? \c
6223.b ]\c
6224.i hname \c
6225.b :
6226.i htemplate
6227.)b
6228Continuation lines in this spec
6229are reflected directly into the outgoing message.
6230The
6231.i htemplate
6232is macro-expanded before insertion into the message.
6233If the
6234.i mflags
6235(surrounded by question marks)
6236are specified,
6237at least one of the specified flags
6238must be stated in the mailer definition
6239for this header to be automatically output.
6240If a
6241.i ${macro}
6242(surrounded by question marks)
6243is specified,
6244the header will be automatically output
6245if the macro is set.
6246The macro may be set using any of the normal methods,
6247including using the
6248.b macro
6249storage map in a ruleset.
6250If one of these headers is in the input
6251it is reflected to the output
6252regardless of these flags or macros.
6253Notice:
6254If a
6255.i ${macro}
6256is used to set a header, then it is useful to add that macro to class
6257.i $={persistentMacros}
6258which consists of the macros that should be saved across queue runs.
6259.pp
6260Some headers have special semantics
6261that will be described later.
6262.pp
6263A secondary syntax allows validation of headers as they are being read.
6264To enable validation, use:
6265.(b
6266.b H \c
6267.i Header \c
6268.b ": $>" \c
6269.i Ruleset
6270.b H \c
6271.i Header \c
6272.b ": $>+" \c
6273.i Ruleset
6274.)b
6275The indicated
6276.i Ruleset
6277is called for the specified
6278.i Header ,
6279and can return
6280.b $#error
6281to reject or quarantine the message or
6282.b $#discard
6283to discard the message
6284(as with the other
6285.b check_ *
6286rulesets).
6287The ruleset receives the header field-body as argument,
6288i.e., not the header field-name; see also
6289${hdr_name} and ${currHeader}.
6290The header is treated as a structured field,
6291that is,
6292text in parentheses is deleted before processing,
6293unless the second form
6294.b $>+
6295is used.
6296Note: only one ruleset can be associated with a header;
6297.i sendmail
6298will silently ignore multiple entries.
6299.pp
6300For example, the configuration lines:
6301.(b
6302HMessage-Id: $>CheckMessageId
6303
6304SCheckMessageId
6305R< $+ @ $+ > $@ OK
6306R$* $#error $: Illegal Message-Id header
6307.)b
6308would refuse any message that had a Message-Id: header of any of the
6309following forms:
6310.(b
6311Message-Id: <>
6312Message-Id: some text
6313Message-Id: <legal text@domain> extra crud
6314.)b
6315A default ruleset that is called for headers which don't have a
6316specific ruleset defined for them can be specified by:
6317.(b
6318.b H \c
6319.i * \c
6320.b ": $>" \c
6321.i Ruleset
6322.)b
6323or
6324.(b
6325.b H \c
6326.i * \c
6327.b ": $>+" \c
6328.i Ruleset
6329.)b
6330.sh 2 "O \*- Set Option"
6331.pp
6332There are a number of global options that
6333can be set from a configuration file.
6334Options are represented by full words;
6335some are also representable as single characters for back compatibility.
6336The syntax of this line is:
6337.(b F
6338.b O \0
6339.i option \c
6340.b = \c
6341.i value
6342.)b
6343This sets option
6344.i option
6345to be
6346.i value .
6347Note that there
6348.i must
6349be a space between the letter `O' and the name of the option.
6350An older version is:
6351.(b F
6352.b O \c
6353.i o\|value
6354.)b
6355where the option
6356.i o
6357is a single character.
6358Depending on the option,
6359.i value
6360may be a string, an integer,
6361a boolean
6362(with legal values
6363.q t ,
6364.q T ,
6365.q f ,
6366or
6367.q F ;
6368the default is TRUE),
6369or
6370a time interval.
6371.pp
6372All filenames used in options should be absolute paths,
6373i.e., starting with '/'.
6374Relative filenames most likely cause surprises during operation
6375(unless otherwise noted).
6376.pp
6377The options supported (with the old, one character names in brackets) are:
6378.nr ii 1i
6379.ip "AliasFile=\fIspec, spec, ...\fP"
6380[A]
6381Specify possible alias file(s).
6382Each
6383.i spec
6384should be in the format
6385``\c
6386.i class \c
6387.b :
6388.i info ''
6389where
6390.i class \c
6391.b :
6392is optional and defaults to ``implicit''.
6393Note that
6394.i info
6395is required for all
6396.i class es
6397except
6398.q ldap .
6399For the
6400.q ldap
6401class,
6402if
6403.i info
6404is not specified,
6405a default
6406.i info
6407value is used as follows:
6408.(b
6409\-k (&(objectClass=sendmailMTAAliasObject)
6410 (sendmailMTAAliasName=aliases)
6411 (|(sendmailMTACluster=${sendmailMTACluster})
6412 (sendmailMTAHost=$j))
6413 (sendmailMTAKey=%0))
6414\-v sendmailMTAAliasValue
6415.)b
6416Depending on how
6417.i sendmail
6418is compiled, valid classes are
6419.q implicit
6420(search through a compiled-in list of alias file types,
6421for back compatibility),
6422.q hash
6423(if
6424.sm NEWDB
6425is specified),
6426.q btree
6427(if
6428.sm NEWDB
6429is specified),
6430.q dbm
6431(if
6432.sm NDBM
6433is specified),
6434.q stab
6435(internal symbol table \*- not normally used
6436unless you have no other database lookup),
6437.q sequence
6438(use a sequence of maps
6439previously declared),
6440.q ldap
6441(if
6442.sm LDAPMAP
6443is specified),
6444or
6445.q nis
6446(if
6447.sm NIS
6448is specified).
6449If a list of
6450.i spec s
6451are provided,
6452.i sendmail
6453searches them in order.
6454.ip AliasWait=\fItimeout\fP
6455[a]
6456If set,
6457wait up to
6458.i timeout
6459(units default to minutes)
6460for an
6461.q @:@
6462entry to exist in the alias database
6463before starting up.
6464If it does not appear in the
6465.i timeout
6466interval issue a warning.
6467.ip AllowBogusHELO
6468[no short name]
6469If set, allow HELO SMTP commands that don't include a host name.
6470Setting this violates RFC 1123 section 5.2.5,
6471but is necessary to interoperate with several SMTP clients.
6472If there is a value, it is still checked for legitimacy.
6473.ip AuthMaxBits=\fIN\fP
6474[no short name]
6475Limit the maximum encryption strength for the security layer in
6476SMTP AUTH (SASL). Default is essentially unlimited.
6477This allows to turn off additional encryption in SASL if
6478STARTTLS is already encrypting the communication, because the
6479existing encryption strength is taken into account when choosing
6480an algorithm for the security layer.
6481For example, if STARTTLS is used and the symmetric cipher is 3DES,
6482then the the keylength (in bits) is 168.
6483Hence setting
6484.b AuthMaxBits
6485to 168 will disable any encryption in SASL.
6486.ip AuthMechanisms
6487[no short name]
6488List of authentication mechanisms for AUTH (separated by spaces).
6489The advertised list of authentication mechanisms will be the
6490intersection of this list and the list of available mechanisms as
6491determined by the Cyrus SASL library.
6492If STARTTLS is active, EXTERNAL will be added to this list.
6493In that case, the value of {cert_subject} is used as authentication id.
6494.ip AuthOptions
6495[no short name]
6496List of options for SMTP AUTH consisting of single characters
6497with intervening white space or commas.
6498.(b
6499.ta 4n
6500A Use the AUTH= parameter for the MAIL FROM
6501 command only when authentication succeeded.
6502 This can be used as a workaround for broken
6503 MTAs that do not implement RFC 2554 correctly.
6504a protection from active (non-dictionary) attacks
6505 during authentication exchange.
6506c require mechanisms which pass client credentials,
6507 and allow mechanisms which can pass credentials
6508 to do so.
6509d don't permit mechanisms susceptible to passive
6510 dictionary attack.
6511f require forward secrecy between sessions
6512 (breaking one won't help break next).
6513m require mechanisms which provide mutual authentication
6514 (only available if using Cyrus SASL v2 or later).
6515p don't permit mechanisms susceptible to simple
6516 passive attack (e.g., PLAIN, LOGIN), unless a
6517 security layer is active.
6518y don't permit mechanisms that allow anonymous login.
6519.)b
6520The first option applies to sendmail as a client, the others to a server.
6521Example:
6522.(b
6523O AuthOptions=p,y
6524.)b
6525would disallow ANONYMOUS as AUTH mechanism and would
6526allow PLAIN and LOGIN only if a security layer (e.g.,
6527provided by STARTTLS) is already active.
6528The options 'a', 'c', 'd', 'f', 'p', and 'y' refer to properties of the
6529selected SASL mechanisms.
6530Explanations of these properties can be found in the Cyrus SASL documentation.
6531.ip AuthRealm
6532[no short name]
6533The authentication realm that is passed to the Cyrus SASL library.
6534If no realm is specified,
6535.b $j
6536is used.
6537.ip BadRcptThrottle=\fIN\fP
6538[no short name]
6539If set and the specified number of recipients in a single SMTP
6540transaction have been rejected, sleep for one second after each subsequent
6541RCPT command in that transaction.
6542.ip BlankSub=\fIc\fP
6543[B]
6544Set the blank substitution character to
6545.i c .
6546Unquoted spaces in addresses are replaced by this character.
6547Defaults to space (i.e., no change is made).
6548.ip CACertPath
6549[no short name]
6550Path to directory with certificates of CAs.
6551This directory directory must contain the hashes of each CA certificate
6552as filenames (or as links to them).
6553.ip CACertFile
6554[no short name]
6555File containing one or more CA certificates;
6556see section about STARTTLS for more information.
6557.ip CheckAliases
6558[n]
6559Validate the RHS of aliases when rebuilding the alias database.
6560.ip CheckpointInterval=\fIN\fP
6561[C]
6562Checkpoints the queue every
6563.i N
6564(default 10)
6565addresses sent.
6566If your system crashes during delivery to a large list,
6567this prevents retransmission to any but the last
6568.i N
6569recipients.
6570.ip ClassFactor=\fIfact\fP
6571[z]
6572The indicated
6573.i fact or
6574is multiplied by the message class
6575(determined by the Precedence: field in the user header
6576and the
6577.b P
6578lines in the configuration file)
6579and subtracted from the priority.
6580Thus, messages with a higher Priority: will be favored.
6581Defaults to 1800.
6582.ip ClientCertFile
6583[no short name]
6584File containing the certificate of the client, i.e., this certificate
6585is used when
6586.i sendmail
6587acts as client (for STARTTLS).
6588.ip ClientKeyFile
6589[no short name]
6590File containing the private key belonging to the client certificate
6591(for STARTTLS if
6592.i sendmail
6593runs as client).
6594.ip ClientPortOptions=\fIoptions\fP
6595[O]
6596Set client SMTP options.
6597The options are
6598.i key=value
6599pairs separated by commas.
6600Known keys are:
6601.(b
6602.ta 1i
6603Port Name/number of source port for connection (defaults to any free port)
6604Addr Address mask (defaults INADDR_ANY)
6605Family Address family (defaults to INET)
6606SndBufSize Size of TCP send buffer
6607RcvBufSize Size of TCP receive buffer
6608Modifier Options (flags) for the client
6609.)b
6610The
6611.i Addr ess
| 5550.ip $=s
5551contains the set of subtypes of message that can be treated recursively.
5552By default it contains only
5553.q rfc822 .
5554Other
5555.q message/*
5556types cannot be 8\(->7 bit encoded.
5557If a message containing eight bit data is sent to a seven bit host,
5558and that message cannot be encoded into seven bits,
5559it will be stripped to 7 bits.
5560.ip $=t
5561set to the set of trusted users by the
5562.b T
5563configuration line.
5564If you want to read trusted users from a file, use
5565.b Ft \c
5566.i /file/name .
5567.ip $=w
5568set to be the set of all names
5569this host is known by.
5570This can be used to match local hostnames.
5571.ip $={persistentMacros}
5572set to the macros that should be saved across queue runs.
5573Care should be taken when adding macro names to this class.
5574.pp
5575.i Sendmail
5576can be compiled to allow a
5577.i scanf (3)
5578string on the
5579.b F
5580line.
5581This lets you do simplistic parsing of text files.
5582For example, to read all the user names in your system
5583.i /etc/passwd
5584file into a class, use
5585.(b
5586FL/etc/passwd %[^:]
5587.)b
5588which reads every line up to the first colon.
5589.sh 2 "M \*- Define Mailer"
5590.pp
5591Programs and interfaces to mailers
5592are defined in this line.
5593The format is:
5594.(b F
5595.b M \c
5596.i name ,
5597{\c
5598.i field =\c
5599.i value \|}*
5600.)b
5601where
5602.i name
5603is the name of the mailer
5604(used internally only)
5605and the
5606.q field=name
5607pairs define attributes of the mailer.
5608Fields are:
5609.(b
5610.ta 1i
5611Path The pathname of the mailer
5612Flags Special flags for this mailer
5613Sender Rewriting set(s) for sender addresses
5614Recipient Rewriting set(s) for recipient addresses
5615recipients Maximum number of recipients per connection
5616Argv An argument vector to pass to this mailer
5617Eol The end-of-line string for this mailer
5618Maxsize The maximum message length to this mailer
5619maxmessages The maximum message deliveries per connection
5620Linelimit The maximum line length in the message body
5621Directory The working directory for the mailer
5622Userid The default user and group id to run as
5623Nice The nice(2) increment for the mailer
5624Charset The default character set for 8-bit characters
5625Type Type information for DSN diagnostics
5626Wait The maximum time to wait for the mailer
5627Queuegroup The default queue group for the mailer
5628/ The root directory for the mailer
5629.)b
5630Only the first character of the field name is checked
5631(it's case-sensitive).
5632.pp
5633The following flags may be set in the mailer description.
5634Any other flags may be used freely
5635to conditionally assign headers to messages
5636destined for particular mailers.
5637Flags marked with \(dg
5638are not interpreted by the
5639.i sendmail
5640binary;
5641these are the conventionally used to correlate to the flags portion
5642of the
5643.b H
5644line.
5645Flags marked with \(dd
5646apply to the mailers for the sender address
5647rather than the usual recipient mailers.
5648.nr ii 4n
5649.ip a
5650Run Extended SMTP (ESMTP) protocol (defined in RFCs 1869, 1652, and 1870).
5651This flag defaults on if the SMTP greeting message includes the word
5652.q ESMTP .
5653.ip A
5654Look up the user (address) part of the resolved mailer triple,
5655in the alias database.
5656Normally this is only set for local mailers.
5657.ip b
5658Force a blank line on the end of a message.
5659This is intended to work around some stupid versions of
5660/bin/mail
5661that require a blank line, but do not provide it themselves.
5662It would not normally be used on network mail.
5663.ip B
5664Strip leading backslashes (\e) off of the address;
5665this is a subset of the functionality of the
5666.b s
5667flag.
5668.ip c
5669Do not include comments in addresses.
5670This should only be used if you have to work around
5671a remote mailer that gets confused by comments.
5672This strips addresses of the form
5673.q "Phrase <address>"
5674or
5675.q "address (Comment)"
5676down to just
5677.q address .
5678.ip C\(dd
5679If mail is
5680.i received
5681from a mailer with this flag set,
5682any addresses in the header that do not have an at sign
5683(\c
5684.q @ )
5685after being rewritten by ruleset three
5686will have the
5687.q @domain
5688clause from the sender envelope address
5689tacked on.
5690This allows mail with headers of the form:
5691.(b
5692From: usera@hosta
5693To: userb@hostb, userc
5694.)b
5695to be rewritten as:
5696.(b
5697From: usera@hosta
5698To: userb@hostb, userc@hosta
5699.)b
5700automatically.
5701However, it doesn't really work reliably.
5702.ip d
5703Do not include angle brackets around route-address syntax addresses.
5704This is useful on mailers that are going to pass addresses to a shell
5705that might interpret angle brackets as I/O redirection.
5706However, it does not protect against other shell metacharacters.
5707Therefore, passing addresses to a shell should not be considered secure.
5708.ip D\(dg
5709This mailer wants a
5710.q Date:
5711header line.
5712.ip e
5713This mailer is expensive to connect to,
5714so try to avoid connecting normally;
5715any necessary connection will occur during a queue run.
5716See also option
5717.b HoldExpensive .
5718.ip E
5719Escape lines beginning with
5720.q From\0
5721in the message with a `>' sign.
5722.ip f
5723The mailer wants a
5724.b \-f
5725.i from
5726flag,
5727but only if this is a network forward operation
5728(i.e.,
5729the mailer will give an error
5730if the executing user
5731does not have special permissions).
5732.ip F\(dg
5733This mailer wants a
5734.q From:
5735header line.
5736.ip g
5737Normally,
5738.i sendmail
5739sends internally generated email (e.g., error messages)
5740using the null return address
5741as required by RFC 1123.
5742However, some mailers don't accept a null return address.
5743If necessary,
5744you can set the
5745.b g
5746flag to prevent
5747.i sendmail
5748from obeying the standards;
5749error messages will be sent as from the MAILER-DAEMON
5750(actually, the value of the
5751.b $n
5752macro).
5753.ip h
5754Upper case should be preserved in host names
5755(the $@ portion of the mailer triplet resolved from ruleset 0)
5756for this mailer.
5757.ip i
5758Do User Database rewriting on envelope sender address.
5759.ip I
5760This mailer will be speaking SMTP
5761to another
5762.i sendmail
5763\*-
5764as such it can use special protocol features.
5765This flag should not be used except for debugging purposes
5766because it uses
5767.b VERB
5768as SMTP command.
5769.ip j
5770Do User Database rewriting on recipients as well as senders.
5771.ip k
5772Normally when
5773.i sendmail
5774connects to a host via SMTP,
5775it checks to make sure that this isn't accidently the same host name
5776as might happen if
5777.i sendmail
5778is misconfigured or if a long-haul network interface is set in loopback mode.
5779This flag disables the loopback check.
5780It should only be used under very unusual circumstances.
5781.ip K
5782Currently unimplemented.
5783Reserved for chunking.
5784.ip l
5785This mailer is local
5786(i.e.,
5787final delivery will be performed).
5788.ip L
5789Limit the line lengths as specified in RFC 821.
5790This deprecated option should be replaced by the
5791.b L=
5792mail declaration.
5793For historic reasons, the
5794.b L
5795flag also sets the
5796.b 7
5797flag.
5798.ip m
5799This mailer can send to multiple users
5800on the same host
5801in one transaction.
5802When a
5803.b $u
5804macro occurs in the
5805.i argv
5806part of the mailer definition,
5807that field will be repeated as necessary
5808for all qualifying users.
5809Removing this flag can defeat duplicate supression on a remote site
5810as each recipient is sent in a separate transaction.
5811.ip M\(dg
5812This mailer wants a
5813.q Message-Id:
5814header line.
5815.ip n
5816Do not insert a UNIX-style
5817.q From
5818line on the front of the message.
5819.ip o
5820Always run as the owner of the recipient mailbox.
5821Normally
5822.i sendmail
5823runs as the sender for locally generated mail
5824or as
5825.q daemon
5826(actually, the user specified in the
5827.b u
5828option)
5829when delivering network mail.
5830The normal behavior is required by most local mailers,
5831which will not allow the envelope sender address
5832to be set unless the mailer is running as daemon.
5833This flag is ignored if the
5834.b S
5835flag is set.
5836.ip p
5837Use the route-addr style reverse-path in the SMTP
5838.q "MAIL FROM:"
5839command
5840rather than just the return address;
5841although this is required in RFC 821 section 3.1,
5842many hosts do not process reverse-paths properly.
5843Reverse-paths are officially discouraged by RFC 1123.
5844.ip P\(dg
5845This mailer wants a
5846.q Return-Path:
5847line.
5848.ip q
5849When an address that resolves to this mailer is verified
5850(SMTP VRFY command),
5851generate 250 responses instead of 252 responses.
5852This will imply that the address is local.
5853.ip r
5854Same as
5855.b f ,
5856but sends a
5857.b \-r
5858flag.
5859.ip R
5860Open SMTP connections from a
5861.q secure
5862port.
5863Secure ports aren't
5864(secure, that is)
5865except on UNIX machines,
5866so it is unclear that this adds anything.
5867.i sendmail
5868must be running as root to be able to use this flag.
5869.ip s
5870Strip quote characters (" and \e) off of the address
5871before calling the mailer.
5872.ip S
5873Don't reset the userid
5874before calling the mailer.
5875This would be used in a secure environment
5876where
5877.i sendmail
5878ran as root.
5879This could be used to avoid forged addresses.
5880If the
5881.b U=
5882field is also specified,
5883this flag causes the effective user id to be set to that user.
5884.ip u
5885Upper case should be preserved in user names for this mailer. Standards
5886require preservation of case in the local part of addresses, except for
5887those address for which your system accepts responsibility.
5888RFC 2142 provides a long list of addresses which should be case
5889insensitive.
5890If you use this flag, you may be violating RFC 2142.
5891Note that postmaster is always treated as a case insensitive address
5892regardless of this flag.
5893.ip U
5894This mailer wants UUCP-style
5895.q From
5896lines with the ugly
5897.q "remote from <host>"
5898on the end.
5899.ip w
5900The user must have a valid account on this machine,
5901i.e.,
5902.i getpwnam
5903must succeed.
5904If not, the mail is bounced.
5905See also the
5906.b MailBoxDatabase
5907option.
5908This is required to get
5909.q \&.forward
5910capability.
5911.ip W
5912Ignore long term host status information (see Section
5913"Persistent Host Status Information").
5914.ip x\(dg
5915This mailer wants a
5916.q Full-Name:
5917header line.
5918.ip X
5919This mailer wants to use the hidden dot algorithm as specified in RFC 821;
5920basically, any line beginning with a dot will have an extra dot prepended
5921(to be stripped at the other end).
5922This insures that lines in the message containing a dot
5923will not terminate the message prematurely.
5924.ip z
5925Run Local Mail Transfer Protocol (LMTP)
5926between
5927.i sendmail
5928and the local mailer.
5929This is a variant on SMTP
5930defined in RFC 2033
5931that is specifically designed for delivery to a local mailbox.
5932.ip Z
5933Apply DialDelay (if set) to this mailer.
5934.ip 0
5935Don't look up MX records for hosts sent via SMTP/LMTP.
5936Do not apply
5937.b FallbackMXhost
5938either.
5939.ip 1
5940Don't send null characters ('\\0') to this mailer.
5941.ip 2
5942Don't use ESMTP even if offered; this is useful for broken
5943systems that offer ESMTP but fail on EHLO (without recovering
5944when HELO is tried next).
5945.ip 3
5946Extend the list of characters converted to =XX notation
5947when converting to Quoted-Printable
5948to include those that don't map cleanly between ASCII and EBCDIC.
5949Useful if you have IBM mainframes on site.
5950.ip 5
5951If no aliases are found for this address,
5952pass the address through ruleset 5 for possible alternate resolution.
5953This is intended to forward the mail to an alternate delivery spot.
5954.ip 6
5955Strip headers to seven bits.
5956.ip 7
5957Strip all output to seven bits.
5958This is the default if the
5959.b L
5960flag is set.
5961Note that clearing this option is not
5962sufficient to get full eight bit data passed through
5963.i sendmail .
5964If the
5965.b 7
5966option is set, this is essentially always set,
5967since the eighth bit was stripped on input.
5968Note that this option will only impact messages
5969that didn't have 8\(->7 bit MIME conversions performed.
5970.ip 8
5971If set,
5972it is acceptable to send eight bit data to this mailer;
5973the usual attempt to do 8\(->7 bit MIME conversions will be bypassed.
5974.ip 9
5975If set,
5976do
5977.i limited
59787\(->8 bit MIME conversions.
5979These conversions are limited to text/plain data.
5980.ip :
5981Check addresses to see if they begin
5982.q :include: ;
5983if they do, convert them to the
5984.q *include*
5985mailer.
5986.ip |
5987Check addresses to see if they begin with a `|';
5988if they do, convert them to the
5989.q prog
5990mailer.
5991.ip /
5992Check addresses to see if they begin with a `/';
5993if they do, convert them to the
5994.q *file*
5995mailer.
5996.ip @
5997Look up addresses in the user database.
5998.ip %
5999Do not attempt delivery on initial receipt of a message
6000or on queue runs
6001unless the queued message is selected
6002using one of the -qI/-qR/-qS queue run modifiers
6003or an ETRN request.
6004.pp
6005Configuration files prior to level 6
6006assume the `A', `w', `5', `:', `|', `/', and `@' options
6007on the mailer named
6008.q local .
6009.pp
6010The mailer with the special name
6011.q error
6012can be used to generate a user error.
6013The (optional) host field is an exit status to be returned,
6014and the user field is a message to be printed.
6015The exit status may be numeric or one of the values
6016USAGE, NOUSER, NOHOST, UNAVAILABLE, SOFTWARE, TEMPFAIL, PROTOCOL, or CONFIG
6017to return the corresponding EX_ exit code,
6018or an enhanced error code as described in RFC 1893,
6019.ul
6020Enhanced Mail System Status Codes.
6021For example, the entry:
6022.(b
6023$#error $@ NOHOST $: Host unknown in this domain
6024.)b
6025on the RHS of a rule
6026will cause the specified error to be generated
6027and the
6028.q "Host unknown"
6029exit status to be returned
6030if the LHS matches.
6031This mailer is only functional in rulesets 0, 5,
6032or one of the check_* rulesets.
6033The host field can also contain the special token
6034.b quarantine
6035which instructs sendmail to quarantine the current message.
6036.pp
6037The mailer with the special name
6038.q discard
6039causes any mail sent to it to be discarded
6040but otherwise treated as though it were successfully delivered.
6041This mailer cannot be used in ruleset 0,
6042only in the various address checking rulesets.
6043.pp
6044The mailer named
6045.q local
6046.i must
6047be defined in every configuration file.
6048This is used to deliver local mail,
6049and is treated specially in several ways.
6050Additionally, three other mailers named
6051.q prog ,
6052.q *file* ,
6053and
6054.q *include*
6055may be defined to tune the delivery of messages to programs,
6056files,
6057and :include: lists respectively.
6058They default to:
6059.(b
6060Mprog, P=/bin/sh, F=lsoDq9, T=DNS/RFC822/X-Unix, A=sh \-c $u
6061M*file*, P=[FILE], F=lsDFMPEouq9, T=DNS/RFC822/X-Unix, A=FILE $u
6062M*include*, P=/dev/null, F=su, A=INCLUDE $u
6063.)b
6064.pp
6065Builtin pathnames are [FILE] and [IPC], the former is used for
6066delivery to files, the latter for delivery via interprocess communication.
6067For mailers that use [IPC] as pathname the argument vector (A=)
6068must start with TCP or FILE for delivery via a TCP or a Unix domain socket.
6069If TCP is used, the second argument must be the name of the host
6070to contact.
6071Optionally a third argument can be used to specify a port,
6072the default is smtp (port 25).
6073If FILE is used, the second argument must be the name of
6074the Unix domain socket.
6075.pp
6076If the argument vector does not contain $u then
6077.i sendmail
6078will speak SMTP (or LMTP if the mailer flag z is specified) to the mailer.
6079.pp
6080If no Eol field is defined, then the default is "\\r\\n" for
6081SMTP mailers and "\\n" of others.
6082.pp
6083The Sender and Recipient rewriting sets
6084may either be a simple ruleset id
6085or may be two ids separated by a slash;
6086if so, the first rewriting set is applied to envelope
6087addresses
6088and the second is applied to headers.
6089Setting any value to zero disables corresponding mailer-specific rewriting.
6090.pp
6091The Directory
6092is actually a colon-separated path of directories to try.
6093For example, the definition
6094.q D=$z:/
6095first tries to execute in the recipient's home directory;
6096if that is not available,
6097it tries to execute in the root of the filesystem.
6098This is intended to be used only on the
6099.q prog
6100mailer,
6101since some shells (such as
6102.i csh )
6103refuse to execute if they cannot read the current directory.
6104Since the queue directory is not normally readable by unprivileged users
6105.i csh
6106scripts as recipients can fail.
6107.pp
6108The Userid
6109specifies the default user and group id to run as,
6110overriding the
6111.b DefaultUser
6112option (q.v.).
6113If the
6114.b S
6115mailer flag is also specified,
6116this user and group will be set as the
6117effective uid and gid for the process.
6118This may be given as
6119.i user:group
6120to set both the user and group id;
6121either may be an integer or a symbolic name to be looked up
6122in the
6123.i passwd
6124and
6125.i group
6126files respectively.
6127If only a symbolic user name is specified,
6128the group id in the
6129.i passwd
6130file for that user is used as the group id.
6131.pp
6132The Charset field
6133is used when converting a message to MIME;
6134this is the character set used in the
6135Content-Type: header.
6136If this is not set, the
6137.b DefaultCharset
6138option is used,
6139and if that is not set, the value
6140.q unknown-8bit
6141is used.
6142.b WARNING:
6143this field applies to the sender's mailer,
6144not the recipient's mailer.
6145For example, if the envelope sender address
6146lists an address on the local network
6147and the recipient is on an external network,
6148the character set will be set from the Charset= field
6149for the local network mailer,
6150not that of the external network mailer.
6151.pp
6152The Type= field
6153sets the type information
6154used in MIME error messages
6155as defined by
6156RFC 1894.
6157It is actually three values separated by slashes:
6158the MTA-type (that is, the description of how hosts are named),
6159the address type (the description of e-mail addresses),
6160and the diagnostic type (the description of error diagnostic codes).
6161Each of these must be a registered value
6162or begin with
6163.q X\- .
6164The default is
6165.q dns/rfc822/smtp .
6166.pp
6167The m= field specifies the maximum number of messages
6168to attempt to deliver on a single SMTP or LMTP connection.
6169The default is infinite.
6170.pp
6171The r= field specifies the maximum number of recipients
6172to attempt to deliver in a single envelope.
6173It defaults to 100.
6174.pp
6175The /= field specifies a new root directory for the mailer. The path is
6176macro expanded and then passed to the
6177.q chroot
6178system call. The root directory is changed before the Directory field is
6179consulted or the uid is changed.
6180.pp
6181The Wait= field specifies the maximum time to wait for the
6182mailer to return after sending all data to it.
6183This applies to mailers that have been forked by
6184.i sendmail .
6185.pp
6186The Queuegroup= field specifies the default queue group in which
6187received mail should be queued.
6188This can be overridden by other means as explained in section
6189``Queue Groups and Queue Directories''.
6190.sh 2 "H \*- Define Header"
6191.pp
6192The format of the header lines that
6193.i sendmail
6194inserts into the message
6195are defined by the
6196.b H
6197line.
6198The syntax of this line is one of the following:
6199.(b F
6200.b H \c
6201.i hname \c
6202.b :
6203.i htemplate
6204.)b
6205.(b F
6206.b H [\c
6207.b ? \c
6208.i mflags \c
6209.b ? \c
6210.b ]\c
6211.i hname \c
6212.b :
6213.i htemplate
6214.)b
6215.(b F
6216.b H [\c
6217.b ?$ \c
6218.i {macro} \c
6219.b ? \c
6220.b ]\c
6221.i hname \c
6222.b :
6223.i htemplate
6224.)b
6225Continuation lines in this spec
6226are reflected directly into the outgoing message.
6227The
6228.i htemplate
6229is macro-expanded before insertion into the message.
6230If the
6231.i mflags
6232(surrounded by question marks)
6233are specified,
6234at least one of the specified flags
6235must be stated in the mailer definition
6236for this header to be automatically output.
6237If a
6238.i ${macro}
6239(surrounded by question marks)
6240is specified,
6241the header will be automatically output
6242if the macro is set.
6243The macro may be set using any of the normal methods,
6244including using the
6245.b macro
6246storage map in a ruleset.
6247If one of these headers is in the input
6248it is reflected to the output
6249regardless of these flags or macros.
6250Notice:
6251If a
6252.i ${macro}
6253is used to set a header, then it is useful to add that macro to class
6254.i $={persistentMacros}
6255which consists of the macros that should be saved across queue runs.
6256.pp
6257Some headers have special semantics
6258that will be described later.
6259.pp
6260A secondary syntax allows validation of headers as they are being read.
6261To enable validation, use:
6262.(b
6263.b H \c
6264.i Header \c
6265.b ": $>" \c
6266.i Ruleset
6267.b H \c
6268.i Header \c
6269.b ": $>+" \c
6270.i Ruleset
6271.)b
6272The indicated
6273.i Ruleset
6274is called for the specified
6275.i Header ,
6276and can return
6277.b $#error
6278to reject or quarantine the message or
6279.b $#discard
6280to discard the message
6281(as with the other
6282.b check_ *
6283rulesets).
6284The ruleset receives the header field-body as argument,
6285i.e., not the header field-name; see also
6286${hdr_name} and ${currHeader}.
6287The header is treated as a structured field,
6288that is,
6289text in parentheses is deleted before processing,
6290unless the second form
6291.b $>+
6292is used.
6293Note: only one ruleset can be associated with a header;
6294.i sendmail
6295will silently ignore multiple entries.
6296.pp
6297For example, the configuration lines:
6298.(b
6299HMessage-Id: $>CheckMessageId
6300
6301SCheckMessageId
6302R< $+ @ $+ > $@ OK
6303R$* $#error $: Illegal Message-Id header
6304.)b
6305would refuse any message that had a Message-Id: header of any of the
6306following forms:
6307.(b
6308Message-Id: <>
6309Message-Id: some text
6310Message-Id: <legal text@domain> extra crud
6311.)b
6312A default ruleset that is called for headers which don't have a
6313specific ruleset defined for them can be specified by:
6314.(b
6315.b H \c
6316.i * \c
6317.b ": $>" \c
6318.i Ruleset
6319.)b
6320or
6321.(b
6322.b H \c
6323.i * \c
6324.b ": $>+" \c
6325.i Ruleset
6326.)b
6327.sh 2 "O \*- Set Option"
6328.pp
6329There are a number of global options that
6330can be set from a configuration file.
6331Options are represented by full words;
6332some are also representable as single characters for back compatibility.
6333The syntax of this line is:
6334.(b F
6335.b O \0
6336.i option \c
6337.b = \c
6338.i value
6339.)b
6340This sets option
6341.i option
6342to be
6343.i value .
6344Note that there
6345.i must
6346be a space between the letter `O' and the name of the option.
6347An older version is:
6348.(b F
6349.b O \c
6350.i o\|value
6351.)b
6352where the option
6353.i o
6354is a single character.
6355Depending on the option,
6356.i value
6357may be a string, an integer,
6358a boolean
6359(with legal values
6360.q t ,
6361.q T ,
6362.q f ,
6363or
6364.q F ;
6365the default is TRUE),
6366or
6367a time interval.
6368.pp
6369All filenames used in options should be absolute paths,
6370i.e., starting with '/'.
6371Relative filenames most likely cause surprises during operation
6372(unless otherwise noted).
6373.pp
6374The options supported (with the old, one character names in brackets) are:
6375.nr ii 1i
6376.ip "AliasFile=\fIspec, spec, ...\fP"
6377[A]
6378Specify possible alias file(s).
6379Each
6380.i spec
6381should be in the format
6382``\c
6383.i class \c
6384.b :
6385.i info ''
6386where
6387.i class \c
6388.b :
6389is optional and defaults to ``implicit''.
6390Note that
6391.i info
6392is required for all
6393.i class es
6394except
6395.q ldap .
6396For the
6397.q ldap
6398class,
6399if
6400.i info
6401is not specified,
6402a default
6403.i info
6404value is used as follows:
6405.(b
6406\-k (&(objectClass=sendmailMTAAliasObject)
6407 (sendmailMTAAliasName=aliases)
6408 (|(sendmailMTACluster=${sendmailMTACluster})
6409 (sendmailMTAHost=$j))
6410 (sendmailMTAKey=%0))
6411\-v sendmailMTAAliasValue
6412.)b
6413Depending on how
6414.i sendmail
6415is compiled, valid classes are
6416.q implicit
6417(search through a compiled-in list of alias file types,
6418for back compatibility),
6419.q hash
6420(if
6421.sm NEWDB
6422is specified),
6423.q btree
6424(if
6425.sm NEWDB
6426is specified),
6427.q dbm
6428(if
6429.sm NDBM
6430is specified),
6431.q stab
6432(internal symbol table \*- not normally used
6433unless you have no other database lookup),
6434.q sequence
6435(use a sequence of maps
6436previously declared),
6437.q ldap
6438(if
6439.sm LDAPMAP
6440is specified),
6441or
6442.q nis
6443(if
6444.sm NIS
6445is specified).
6446If a list of
6447.i spec s
6448are provided,
6449.i sendmail
6450searches them in order.
6451.ip AliasWait=\fItimeout\fP
6452[a]
6453If set,
6454wait up to
6455.i timeout
6456(units default to minutes)
6457for an
6458.q @:@
6459entry to exist in the alias database
6460before starting up.
6461If it does not appear in the
6462.i timeout
6463interval issue a warning.
6464.ip AllowBogusHELO
6465[no short name]
6466If set, allow HELO SMTP commands that don't include a host name.
6467Setting this violates RFC 1123 section 5.2.5,
6468but is necessary to interoperate with several SMTP clients.
6469If there is a value, it is still checked for legitimacy.
6470.ip AuthMaxBits=\fIN\fP
6471[no short name]
6472Limit the maximum encryption strength for the security layer in
6473SMTP AUTH (SASL). Default is essentially unlimited.
6474This allows to turn off additional encryption in SASL if
6475STARTTLS is already encrypting the communication, because the
6476existing encryption strength is taken into account when choosing
6477an algorithm for the security layer.
6478For example, if STARTTLS is used and the symmetric cipher is 3DES,
6479then the the keylength (in bits) is 168.
6480Hence setting
6481.b AuthMaxBits
6482to 168 will disable any encryption in SASL.
6483.ip AuthMechanisms
6484[no short name]
6485List of authentication mechanisms for AUTH (separated by spaces).
6486The advertised list of authentication mechanisms will be the
6487intersection of this list and the list of available mechanisms as
6488determined by the Cyrus SASL library.
6489If STARTTLS is active, EXTERNAL will be added to this list.
6490In that case, the value of {cert_subject} is used as authentication id.
6491.ip AuthOptions
6492[no short name]
6493List of options for SMTP AUTH consisting of single characters
6494with intervening white space or commas.
6495.(b
6496.ta 4n
6497A Use the AUTH= parameter for the MAIL FROM
6498 command only when authentication succeeded.
6499 This can be used as a workaround for broken
6500 MTAs that do not implement RFC 2554 correctly.
6501a protection from active (non-dictionary) attacks
6502 during authentication exchange.
6503c require mechanisms which pass client credentials,
6504 and allow mechanisms which can pass credentials
6505 to do so.
6506d don't permit mechanisms susceptible to passive
6507 dictionary attack.
6508f require forward secrecy between sessions
6509 (breaking one won't help break next).
6510m require mechanisms which provide mutual authentication
6511 (only available if using Cyrus SASL v2 or later).
6512p don't permit mechanisms susceptible to simple
6513 passive attack (e.g., PLAIN, LOGIN), unless a
6514 security layer is active.
6515y don't permit mechanisms that allow anonymous login.
6516.)b
6517The first option applies to sendmail as a client, the others to a server.
6518Example:
6519.(b
6520O AuthOptions=p,y
6521.)b
6522would disallow ANONYMOUS as AUTH mechanism and would
6523allow PLAIN and LOGIN only if a security layer (e.g.,
6524provided by STARTTLS) is already active.
6525The options 'a', 'c', 'd', 'f', 'p', and 'y' refer to properties of the
6526selected SASL mechanisms.
6527Explanations of these properties can be found in the Cyrus SASL documentation.
6528.ip AuthRealm
6529[no short name]
6530The authentication realm that is passed to the Cyrus SASL library.
6531If no realm is specified,
6532.b $j
6533is used.
6534.ip BadRcptThrottle=\fIN\fP
6535[no short name]
6536If set and the specified number of recipients in a single SMTP
6537transaction have been rejected, sleep for one second after each subsequent
6538RCPT command in that transaction.
6539.ip BlankSub=\fIc\fP
6540[B]
6541Set the blank substitution character to
6542.i c .
6543Unquoted spaces in addresses are replaced by this character.
6544Defaults to space (i.e., no change is made).
6545.ip CACertPath
6546[no short name]
6547Path to directory with certificates of CAs.
6548This directory directory must contain the hashes of each CA certificate
6549as filenames (or as links to them).
6550.ip CACertFile
6551[no short name]
6552File containing one or more CA certificates;
6553see section about STARTTLS for more information.
6554.ip CheckAliases
6555[n]
6556Validate the RHS of aliases when rebuilding the alias database.
6557.ip CheckpointInterval=\fIN\fP
6558[C]
6559Checkpoints the queue every
6560.i N
6561(default 10)
6562addresses sent.
6563If your system crashes during delivery to a large list,
6564this prevents retransmission to any but the last
6565.i N
6566recipients.
6567.ip ClassFactor=\fIfact\fP
6568[z]
6569The indicated
6570.i fact or
6571is multiplied by the message class
6572(determined by the Precedence: field in the user header
6573and the
6574.b P
6575lines in the configuration file)
6576and subtracted from the priority.
6577Thus, messages with a higher Priority: will be favored.
6578Defaults to 1800.
6579.ip ClientCertFile
6580[no short name]
6581File containing the certificate of the client, i.e., this certificate
6582is used when
6583.i sendmail
6584acts as client (for STARTTLS).
6585.ip ClientKeyFile
6586[no short name]
6587File containing the private key belonging to the client certificate
6588(for STARTTLS if
6589.i sendmail
6590runs as client).
6591.ip ClientPortOptions=\fIoptions\fP
6592[O]
6593Set client SMTP options.
6594The options are
6595.i key=value
6596pairs separated by commas.
6597Known keys are:
6598.(b
6599.ta 1i
6600Port Name/number of source port for connection (defaults to any free port)
6601Addr Address mask (defaults INADDR_ANY)
6602Family Address family (defaults to INET)
6603SndBufSize Size of TCP send buffer
6604RcvBufSize Size of TCP receive buffer
6605Modifier Options (flags) for the client
6606.)b
6607The
6608.i Addr ess
|
6612mask may be a numeric address in dot notation
| 6609mask may be a numeric address in IPv4 dot notation or IPv6 colon notation
|
6613or a network name.
| 6610or a network name.
|
| 6611Note that if a network name is specified,
6612only the first IP address returned for it will be used.
6613This may cause indeterminate behavior for network names
6614that resolve to multiple addresses.
6615Therefore, use of an address is recommended.
|
6614.i Modifier
6615can be the following character:
6616.(b
6617.ta 1i
6618h use name of interface for HELO command
6619A don't use AUTH when sending e-mail
6620S don't use STARTTLS when sending e-mail
6621.)b
6622If ``h'' is set, the name corresponding to the outgoing interface
6623address (whether chosen via the Connection parameter or
6624the default) is used for the HELO/EHLO command.
6625However, the name must not start with a square bracket
6626and it must contain at least one dot.
6627This is a simple test whether the name is not
6628an IP address (in square brackets) but a qualified hostname.
6629Note that multiple ClientPortOptions settings are allowed
6630in order to give settings for each protocol family
6631(e.g., one for Family=inet and one for Family=inet6).
6632A restriction placed on one family only affects
6633outgoing connections on that particular family.
6634.ip ColonOkInAddr
6635[no short name]
6636If set, colons are acceptable in e-mail addresses
6637(e.g.,
6638.q host:user ).
6639If not set, colons indicate the beginning of a RFC 822 group construct
6640(\c
6641.q "groupname: member1, member2, ... memberN;" ).
6642Doubled colons are always acceptable
6643(\c
6644.q nodename::user )
6645and proper route-addr nesting is understood
6646(\c
6647.q <@relay:user@host> ).
6648Furthermore, this option defaults on if the configuration version level
6649is less than 6 (for back compatibility).
6650However, it must be off for full compatibility with RFC 822.
6651.ip ConnectionCacheSize=\fIN\fP
6652[k]
6653The maximum number of open connections that will be cached at a time.
6654The default is one.
6655This delays closing the current connection until
6656either this invocation of
6657.i sendmail
6658needs to connect to another host
6659or it terminates.
6660Setting it to zero defaults to the old behavior,
6661that is, connections are closed immediately.
6662Since this consumes file descriptors,
6663the connection cache should be kept small:
66644 is probably a practical maximum.
6665.ip ConnectionCacheTimeout=\fItimeout\fP
6666[K]
6667The maximum amount of time a cached connection will be permitted to idle
6668without activity.
6669If this time is exceeded,
6670the connection is immediately closed.
6671This value should be small (on the order of ten minutes).
6672Before
6673.i sendmail
6674uses a cached connection,
6675it always sends a RSET command
6676to check the connection;
6677if this fails, it reopens the connection.
6678This keeps your end from failing if the other end times out.
6679The point of this option is to be a good network neighbor
6680and avoid using up excessive resources
6681on the other end.
6682The default is five minutes.
6683.ip ConnectOnlyTo=\fIaddress\fP
6684[no short name]
6685This can be used to
6686override the connection address (for testing purposes).
6687.ip ConnectionRateThrottle=\fIN\fP
6688[no short name]
6689If set to a positive value,
6690allow no more than
6691.i N
6692incoming connections in a one second period per daemon.
6693This is intended to flatten out peaks
6694and allow the load average checking to cut in.
6695Defaults to zero (no limits).
6696.ip ConnectionRateWindowSize=\fIN\fP
6697[no short name]
6698Define the length of the interval for which
6699the number of incoming connections is maintained.
6700The default is 60 seconds.
6701.ip ControlSocketName=\fIname\fP
6702[no short name]
6703Name of the control socket for daemon management.
6704A running
6705.i sendmail
6706daemon can be controlled through this named socket.
6707Available commands are:
6708.i help,
6709.i mstat,
6710.i restart,
6711.i shutdown,
6712and
6713.i status.
6714The
6715.i status
6716command returns the current number of daemon children,
6717the maximum number of daemon children,
6718the free disk space (in blocks) of the queue directory,
6719and the load average of the machine expressed as an integer.
6720If not set, no control socket will be available.
6721Solaris and pre-4.4BSD kernel users should see the note in sendmail/README .
6722.ip CRLFile=\fIname\fP
6723[no short name]
6724Name of file that contains certificate
6725revocation status, useful for X.509v3 authentication.
6726CRL checking requires at least OpenSSL version 0.9.7.
6727Note: if a CRLFile is specified but the file is unusable,
6728STARTTLS is disabled.
6729.ip DHParameters
6730Possible values are:
6731.(b
6732.ta 1i
67335 use 512 bit prime
67341 use 1024 bit prime
6735none do not use Diffie-Hellman
6736NAME load prime from file
6737.)b
6738This is only required if a ciphersuite containing DSA/DH is used.
6739If ``5'' is selected, then precomputed, fixed primes are used.
6740This is the default for the client side.
6741If ``1'' is selected, then prime values are computed during startup.
6742This is the default for the server side.
6743Note: this operation can take a significant amount of time on a
6744slow machine (several seconds), but it is only done once at startup.
6745If ``none'' is selected, then TLS ciphersuites containing DSA/DH
6746cannot be used.
6747If a file name is specified (which must be an absolute path),
6748then the primes are read from it.
6749.ip DaemonPortOptions=\fIoptions\fP
6750[O]
6751Set server SMTP options.
6752Each instance of
6753.b DaemonPortOptions
6754leads to an additional incoming socket.
6755The options are
6756.i key=value
6757pairs.
6758Known keys are:
6759.(b
6760.ta 1i
6761Name User-definable name for the daemon (defaults to "Daemon#")
6762Port Name/number of listening port (defaults to "smtp")
6763Addr Address mask (defaults INADDR_ANY)
6764Family Address family (defaults to INET)
6765InputMailFilters List of input mail filters for the daemon
6766Listen Size of listen queue (defaults to 10)
6767Modifier Options (flags) for the daemon
6768SndBufSize Size of TCP send buffer
6769RcvBufSize Size of TCP receive buffer
6770children maximum number of children per daemon, see \fBMaxDaemonChildren\fP.
6771DeliveryMode Delivery mode per daemon, see \fBDeliveryMode\fP.
6772refuseLA RefuseLA per daemon
6773delayLA DelayLA per daemon
6774queueLA QueueLA per daemon
6775.)b
6776The
6777.i Name
6778key is used for error messages and logging.
6779The
6780.i Addr ess
| 6616.i Modifier
6617can be the following character:
6618.(b
6619.ta 1i
6620h use name of interface for HELO command
6621A don't use AUTH when sending e-mail
6622S don't use STARTTLS when sending e-mail
6623.)b
6624If ``h'' is set, the name corresponding to the outgoing interface
6625address (whether chosen via the Connection parameter or
6626the default) is used for the HELO/EHLO command.
6627However, the name must not start with a square bracket
6628and it must contain at least one dot.
6629This is a simple test whether the name is not
6630an IP address (in square brackets) but a qualified hostname.
6631Note that multiple ClientPortOptions settings are allowed
6632in order to give settings for each protocol family
6633(e.g., one for Family=inet and one for Family=inet6).
6634A restriction placed on one family only affects
6635outgoing connections on that particular family.
6636.ip ColonOkInAddr
6637[no short name]
6638If set, colons are acceptable in e-mail addresses
6639(e.g.,
6640.q host:user ).
6641If not set, colons indicate the beginning of a RFC 822 group construct
6642(\c
6643.q "groupname: member1, member2, ... memberN;" ).
6644Doubled colons are always acceptable
6645(\c
6646.q nodename::user )
6647and proper route-addr nesting is understood
6648(\c
6649.q <@relay:user@host> ).
6650Furthermore, this option defaults on if the configuration version level
6651is less than 6 (for back compatibility).
6652However, it must be off for full compatibility with RFC 822.
6653.ip ConnectionCacheSize=\fIN\fP
6654[k]
6655The maximum number of open connections that will be cached at a time.
6656The default is one.
6657This delays closing the current connection until
6658either this invocation of
6659.i sendmail
6660needs to connect to another host
6661or it terminates.
6662Setting it to zero defaults to the old behavior,
6663that is, connections are closed immediately.
6664Since this consumes file descriptors,
6665the connection cache should be kept small:
66664 is probably a practical maximum.
6667.ip ConnectionCacheTimeout=\fItimeout\fP
6668[K]
6669The maximum amount of time a cached connection will be permitted to idle
6670without activity.
6671If this time is exceeded,
6672the connection is immediately closed.
6673This value should be small (on the order of ten minutes).
6674Before
6675.i sendmail
6676uses a cached connection,
6677it always sends a RSET command
6678to check the connection;
6679if this fails, it reopens the connection.
6680This keeps your end from failing if the other end times out.
6681The point of this option is to be a good network neighbor
6682and avoid using up excessive resources
6683on the other end.
6684The default is five minutes.
6685.ip ConnectOnlyTo=\fIaddress\fP
6686[no short name]
6687This can be used to
6688override the connection address (for testing purposes).
6689.ip ConnectionRateThrottle=\fIN\fP
6690[no short name]
6691If set to a positive value,
6692allow no more than
6693.i N
6694incoming connections in a one second period per daemon.
6695This is intended to flatten out peaks
6696and allow the load average checking to cut in.
6697Defaults to zero (no limits).
6698.ip ConnectionRateWindowSize=\fIN\fP
6699[no short name]
6700Define the length of the interval for which
6701the number of incoming connections is maintained.
6702The default is 60 seconds.
6703.ip ControlSocketName=\fIname\fP
6704[no short name]
6705Name of the control socket for daemon management.
6706A running
6707.i sendmail
6708daemon can be controlled through this named socket.
6709Available commands are:
6710.i help,
6711.i mstat,
6712.i restart,
6713.i shutdown,
6714and
6715.i status.
6716The
6717.i status
6718command returns the current number of daemon children,
6719the maximum number of daemon children,
6720the free disk space (in blocks) of the queue directory,
6721and the load average of the machine expressed as an integer.
6722If not set, no control socket will be available.
6723Solaris and pre-4.4BSD kernel users should see the note in sendmail/README .
6724.ip CRLFile=\fIname\fP
6725[no short name]
6726Name of file that contains certificate
6727revocation status, useful for X.509v3 authentication.
6728CRL checking requires at least OpenSSL version 0.9.7.
6729Note: if a CRLFile is specified but the file is unusable,
6730STARTTLS is disabled.
6731.ip DHParameters
6732Possible values are:
6733.(b
6734.ta 1i
67355 use 512 bit prime
67361 use 1024 bit prime
6737none do not use Diffie-Hellman
6738NAME load prime from file
6739.)b
6740This is only required if a ciphersuite containing DSA/DH is used.
6741If ``5'' is selected, then precomputed, fixed primes are used.
6742This is the default for the client side.
6743If ``1'' is selected, then prime values are computed during startup.
6744This is the default for the server side.
6745Note: this operation can take a significant amount of time on a
6746slow machine (several seconds), but it is only done once at startup.
6747If ``none'' is selected, then TLS ciphersuites containing DSA/DH
6748cannot be used.
6749If a file name is specified (which must be an absolute path),
6750then the primes are read from it.
6751.ip DaemonPortOptions=\fIoptions\fP
6752[O]
6753Set server SMTP options.
6754Each instance of
6755.b DaemonPortOptions
6756leads to an additional incoming socket.
6757The options are
6758.i key=value
6759pairs.
6760Known keys are:
6761.(b
6762.ta 1i
6763Name User-definable name for the daemon (defaults to "Daemon#")
6764Port Name/number of listening port (defaults to "smtp")
6765Addr Address mask (defaults INADDR_ANY)
6766Family Address family (defaults to INET)
6767InputMailFilters List of input mail filters for the daemon
6768Listen Size of listen queue (defaults to 10)
6769Modifier Options (flags) for the daemon
6770SndBufSize Size of TCP send buffer
6771RcvBufSize Size of TCP receive buffer
6772children maximum number of children per daemon, see \fBMaxDaemonChildren\fP.
6773DeliveryMode Delivery mode per daemon, see \fBDeliveryMode\fP.
6774refuseLA RefuseLA per daemon
6775delayLA DelayLA per daemon
6776queueLA QueueLA per daemon
6777.)b
6778The
6779.i Name
6780key is used for error messages and logging.
6781The
6782.i Addr ess
|
6781mask may be a numeric address in dot notation
| 6783mask may be a numeric address in IPv4 dot notation or IPv6 colon notation
|
6782or a network name.
| 6784or a network name.
|
| 6785Note that if a network name is specified,
6786only the first IP address returned for it will be used.
6787This may cause indeterminate behavior for network names
6788that resolve to multiple addresses.
6789Therefore, use of an address is recommended.
|
6783The
6784.i Family
6785key defaults to INET (IPv4).
6786IPv6 users who wish to also accept IPv6 connections
6787should add additional Family=inet6
6788.b DaemonPortOptions
6789lines.
6790The
6791.i InputMailFilters
6792key overrides the default list of input mail filters listed in the
6793.b InputMailFilters
6794option.
6795If multiple input mail filters are required, they must be separated
6796by semicolons (not commas).
6797.i Modifier
6798can be a sequence (without any delimiters)
6799of the following characters:
6800.(b
6801.ta 1i
6802a always require authentication
6803b bind to interface through which mail has been received
6804c perform hostname canonification (.cf)
6805f require fully qualified hostname (.cf)
6806s Run smtps (SMTP over SSL) instead of smtp
6807u allow unqualified addresses (.cf)
6808A disable AUTH (overrides 'a' modifier)
6809C don't perform hostname canonification
6810E disallow ETRN (see RFC 2476)
6811O optional; if opening the socket fails ignore it
6812S don't offer STARTTLS
6813.)b
6814That is, one way to specify a message submission agent (MSA) that
6815always requires authentication is:
6816.(b
6817O DaemonPortOptions=Name=MSA, Port=587, M=Ea
6818.)b
6819The modifiers that are marked with "(.cf)" have only
6820effect in the standard configuration file, in which
6821they are available via
6822.b ${daemon_flags} .
6823Notice: Do
6824.b not
6825use the ``a'' modifier on a public accessible MTA!
6826It should only be used for a MSA that is accessed by authorized
6827users for initial mail submission.
6828Users must authenticate to use a MSA which has this option turned on.
6829The flags ``c'' and ``C'' can change the default for
6830hostname canonification in the
6831.i sendmail.cf
6832file.
6833See the relevant documentation for
6834.sm FEATURE(nocanonify) .
6835The modifier ``f'' disallows addresses of the form
6836.b user@host
6837unless they are submitted directly.
6838The flag ``u'' allows unqualified sender addresses,
6839i.e., those without @host.
6840``b'' forces sendmail to bind to the interface
6841through which the e-mail has been
6842received for the outgoing connection.
6843.b WARNING:
6844Use ``b''
6845only if outgoing mail can be routed through the incoming connection's
6846interface to its destination. No attempt is made to catch problems due to a
6847misconfiguration of this parameter, use it only for virtual hosting
6848where each virtual interface can connect to every possible location.
6849This will also override possible settings via
6850.b ClientPortOptions.
6851Note,
6852.i sendmail
6853will listen on a new socket
6854for each occurence of the
6855.b DaemonPortOptions
6856option in a configuration file.
6857The modifier ``O'' causes sendmail to ignore a socket
6858if it can't be opened.
6859This applies to failures from the socket(2) and bind(2) calls.
6860.ip DefaultAuthInfo
6861[no short name]
6862Filename that contains default authentication information for outgoing
6863connections. This file must contain the user id, the authorization id,
6864the password (plain text), the realm and the list of mechanisms to use
6865on separate lines and must be readable by
6866root (or the trusted user) only.
6867If no realm is specified,
6868.b $j
6869is used.
6870If no mechanisms are specified, the list given by
6871.b AuthMechanisms
6872is used.
6873Notice: this option is deprecated and will be removed in future versions.
6874Moreover, it doesn't work for the MSP since it can't read the file
6875(the file must not be group/world-readable otherwise
6876.i sendmail
6877will complain).
6878Use the authinfo ruleset instead which provides more control over
6879the usage of the data anyway.
6880.ip DefaultCharSet=\fIcharset\fP
6881[no short name]
6882When a message that has 8-bit characters but is not in MIME format
6883is converted to MIME
6884(see the EightBitMode option)
6885a character set must be included in the Content-Type: header.
6886This character set is normally set from the Charset= field
6887of the mailer descriptor.
6888If that is not set, the value of this option is used.
6889If this option is not set, the value
6890.q unknown-8bit
6891is used.
6892.ip DataFileBufferSize=\fIthreshold\fP
6893[no short name]
6894Set the
6895.i threshold ,
6896in bytes,
6897before a memory-based
6898queue data file
6899becomes disk-based.
6900The default is 4096 bytes.
6901.ip DeadLetterDrop=\fIfile\fP
6902[no short name]
6903Defines the location of the system-wide dead.letter file,
6904formerly hardcoded to /usr/tmp/dead.letter.
6905If this option is not set (the default),
6906sendmail will not attempt to save to a system-wide dead.letter file
6907in the event
6908it cannot bounce the mail to the user or postmaster.
6909Instead, it will rename the qf file
6910as it has in the past
6911when the dead.letter file could not be opened.
6912.ip DefaultUser=\fIuser:group\fP
6913[u]
6914Set the default userid for mailers to
6915.i user:group .
6916If
6917.i group
6918is omitted and
6919.i user
6920is a user name
6921(as opposed to a numeric user id)
6922the default group listed in the /etc/passwd file for that user is used
6923as the default group.
6924Both
6925.i user
6926and
6927.i group
6928may be numeric.
6929Mailers without the
6930.i S
6931flag in the mailer definition
6932will run as this user.
6933Defaults to 1:1.
6934The value can also be given as a symbolic user name.\**
6935.(f
6936\**The old
6937.b g
6938option has been combined into the
6939.b DefaultUser
6940option.
6941.)f
6942.ip DelayLA=\fILA\fP
6943[no short name]
6944When the system load average exceeds
6945.i LA ,
6946.i sendmail
6947will sleep for one second on most SMTP commands and
6948before accepting connections.
6949.ip DeliverByMin=\fItime\fP
6950[0]
6951Set minimum time for Deliver By SMTP Service Extension (RFC 2852).
6952If 0, no time is listed, if less than 0, the extension is not offered,
6953if greater than 0, it is listed as minimum time
6954for the EHLO keyword DELIVERBY.
6955.ip DeliveryMode=\fIx\fP
6956[d]
6957Deliver in mode
6958.i x .
6959Legal modes are:
6960.(b
6961.ta 4n
6962i Deliver interactively (synchronously)
6963b Deliver in background (asynchronously)
6964q Just queue the message (deliver during queue run)
6965d Defer delivery and all map lookups (deliver during queue run)
6966.)b
6967Defaults to ``b'' if no option is specified,
6968``i'' if it is specified but given no argument
6969(i.e., ``Od'' is equivalent to ``Odi'').
6970The
6971.b \-v
6972command line flag sets this to
6973.b i .
6974Note: for internal reasons,
6975``i'' does not work
6976if a milter is enabled which can reject or delete recipients.
6977In that case the mode will be changed to ``b''.
6978.ip DialDelay=\fIsleeptime\fP
6979[no short name]
6980Dial-on-demand network connections can see timeouts
6981if a connection is opened before the call is set up.
6982If this is set to an interval and a connection times out
6983on the first connection being attempted
6984.i sendmail
6985will sleep for this amount of time and try again.
6986This should give your system time to establish the connection
6987to your service provider.
6988Units default to seconds, so
6989.q DialDelay=5
6990uses a five second delay.
6991Defaults to zero
6992(no retry).
6993This delay only applies to mailers which have the
6994Z flag set.
6995.ip DirectSubmissionModifiers=\fImodifiers\fP
6996Defines
6997.b ${daemon_flags}
6998for direct (command line) submissions.
6999If not set,
7000.b ${daemon_flags}
7001is either "CC f" if the option
7002.b \-G
7003is used or "c u" otherwise.
7004Note that only the the "CC", "c", "f", and "u" flags are checked.
7005.ip DontBlameSendmail=\fIoption,option,...\fP
7006[no short name]
7007In order to avoid possible cracking attempts
7008caused by world- and group-writable files and directories,
7009.i sendmail
7010does paranoid checking when opening most of its support files.
7011If for some reason you absolutely must run with,
7012for example,
7013a group-writable
7014.i /etc
7015directory,
7016then you will have to turn off this checking
7017(at the cost of making your system more vulnerable to attack).
7018The possible arguments have been described earlier.
7019The details of these flags are described above.
7020.\"XXX should have more here!!! XXX
7021.b "Use of this option is not recommended."
7022.ip DontExpandCnames
7023[no short name]
7024The standards say that all host addresses used in a mail message
7025must be fully canonical.
7026For example, if your host is named
7027.q Cruft.Foo.ORG
7028and also has an alias of
7029.q FTP.Foo.ORG ,
7030the former name must be used at all times.
7031This is enforced during host name canonification
7032($[ ... $] lookups).
7033If this option is set, the protocols are ignored and the
7034.q wrong
7035thing is done.
7036However, the IETF is moving toward changing this standard,
7037so the behavior may become acceptable.
7038Please note that hosts downstream may still rewrite the address
7039to be the true canonical name however.
7040.ip DontInitGroups
7041[no short name]
7042If set,
7043.i sendmail
7044will avoid using the initgroups(3) call.
7045If you are running NIS,
7046this causes a sequential scan of the groups.byname map,
7047which can cause your NIS server to be badly overloaded in a large domain.
7048The cost of this is that the only group found for users
7049will be their primary group (the one in the password file),
7050which will make file access permissions somewhat more restrictive.
7051Has no effect on systems that don't have group lists.
7052.ip DontProbeInterfaces
7053[no short name]
7054.i Sendmail
7055normally finds the names of all interfaces active on your machine
7056when it starts up
7057and adds their name to the
7058.b $=w
7059class of known host aliases.
7060If you have a large number of virtual interfaces
7061or if your DNS inverse lookups are slow
7062this can be time consuming.
7063This option turns off that probing.
7064However, you will need to be certain to include all variant names
7065in the
7066.b $=w
7067class by some other mechanism.
7068If set to
7069.b loopback ,
7070loopback interfaces (e.g., lo0) will not be probed.
7071.ip DontPruneRoutes
7072[R]
7073Normally,
7074.i sendmail
7075tries to eliminate any unnecessary explicit routes
7076when sending an error message
7077(as discussed in RFC 1123 \(sc 5.2.6).
7078For example,
7079when sending an error message to
7080.(b
7081<@known1,@known2,@known3:user@unknown>
7082.)b
7083.i sendmail
7084will strip off the
7085.q @known1,@known2
7086in order to make the route as direct as possible.
7087However, if the
7088.b R
7089option is set, this will be disabled,
7090and the mail will be sent to the first address in the route,
7091even if later addresses are known.
7092This may be useful if you are caught behind a firewall.
7093.ip DoubleBounceAddress=\fIerror-address\fP
7094[no short name]
7095If an error occurs when sending an error message,
7096send the error report
7097(termed a
7098.q "double bounce"
7099because it is an error
7100.q bounce
7101that occurs when trying to send another error
7102.q bounce )
7103to the indicated address.
7104The address is macro expanded
7105at the time of delivery.
7106If not set, defaults to
7107.q postmaster .
7108If set to an empty string, double bounces are dropped.
7109.ip EightBitMode=\fIaction\fP
7110[8]
7111Set handling of eight-bit data.
7112There are two kinds of eight-bit data:
7113that declared as such using the
7114.b BODY=8BITMIME
7115ESMTP declaration or the
7116.b \-B8BITMIME
7117command line flag,
7118and undeclared 8-bit data, that is,
7119input that just happens to be eight bits.
7120There are three basic operations that can happen:
7121undeclared 8-bit data can be automatically converted to 8BITMIME,
7122undeclared 8-bit data can be passed as-is without conversion to MIME
7123(``just send 8''),
7124and declared 8-bit data can be converted to 7-bits
7125for transmission to a non-8BITMIME mailer.
7126The possible
7127.i action s
7128are:
7129.(b
7130.\" r Reject undeclared 8-bit data;
7131.\" don't convert 8BITMIME\(->7BIT (``reject'')
7132 s Reject undeclared 8-bit data (``strict'')
7133.\" do convert 8BITMIME\(->7BIT (``strict'')
7134.\" c Convert undeclared 8-bit data to MIME;
7135.\" don't convert 8BITMIME\(->7BIT (``convert'')
7136 m Convert undeclared 8-bit data to MIME (``mime'')
7137.\" do convert 8BITMIME\(->7BIT (``mime'')
7138.\" j Pass undeclared 8-bit data;
7139.\" don't convert 8BITMIME\(->7BIT (``just send 8'')
7140 p Pass undeclared 8-bit data (``pass'')
7141.\" do convert 8BITMIME\(->7BIT (``pass'')
7142.\" a Adaptive algorithm: see below
7143.)b
7144.\"The adaptive algorithm is to accept 8-bit data,
7145.\"converting it to 8BITMIME only if the receiver understands that,
7146.\"otherwise just passing it as undeclared 8-bit data;
7147.\"8BITMIME\(->7BIT conversions are done.
7148In all cases properly declared 8BITMIME data will be converted to 7BIT
7149as needed.
7150.ip ErrorHeader=\fIfile-or-message\fP
7151[E]
7152Prepend error messages with the indicated message.
7153If it begins with a slash,
7154it is assumed to be the pathname of a file
7155containing a message (this is the recommended setting).
7156Otherwise, it is a literal message.
7157The error file might contain the name, email address, and/or phone number
7158of a local postmaster who could provide assistance
7159to end users.
7160If the option is missing or null,
7161or if it names a file which does not exist or which is not readable,
7162no message is printed.
7163.ip ErrorMode=\fIx\fP
7164[e]
7165Dispose of errors using mode
7166.i x .
7167The values for
7168.i x
7169are:
7170.(b
7171p Print error messages (default)
7172q No messages, just give exit status
7173m Mail back errors
7174w Write back errors (mail if user not logged in)
7175e Mail back errors (when applicable) and give zero exit stat always
7176.)b
7177Note that the last mode,
7178.q e ,
7179is for Berknet error processing and
7180should not be used in normal circumstances.
7181Note, too, that mode
7182.q q ,
7183only applies to errors recognized before sendmail forks for
7184background delivery.
7185.ip FallbackMXhost=\fIfallbackhost\fP
7186[V]
7187If specified, the
7188.i fallbackhost
7189acts like a very low priority MX
7190on every host.
7191MX records will be looked up for this host,
7192unless the name is surrounded by square brackets.
7193This is intended to be used by sites with poor network connectivity.
7194Messages which are undeliverable due to temporary address failures
7195(e.g., DNS failure)
7196also go to the FallbackMXhost.
7197.ip FallBackSmartHost=\fIhostname\fP
7198If specified, the
7199.i FallBackSmartHost
7200will be used in a last-ditch effort for each host.
7201This is intended to be used by sites with "fake internal DNS",
7202e.g., a company whose DNS accurately reflects the world
7203inside that company's domain but not outside.
7204.ip FastSplit
7205[no short name]
7206If set to a value greater than zero (the default is one),
7207it suppresses the MX lookups on addresses
7208when they are initially sorted, i.e., for the first delivery attempt.
7209This usually results in faster envelope splitting unless the MX records
7210are readily available in a local DNS cache.
7211To enforce initial sorting based on MX records set
7212.b FastSplit
7213to zero.
7214If the mail is submitted directly from the command line, then
7215the value also limits the number of processes to deliver the envelopes;
7216if more envelopes are created they are only queued up
7217and must be taken care of by a queue run.
7218Since the default submission method is via SMTP (either from a MUA
7219or via the MSP), the value of
7220.b FastSplit
7221is seldom used to limit the number of processes to deliver the envelopes.
7222.ip ForkEachJob
7223[Y]
7224If set,
7225deliver each job that is run from the queue in a separate process.
7226.ip ForwardPath=\fIpath\fP
7227[J]
7228Set the path for searching for users' .forward files.
7229The default is
7230.q $z/.forward .
7231Some sites that use the automounter may prefer to change this to
7232.q /var/forward/$u
7233to search a file with the same name as the user in a system directory.
7234It can also be set to a sequence of paths separated by colons;
7235.i sendmail
7236stops at the first file it can successfully and safely open.
7237For example,
7238.q /var/forward/$u:$z/.forward
7239will search first in /var/forward/\c
7240.i username
7241and then in
7242.i ~username /.forward
7243(but only if the first file does not exist).
7244.ip HeloName=\fIname\fP
7245[no short name]
7246Set the name to be used for HELO/EHLO (instead of $j).
7247.ip HoldExpensive
7248[c]
7249If an outgoing mailer is marked as being expensive,
7250don't connect immediately.
7251.ip HostsFile=\fIpath\fP
7252[no short name]
7253The path to the hosts database,
7254normally
7255.q /etc/hosts .
7256This option is only consulted when sendmail
7257is canonifying addresses,
7258and then only when
7259.q files
7260is in the
7261.q hosts
7262service switch entry.
7263In particular, this file is
7264.i never
7265used when looking up host addresses;
7266that is under the control of the system
7267.i gethostbyname (3)
7268routine.
7269.ip HostStatusDirectory=\fIpath\fP
7270[no short name]
7271The location of the long term host status information.
7272When set,
7273information about the status of hosts
7274(e.g., host down or not accepting connections)
7275will be shared between all
7276.i sendmail
7277processes;
7278normally, this information is only held within a single queue run.
7279This option requires a connection cache of at least 1 to function.
7280If the option begins with a leading `/',
7281it is an absolute pathname;
7282otherwise,
7283it is relative to the mail queue directory.
7284A suggested value for sites desiring persistent host status is
7285.q \&.hoststat
7286(i.e., a subdirectory of the queue directory).
7287.ip IgnoreDots
7288[i]
7289Ignore dots in incoming messages.
7290This is always disabled (that is, dots are always accepted)
7291when reading SMTP mail.
7292.ip InputMailFilters=\fIname,name,...\fP
7293A comma separated list of filters which determines which filters
7294(see the "X \*- Mail Filter (Milter) Definitions" section)
7295and the invocation sequence are contacted for incoming SMTP messages.
7296If none are set, no filters will be contacted.
7297.ip LDAPDefaultSpec=\fIspec\fP
7298[no short name]
7299Sets a default map specification for LDAP maps.
7300The value should only contain LDAP specific settings
7301such as
7302.q "-h host -p port -d bindDN" .
7303The settings will be used for all LDAP maps
7304unless the individual map specification overrides a setting.
7305This option should be set before any LDAP maps are defined.
7306.ip LogLevel=\fIn\fP
7307[L]
7308Set the log level to
7309.i n .
7310Defaults to 9.
7311.ip M\fIx\|value\fP
7312[no long version]
7313Set the macro
7314.i x
7315to
7316.i value .
7317This is intended only for use from the command line.
7318The
7319.b \-M
7320flag is preferred.
7321.ip MailboxDatabase
7322[no short name]
7323Type of lookup to find information about local mailboxes,
7324defaults to ``pw'' which uses
7325.i getpwnam .
7326Other types can be introduced by adding them to the source code,
7327see libsm/mbdb.c for details.
7328.ip UseMSP
7329[no short name]
7330Use as mail submission program, i.e.,
7331allow group writable queue files
7332if the group is the same as that of a set-group-ID sendmail binary.
7333See the file
7334.b sendmail/SECURITY
7335in the distribution tarball.
7336.ip MatchGECOS
7337[G]
7338Allow fuzzy matching on the GECOS field.
7339If this flag is set,
7340and the usual user name lookups fail
7341(that is, there is no alias with this name and a
7342.i getpwnam
7343fails),
7344sequentially search the password file
7345for a matching entry in the GECOS field.
7346This also requires that MATCHGECOS
7347be turned on during compilation.
7348This option is not recommended.
7349.ip MaxAliasRecursion=\fIN\fP
7350[no short name]
7351The maximum depth of alias recursion (default: 10).
7352.ip MaxDaemonChildren=\fIN\fP
7353[no short name]
7354If set,
7355.i sendmail
7356will refuse connections when it has more than
7357.i N
7358children processing incoming mail or automatic queue runs.
7359This does not limit the number of outgoing connections.
7360If the default
7361.b DeliveryMode
7362(background) is used, then
7363.i sendmail
7364may create an almost unlimited number of children
7365(depending on the number of transactions and the
7366relative execution times of mail receiption and mail delivery).
7367If the limit should be enforced, then a
7368.b DeliveryMode
7369other than background must be used.
7370If not set, there is no limit to the number of children --
7371that is, the system load average controls this.
7372.ip MaxHeadersLength=\fIN\fP
7373[no short name]
7374The maximum length of the sum of all headers.
7375This can be used to prevent a denial of service attack.
7376The default is no limit.
7377.ip MaxHopCount=\fIN\fP
7378[h]
7379The maximum hop count.
7380Messages that have been processed more than
7381.i N
7382times are assumed to be in a loop and are rejected.
7383Defaults to 25.
7384.ip MaxMessageSize=\fIN\fP
7385[no short name]
7386Specify the maximum message size
7387to be advertised in the ESMTP EHLO response.
7388Messages larger than this will be rejected.
7389If set to a value greater than zero,
7390that value will be listed in the SIZE response,
7391otherwise SIZE is advertised in the ESMTP EHLO response
7392without a parameter.
7393.ip MaxMimeHeaderLength=\fIN[/M]\fP
7394[no short name]
7395Sets the maximum length of certain MIME header field values to
7396.i N
7397characters.
7398These MIME header fields are determined by being a member of
7399class {checkMIMETextHeaders}, which currently contains only
7400the header Content-Description.
7401For some of these headers which take parameters,
7402the maximum length of each parameter is set to
7403.i M
7404if specified. If
7405.i /M
7406is not specified, one half of
7407.i N
7408will be used.
7409By default,
7410these values are 2048 and 1024, respectively.
7411To allow any length, a value of 0 can be specified.
7412.ip MaxNOOPCommands=\fIN\fP
7413Override the default of
7414.b MAXNOOPCOMMANDS
7415for the number of
7416.i useless
7417commands, see Section
7418"Measures against Denial of Service Attacks".
7419.ip MaxQueueChildren=\fIN\fP
7420[no short name]
7421When set, this limits the number of concurrent queue runner processes to
7422.i N.
7423This helps to control the amount of system resources used when processing
7424the queue. When there are multiple queue groups defined and the total number
7425of queue runners for these queue groups would exceed
7426.i MaxQueueChildren
7427then the queue groups will not all run concurrently. That is, some portion
7428of the queue groups will run concurrently such that
7429.i MaxQueueChildren
7430will not be exceeded, while the remaining queue groups will be run later (in
7431round robin order). See also
7432.i MaxRunnersPerQueue
7433and the section \fBQueue Group Declaration\fP.
7434Notice:
7435.i sendmail
7436does not count individual queue runners, but only sets of processes
7437that act on a workgroup.
7438Hence the actual number of queue runners may be lower than the limit
7439imposed by
7440.i MaxQueueChildren .
7441This discrepancy can be large if some queue runners have to wait
7442for a slow server and if short intervals are used.
7443.ip MaxQueueRunSize=\fIN\fP
7444[no short name]
7445The maximum number of jobs that will be processed
7446in a single queue run.
7447If not set, there is no limit on the size.
7448If you have very large queues or a very short queue run interval
7449this could be unstable.
7450However, since the first
7451.i N
7452jobs in queue directory order are run (rather than the
7453.i N
7454highest priority jobs)
7455this should be set as high as possible to avoid
7456.q losing
7457jobs that happen to fall late in the queue directory.
7458Note: this option also restricts the number of entries printed by
7459.i mailq .
7460That is, if
7461.i MaxQueueRunSize
7462is set to a value
7463.b N
7464larger than zero,
7465then only
7466.b N
7467entries are printed per queue group.
7468.ip MaxRecipientsPerMessage=\fIN\fP
7469[no short name]
7470The maximum number of recipients that will be accepted per message
7471in an SMTP transaction.
7472Note: setting this too low can interfere with sending mail from
7473MUAs that use SMTP for initial submission.
7474If not set, there is no limit on the number of recipients per envelope.
7475.ip MaxRunnersPerQueue=\fIN\fP
7476[no short name]
7477This sets the default maximum number of queue runners for queue groups.
7478Up to
7479.i N
7480queue runners will work in parallel on a queue group's messages.
7481This is useful where the processing of a message in the queue might
7482delay the processing of subsequent messages. Such a delay may be the result
7483of non-erroneous situations such as a low bandwidth connection.
7484May be overridden on a per queue group basis by setting the
7485.i Runners
7486option; see the section \fBQueue Group Declaration\fP.
7487The default is 1 when not set.
7488.ip MeToo
7489[m]
7490Send to me too,
7491even if I am in an alias expansion.
7492This option is deprecated
7493and will be removed from a future version.
7494.ip Milter
7495[no short name]
7496This option has several sub(sub)options.
7497The names of the suboptions are separated by dots.
7498At the first level the following options are available:
7499.(b
7500.ta \w'LogLevel'u+3n
7501LogLevel Log level for input mail filter actions, defaults to LogLevel.
7502macros Specifies list of macro to transmit to filters.
7503 See list below.
7504.)b
7505The ``macros'' option has the following suboptions
7506which specify the list of macro to transmit to milters
7507after a certain event occurred.
7508.(b
7509.ta \w'envfrom'u+3n
7510connect After session connection start
7511helo After EHLO/HELO command
7512envfrom After MAIL From command
7513envrcpt After RCPT To command
7514data After DATA command.
7515eoh After DATA command and header
7516eom After DATA command and terminating ``.''
7517.)b
7518By default the lists of macros are empty.
7519Example:
7520.(b
7521O Milter.LogLevel=12
7522O Milter.macros.connect=j, _, {daemon_name}
7523.)b
7524.ip MinFreeBlocks=\fIN\fP
7525[b]
7526Insist on at least
7527.i N
7528blocks free on the filesystem that holds the queue files
7529before accepting email via SMTP.
7530If there is insufficient space
7531.i sendmail
7532gives a 452 response
7533to the MAIL command.
7534This invites the sender to try again later.
7535.ip MinQueueAge=\fIage\fP
7536[no short name]
7537Don't process any queued jobs
7538that have been in the queue less than the indicated time interval.
7539This is intended to allow you to get responsiveness
7540by processing the queue fairly frequently
7541without thrashing your system by trying jobs too often.
7542The default units are minutes.
7543Note:
7544This option is ignored for queue runs that select a subset
7545of the queue, i.e.,
7546.q \-q[!][I|R|S|Q][string]
7547.ip MustQuoteChars=\fIs\fP
7548[no short name]
7549Sets the list of characters that must be quoted if used in a full name
7550that is in the phrase part of a ``phrase <address>'' syntax.
7551The default is ``\'.''.
7552The characters ``@,;:\e()[]'' are always added to this list.
7553.ip NiceQueueRun
7554[no short name]
7555The priority of queue runners (nice(3)).
7556This value must be greater or equal zero.
7557.ip NoRecipientAction
7558[no short name]
7559The action to take when you receive a message that has no valid
7560recipient headers (To:, Cc:, Bcc:, or Apparently-To: \(em
7561the last included for back compatibility with old
7562.i sendmail s).
7563It can be
7564.b None
7565to pass the message on unmodified,
7566which violates the protocol,
7567.b Add-To
7568to add a To: header with any recipients it can find in the envelope
7569(which might expose Bcc: recipients),
7570.b Add-Apparently-To
7571to add an Apparently-To: header
7572(this is only for back-compatibility
7573and is officially deprecated),
7574.b Add-To-Undisclosed
7575to add a header
7576.q "To: undisclosed-recipients:;"
7577to make the header legal without disclosing anything,
7578or
7579.b Add-Bcc
7580to add an empty Bcc: header.
7581.ip OldStyleHeaders
7582[o]
7583Assume that the headers may be in old format,
7584i.e.,
7585spaces delimit names.
7586This actually turns on
7587an adaptive algorithm:
7588if any recipient address contains a comma, parenthesis,
7589or angle bracket,
7590it will be assumed that commas already exist.
7591If this flag is not on,
7592only commas delimit names.
7593Headers are always output with commas between the names.
7594Defaults to off.
7595.ip OperatorChars=\fIcharlist\fP
7596[$o macro]
7597The list of characters that are considered to be
7598.q operators ,
7599that is, characters that delimit tokens.
7600All operator characters are tokens by themselves;
7601sequences of non-operator characters are also tokens.
7602White space characters separate tokens
7603but are not tokens themselves \(em for example,
7604.q AAA.BBB
7605has three tokens, but
7606.q "AAA BBB"
7607has two.
7608If not set, OperatorChars defaults to
7609.q \&.\|:\|@\|[\|] ;
7610additionally, the characters
7611.q (\|)\|<\|>\|,\|;
7612are always operators.
7613Note that OperatorChars must be set in the
7614configuration file before any rulesets.
7615.ip PidFile=\fIfilename\fP
7616[no short name]
7617Filename of the pid file.
7618(default is _PATH_SENDMAILPID).
7619The
7620.i filename
7621is macro-expanded before it is opened, and unlinked when
7622.i sendmail
7623exits.
7624.ip PostmasterCopy=\fIpostmaster\fP
7625[P]
7626If set,
7627copies of error messages will be sent to the named
7628.i postmaster .
7629Only the header of the failed message is sent.
7630Errors resulting from messages with a negative precedence will not be sent.
7631Since most errors are user problems,
7632this is probably not a good idea on large sites,
7633and arguably contains all sorts of privacy violations,
7634but it seems to be popular with certain operating systems vendors.
7635The address is macro expanded
7636at the time of delivery.
7637Defaults to no postmaster copies.
7638.ip PrivacyOptions=\fI\|opt,opt,...\fP
7639[p]
7640Set the privacy
7641.i opt ions.
7642``Privacy'' is really a misnomer;
7643many of these are just a way of insisting on stricter adherence
7644to the SMTP protocol.
7645The
7646.i opt ions
7647can be selected from:
7648.(b
7649.ta \w'noactualrecipient'u+3n
7650public Allow open access
7651needmailhelo Insist on HELO or EHLO command before MAIL
7652needexpnhelo Insist on HELO or EHLO command before EXPN
7653noexpn Disallow EXPN entirely, implies noverb.
7654needvrfyhelo Insist on HELO or EHLO command before VRFY
7655novrfy Disallow VRFY entirely
7656noetrn Disallow ETRN entirely
7657noverb Disallow VERB entirely
7658restrictmailq Restrict mailq command
7659restrictqrun Restrict \-q command line flag
7660restrictexpand Restrict \-bv and \-v command line flags
7661noreceipts Don't return success DSNs\**
7662nobodyreturn Don't return the body of a message with DSNs
7663goaway Disallow essentially all SMTP status queries
7664authwarnings Put X-Authentication-Warning: headers in messages
7665 and log warnings
7666noactualrecipient Don't put X-Actual-Recipient lines in DSNs
7667 which reveal the actual account that addresses map to.
7668.)b
7669.(f
7670\**N.B.:
7671the
7672.b noreceipts
7673flag turns off support for RFC 1891
7674(Delivery Status Notification).
7675.)f
7676The
7677.q goaway
7678pseudo-flag sets all flags except
7679.q noreceipts ,
7680.q restrictmailq ,
7681.q restrictqrun ,
7682.q restrictexpand ,
7683.q noetrn ,
7684and
7685.q nobodyreturn .
7686If mailq is restricted,
7687only people in the same group as the queue directory
7688can print the queue.
7689If queue runs are restricted,
7690only root and the owner of the queue directory
7691can run the queue.
7692The
7693.q restrictexpand
7694pseudo-flag instructs
7695.i sendmail
7696to drop privileges when the
7697.b \-bv
7698option is given by users who are neither root nor the TrustedUser
7699so users cannot read private aliases, forwards, or :include: files.
7700It will add the
7701.q NonRootSafeAddr
7702to the
7703.q DontBlameSendmail
7704option to prevent misleading unsafe address warnings.
7705It also overrides the
7706.b \-v
7707(verbose) command line option to prevent information leakage.
7708Authentication Warnings add warnings about various conditions
7709that may indicate attempts to spoof the mail system,
7710such as using a non-standard queue directory.
7711.ip ProcessTitlePrefix=\fIstring\fP
7712[no short name]
7713Prefix the process title shown on 'ps' listings with
7714.i string .
7715The
7716.i string
7717will be macro processed.
7718.ip QueueDirectory=\fIdir\fP
7719[Q]
7720The QueueDirectory option serves two purposes.
7721First, it specifies the directory or set of directories that comprise
7722the default queue group.
7723Second, it specifies the directory D which is the ancestor of all queue
7724directories, and which sendmail uses as its current working directory.
7725When sendmail dumps core, it leaves its core files in D.
7726There are two cases.
7727If \fIdir\fR ends with an asterisk (eg, \fI/var/spool/mqueue/qd*\fR),
7728then all of the directories or symbolic links to directories
7729beginning with `qd' in
7730.i /var/spool/mqueue
7731will be used as queue directories of the default queue group,
7732and
7733.i /var/spool/mqueue
7734will be used as the working directory D.
7735Otherwise,
7736\fIdir\fR must name a directory (usually \fI/var/spool/mqueue\fR):
7737the default queue group consists of the single queue directory \fIdir\fR,
7738and the working directory D is set to \fIdir\fR.
7739To define additional groups of queue directories,
7740use the configuration file `Q' command.
7741Do not change the queue directory structure
7742while sendmail is running.
7743.ip QueueFactor=\fIfactor\fP
7744[q]
7745Use
7746.i factor
7747as the multiplier in the map function
7748to decide when to just queue up jobs rather than run them.
7749This value is divided by the difference between the current load average
7750and the load average limit
7751(\c
7752.b QueueLA
7753option)
7754to determine the maximum message priority
7755that will be sent.
7756Defaults to 600000.
7757.ip QueueLA=\fILA\fP
7758[x]
7759When the system load average exceeds
7760.i LA
7761and the
7762.b QueueFactor
7763(\c
7764.b q )
7765option divided by the difference in the current load average and the
7766.b QueueLA
7767option plus one
7768is less than the priority of the message,
7769just queue messages
7770(i.e., don't try to send them).
7771Defaults to 8 multiplied by
7772the number of processors online on the system
7773(if that can be determined).
7774.ip QueueFileMode=\fImode\fP
7775[no short name]
7776Default permissions for queue files (octal).
7777If not set, sendmail uses 0600 unless its real
7778and effective uid are different in which case it uses 0644.
7779.ip QueueSortOrder=\fIalgorithm\fP
7780[no short name]
7781Sets the
7782.i algorithm
7783used for sorting the queue.
7784Only the first character of the value is used.
7785Legal values are
7786.q host
7787(to order by the name of the first host name of the first recipient),
7788.q filename
7789(to order by the name of the queue file name),
7790.q time
7791(to order by the submission/creation time),
7792.q random
7793(to order randomly),
7794.q modification
7795(to order by the modification time of the qf file (older entries first)),
7796.q none
7797(to not order),
7798and
7799.q priority
7800(to order by message priority).
7801Host ordering makes better use of the connection cache,
7802but may tend to process low priority messages
7803that go to a single host
7804over high priority messages that go to several hosts;
7805it probably shouldn't be used on slow network links.
7806Filename and modification time ordering saves the overhead of
7807reading all of the queued items
7808before starting the queue run.
7809Creation (submission) time ordering is almost always a bad idea,
7810since it allows large, bulk mail to go out
7811before smaller, personal mail,
7812but may have applicability on some hosts with very fast connections.
7813Random is useful if several queue runners are started by hand
7814which try to drain the same queue since odds are they will be working
7815on different parts of the queue at the same time.
7816Priority ordering is the default.
7817.ip QueueTimeout=\fItimeout\fP
7818[T]
7819A synonym for
7820.q Timeout.queuereturn .
7821Use that form instead of the
7822.q QueueTimeout
7823form.
7824.ip RandFile
7825[no short name]
7826Name of file containing random data or the name of the UNIX socket
7827if EGD is used.
7828A (required) prefix "egd:" or "file:" specifies the type.
7829STARTTLS requires this filename if the compile flag HASURANDOMDEV is not set
7830(see sendmail/README).
7831.ip ResolverOptions=\fIoptions\fP
7832[I]
7833Set resolver options.
7834Values can be set using
7835.b + \c
7836.i flag
7837and cleared using
7838.b \- \c
7839.i flag ;
7840the
7841.i flag s
7842can be
7843.q debug ,
7844.q aaonly ,
7845.q usevc ,
7846.q primary ,
7847.q igntc ,
7848.q recurse ,
7849.q defnames ,
7850.q stayopen ,
7851.q use_inet6 ,
7852or
7853.q dnsrch .
7854The string
7855.q HasWildcardMX
7856(without a
7857.b +
7858or
7859.b \- )
7860can be specified to turn off matching against MX records
7861when doing name canonifications.
7862The string
7863.q WorkAroundBrokenAAAA
7864(without a
7865.b +
7866or
7867.b \- )
7868can be specified to work around some broken nameservers
7869which return SERVFAIL (a temporary failure) on T_AAAA (IPv6) lookups.
7870Notice: it might be necessary to apply the same (or similar) options to
7871.i submit.cf
7872too.
7873.ip RequiresDirfsync
7874[no short name]
7875This option can be used to override the compile time flag
7876.b REQUIRES_DIR_FSYNC
7877at runtime by setting it to
7878.sm false .
7879If the compile time flag is not set, the option is ignored.
7880The flag turns on support for file systems that require to call
7881.i fsync()
7882for a directory if the meta-data in it has been changed.
7883This should be turned on at least for older versions of ReiserFS;
7884it is enabled by default for Linux.
7885According to some information this flag is not needed
7886anymore for kernel 2.4.16 and newer.
7887.ip RrtImpliesDsn
7888[R]
7889If this option is set, a
7890.q Return-Receipt-To:
7891header causes the request of a DSN, which is sent to
7892the envelope sender as required by RFC 1891,
7893not to the address given in the header.
7894.ip RunAsUser=\fIuser\fP
7895[no short name]
7896The
7897.i user
7898parameter may be a user name
7899(looked up in
7900.i /etc/passwd )
7901or a numeric user id;
7902either form can have
7903.q ":group"
7904attached
7905(where group can be numeric or symbolic).
7906If set to a non-zero (non-root) value,
7907.i sendmail
7908will change to this user id shortly after startup\**.
7909.(f
7910\**When running as a daemon,
7911it changes to this user after accepting a connection
7912but before reading any
7913.sm SMTP
7914commands.
7915.)f
7916This avoids a certain class of security problems.
7917However, this means that all
7918.q \&.forward
7919and
7920.q :include:
7921files must be readable by the indicated
7922.i user
7923and all files to be written must be writable by
7924.i user
7925Also, all file and program deliveries will be marked unsafe
7926unless the option
7927.b DontBlameSendmail=NonRootSafeAddr
7928is set,
7929in which case the delivery will be done as
7930.i user .
7931It is also incompatible with the
7932.b SafeFileEnvironment
7933option.
7934In other words, it may not actually add much to security on an average system,
7935and may in fact detract from security
7936(because other file permissions must be loosened).
7937However, it should be useful on firewalls and other
7938places where users don't have accounts and the aliases file is
7939well constrained.
7940.ip RecipientFactor=\fIfact\fP
7941[y]
7942The indicated
7943.i fact or
7944is added to the priority (thus
7945.i lowering
7946the priority of the job)
7947for each recipient,
7948i.e., this value penalizes jobs with large numbers of recipients.
7949Defaults to 30000.
7950.ip RefuseLA=\fILA\fP
7951[X]
7952When the system load average exceeds
7953.i LA ,
7954refuse incoming SMTP connections.
7955Defaults to 12 multiplied by
7956the number of processors online on the system
7957(if that can be determined).
7958.ip RejectLogInterval=\fItimeout\fP
7959[no short name]
7960Log interval when refusing connections for this long
7961(default: 3h).
7962.ip RetryFactor=\fIfact\fP
7963[Z]
7964The
7965.i fact or
7966is added to the priority
7967every time a job is processed.
7968Thus,
7969each time a job is processed,
7970its priority will be decreased by the indicated value.
7971In most environments this should be positive,
7972since hosts that are down are all too often down for a long time.
7973Defaults to 90000.
7974.ip SafeFileEnvironment=\fIdir\fP
7975[no short name]
7976If this option is set,
7977.i sendmail
7978will do a
7979.i chroot (2)
7980call into the indicated
7981.i dir ectory
7982before doing any file writes.
7983If the file name specified by the user begins with
7984.i dir ,
7985that partial path name will be stripped off before writing,
7986so (for example)
7987if the SafeFileEnvironment variable is set to
7988.q /safe
7989then aliases of
7990.q /safe/logs/file
7991and
7992.q /logs/file
7993actually indicate the same file.
7994Additionally, if this option is set,
7995.i sendmail
7996refuses to deliver to symbolic links.
7997.ip SaveFromLine
7998[f]
7999Save
8000UNIX-style
8001.q From
8002lines at the front of headers.
8003Normally they are assumed redundant
8004and discarded.
8005.ip SendMimeErrors
8006[j]
8007If set, send error messages in MIME format
8008(see RFC 2045 and RFC 1344 for details).
8009If disabled,
8010.i sendmail
8011will not return the DSN keyword in response to an EHLO
8012and will not do Delivery Status Notification processing as described in
8013RFC 1891.
8014.ip ServerCertFile
8015[no short name]
8016File containing the certificate of the server, i.e., this certificate
8017is used when sendmail acts as server
8018(used for STARTTLS).
8019.ip ServerKeyFile
8020[no short name]
8021File containing the private key belonging to the server certificate
8022(used for STARTTLS).
8023.ip ServiceSwitchFile=\fIfilename\fP
8024[no short name]
8025If your host operating system has a service switch abstraction
8026(e.g., /etc/nsswitch.conf on Solaris
8027or /etc/svc.conf on Ultrix and DEC OSF/1)
8028that service will be consulted and this option is ignored.
8029Otherwise, this is the name of a file
8030that provides the list of methods used to implement particular services.
8031The syntax is a series of lines,
8032each of which is a sequence of words.
8033The first word is the service name,
8034and following words are service types.
8035The services that
8036.i sendmail
8037consults directly are
8038.q aliases
8039and
8040.q hosts.
8041Service types can be
8042.q dns ,
8043.q nis ,
8044.q nisplus ,
8045or
8046.q files
8047(with the caveat that the appropriate support
8048must be compiled in
8049before the service can be referenced).
8050If ServiceSwitchFile is not specified, it defaults to
8051/etc/mail/service.switch.
8052If that file does not exist, the default switch is:
8053.(b
8054aliases files
8055hosts dns nis files
8056.)b
8057The default file is
8058.q /etc/mail/service.switch .
8059.ip SevenBitInput
8060[7]
8061Strip input to seven bits for compatibility with old systems.
8062This shouldn't be necessary.
8063.ip SharedMemoryKey
8064[no short name]
8065Key to use for shared memory segment;
8066if not set (or 0), shared memory will not be used.
8067If set to
8068-1
8069.i sendmail
8070can select a key itself provided that also
8071.b SharedMemoryKeyFile
8072is set.
8073Requires support for shared memory to be compiled into
8074.i sendmail .
8075If this option is set,
8076.i sendmail
8077can share some data between different instances.
8078For example, the number of entries in a queue directory
8079or the available space in a file system.
8080This allows for more efficient program execution, since only
8081one process needs to update the data instead of each individual
8082process gathering the data each time it is required.
8083.ip SharedMemoryKeyFile
8084[no short name]
8085If
8086.b SharedMemoryKey
8087is set to
8088-1
8089then the automatically selected shared memory key will be stored
8090in the specified file.
8091.ip SingleLineFromHeader
8092[no short name]
8093If set, From: lines that have embedded newlines are unwrapped
8094onto one line.
8095This is to get around a botch in Lotus Notes
8096that apparently cannot understand legally wrapped RFC 822 headers.
8097.ip SingleThreadDelivery
8098[no short name]
8099If set, a client machine will never try to open two SMTP connections
8100to a single server machine at the same time,
8101even in different processes.
8102That is, if another
8103.i sendmail
8104is already talking to some host a new
8105.i sendmail
8106will not open another connection.
8107This property is of mixed value;
8108although this reduces the load on the other machine,
8109it can cause mail to be delayed
8110(for example, if one
8111.i sendmail
8112is delivering a huge message, other
8113.i sendmail s
8114won't be able to send even small messages).
8115Also, it requires another file descriptor
8116(for the lock file)
8117per connection, so you may have to reduce the
8118.b ConnectionCacheSize
8119option to avoid running out of per-process file descriptors.
8120Requires the
8121.b HostStatusDirectory
8122option.
8123.ip SmtpGreetingMessage=\fImessage\fP
8124[$e macro]
8125The message printed when the SMTP server starts up.
8126Defaults to
8127.q "$j Sendmail $v ready at $b".
8128.ip SoftBounce
8129If set, issue temporary errors (4xy) instead of permanent errors (5xy).
8130This can be useful during testing of a new configuration to avoid
8131erroneous bouncing of mails.
8132.ip StatusFile=\fIfile\fP
8133[S]
8134Log summary statistics in the named
8135.i file .
8136If no file name is specified, "statistics" is used.
8137If not set,
8138no summary statistics are saved.
8139This file does not grow in size.
8140It can be printed using the
8141.i mailstats (8)
8142program.
8143.ip SuperSafe
8144[s]
8145This option can be set to True, False, Interactive, or PostMilter.
8146If set to True,
8147.i sendmail
8148will be super-safe when running things,
8149i.e., always instantiate the queue file,
8150even if you are going to attempt immediate delivery.
8151.i Sendmail
8152always instantiates the queue file
8153before returning control to the client
8154under any circumstances.
8155This should really
8156.i always
8157be set to True.
8158The Interactive value has been introduced in 8.12 and can
8159be used together with
8160.b DeliveryMode=i .
8161It skips some synchronization calls which are effectively
8162doubled in the code execution path for this mode.
8163If set to PostMilter,
8164.i sendmail
8165defers synchronizing the queue file until any milters have
8166signaled acceptance of the message.
8167PostMilter is useful only when
8168.i sendmail
8169is running as an SMTP server; in all other situations it
8170acts the same as True.
8171.ip TLSSrvOptions
8172[no short name]
8173List of options for SMTP STARTTLS for the server
8174consisting of single characters
8175with intervening white space or commas.
8176The flag ``V'' disables client verification, and hence
8177it is not possible to use a client certificate for relaying.
8178Currently there are no other flags available.
8179.ip TempFileMode=\fImode\fP
8180[F]
8181The file mode for transcript files, files to which
8182.i sendmail
8183delivers directly, files in the
8184.b HostStatusDirectory ,
8185and
8186.b StatusFile .
8187It is interpreted in octal by default.
8188Defaults to 0600.
8189.ip Timeout.\fItype\fP=\|\fItimeout\fP
8190[r; subsumes old T option as well]
8191Set timeout values.
8192For more information,
8193see section
8194.\" XREF
81954.1.
8196.ip TimeZoneSpec=\fItzinfo\fP
8197[t]
8198Set the local time zone info to
8199.i tzinfo
8200\*- for example,
8201.q PST8PDT .
8202Actually, if this is not set,
8203the TZ environment variable is cleared (so the system default is used);
8204if set but null, the user's TZ variable is used,
8205and if set and non-null the TZ variable is set to this value.
8206.ip TrustedUser=\fIuser\fP
8207[no short name]
8208The
8209.i user
8210parameter may be a user name
8211(looked up in
8212.i /etc/passwd )
8213or a numeric user id.
8214Trusted user for file ownership and starting the daemon. If set, generated
8215alias databases and the control socket (if configured) will automatically
8216be owned by this user.
8217.ip TryNullMXList
8218[w]
8219If this system is the
8220.q best
8221(that is, lowest preference)
8222MX for a given host,
8223its configuration rules should normally detect this situation
8224and treat that condition specially
8225by forwarding the mail to a UUCP feed,
8226treating it as local,
8227or whatever.
8228However, in some cases (such as Internet firewalls)
8229you may want to try to connect directly to that host
8230as though it had no MX records at all.
8231Setting this option causes
8232.i sendmail
8233to try this.
8234The downside is that errors in your configuration
8235are likely to be diagnosed as
8236.q "host unknown"
8237or
8238.q "message timed out"
8239instead of something more meaningful.
8240This option is disrecommended.
8241.ip UnixFromLine=\fIfromline\fP
8242[$l macro]
8243Defines the format used when
8244.i sendmail
8245must add a UNIX-style From_ line
8246(that is, a line beginning
8247.q From<space>user ).
8248Defaults to
8249.q "From $g $d" .
8250Don't change this unless your system uses a different UNIX mailbox format
8251(very unlikely).
8252.ip UnsafeGroupWrites
8253[no short name]
8254If set (default),
8255:include: and .forward files that are group writable are considered
8256.q unsafe ,
8257that is,
8258they cannot reference programs or write directly to files.
8259World writable :include: and .forward files
8260are always unsafe.
8261Note: use
8262.b DontBlameSendmail
8263instead; this option is deprecated.
8264.ip UseErrorsTo
8265[l]
8266If there is an
8267.q Errors-To:
8268header, send error messages to the addresses listed there.
8269They normally go to the envelope sender.
8270Use of this option causes
8271.i sendmail
8272to violate RFC 1123.
8273This option is disrecommended and deprecated.
8274.ip UserDatabaseSpec=\fIudbspec\fP
8275[U]
8276The user database specification.
8277.ip Verbose
8278[v]
8279Run in verbose mode.
8280If this is set,
8281.i sendmail
8282adjusts options
8283.b HoldExpensive
8284(old
8285.b c )
8286and
8287.b DeliveryMode
8288(old
8289.b d )
8290so that all mail is delivered completely
8291in a single job
8292so that you can see the entire delivery process.
8293Option
8294.b Verbose
8295should
8296.i never
8297be set in the configuration file;
8298it is intended for command line use only.
8299Note that the use of option
8300.b Verbose
8301can cause authentication information to leak, if you use a
8302sendmail client to authenticate to a server.
8303If the authentication mechanism uses plain text passwords
8304(as with LOGIN or PLAIN),
8305then the password could be compromised.
8306To avoid this, do not install sendmail set-user-ID root,
8307and disable the
8308.b VERB
8309SMTP command with a suitable
8310.b PrivacyOptions
8311setting.
8312.ip XscriptFileBufferSize=\fIthreshold\fP
8313[no short name]
8314Set the
8315.i threshold ,
8316in bytes,
8317before a memory-based
8318queue transcript file
8319becomes disk-based.
8320The default is 4096 bytes.
8321.lp
8322All options can be specified on the command line using the
8323\-O or \-o flag,
8324but most will cause
8325.i sendmail
8326to relinquish its set-user-ID permissions.
8327The options that will not cause this are
8328SevenBitInput [7],
8329EightBitMode [8],
8330MinFreeBlocks [b],
8331CheckpointInterval [C],
8332DeliveryMode [d],
8333ErrorMode [e],
8334IgnoreDots [i],
8335SendMimeErrors [j],
8336LogLevel [L],
8337MeToo [m],
8338OldStyleHeaders [o],
8339PrivacyOptions [p],
8340SuperSafe [s],
8341Verbose [v],
8342QueueSortOrder,
8343MinQueueAge,
8344DefaultCharSet,
8345Dial Delay,
8346NoRecipientAction,
8347ColonOkInAddr,
8348MaxQueueRunSize,
8349SingleLineFromHeader,
8350and
8351AllowBogusHELO.
8352Actually, PrivacyOptions [p] given on the command line
8353are added to those already specified in the
8354.i sendmail.cf
8355file, i.e., they can't be reset.
8356Also, M (define macro) when defining the r or s macros
8357is also considered
8358.q safe .
8359.sh 2 "P \*- Precedence Definitions"
8360.pp
8361Values for the
8362.q "Precedence:"
8363field may be defined using the
8364.b P
8365control line.
8366The syntax of this field is:
8367.(b
8368\fBP\fP\fIname\fP\fB=\fP\fInum\fP
8369.)b
8370When the
8371.i name
8372is found in a
8373.q Precedence:
8374field,
8375the message class is set to
8376.i num .
8377Higher numbers mean higher precedence.
8378Numbers less than zero
8379have the special property
8380that if an error occurs during processing
8381the body of the message will not be returned;
8382this is expected to be used for
8383.q "bulk"
8384mail such as through mailing lists.
8385The default precedence is zero.
8386For example,
8387our list of precedences is:
8388.(b
8389Pfirst-class=0
8390Pspecial-delivery=100
8391Plist=\-30
8392Pbulk=\-60
8393Pjunk=\-100
8394.)b
8395People writing mailing list exploders
8396are encouraged to use
8397.q "Precedence: list" .
8398Older versions of
8399.i sendmail
8400(which discarded all error returns for negative precedences)
8401didn't recognize this name, giving it a default precedence of zero.
8402This allows list maintainers to see error returns
8403on both old and new versions of
8404.i sendmail .
8405.sh 2 "V \*- Configuration Version Level"
8406.pp
8407To provide compatibility with old configuration files,
8408the
8409.b V
8410line has been added to define some very basic semantics
8411of the configuration file.
8412These are not intended to be long term supports;
8413rather, they describe compatibility features
8414which will probably be removed in future releases.
8415.pp
8416.b N.B.:
8417these version
8418.i levels
8419have nothing
8420to do with the version
8421.i number
8422on the files.
8423For example,
8424as of this writing
8425version 10 config files
8426(specifically, 8.10)
8427used version level 9 configurations.
8428.pp
8429.q Old
8430configuration files are defined as version level one.
8431Version level two files make the following changes:
8432.np
8433Host name canonification ($[ ... $])
8434appends a dot if the name is recognized;
8435this gives the config file a way of finding out if anything matched.
8436(Actually, this just initializes the
8437.q host
8438map with the
8439.q \-a.
8440flag \*- you can reset it to anything you prefer
8441by declaring the map explicitly.)
8442.np
8443Default host name extension is consistent throughout processing;
8444version level one configurations turned off domain extension
8445(that is, adding the local domain name)
8446during certain points in processing.
8447Version level two configurations are expected to include a trailing dot
8448to indicate that the name is already canonical.
8449.np
8450Local names that are not aliases
8451are passed through a new distinguished ruleset five;
8452this can be used to append a local relay.
8453This behavior can be prevented by resolving the local name
8454with an initial `@'.
8455That is, something that resolves to a local mailer and a user name of
8456.q vikki
8457will be passed through ruleset five,
8458but a user name of
8459.q @vikki
8460will have the `@' stripped,
8461will not be passed through ruleset five,
8462but will otherwise be treated the same as the prior example.
8463The expectation is that this might be used to implement a policy
8464where mail sent to
8465.q vikki
8466was handled by a central hub,
8467but mail sent to
8468.q vikki@localhost
8469was delivered directly.
8470.pp
8471Version level three files
8472allow # initiated comments on all lines.
8473Exceptions are backslash escaped # marks
8474and the $# syntax.
8475.pp
8476Version level four configurations
8477are completely equivalent to level three
8478for historical reasons.
8479.pp
8480Version level five configuration files
8481change the default definition of
8482.b $w
8483to be just the first component of the hostname.
8484.pp
8485Version level six configuration files
8486change many of the local processing options
8487(such as aliasing and matching the beginning of the address for
8488`|' characters)
8489to be mailer flags;
8490this allows fine-grained control over the special local processing.
8491Level six configuration files may also use long option names.
8492The
8493.b ColonOkInAddr
8494option (to allow colons in the local-part of addresses)
8495defaults
8496.b on
8497for lower numbered configuration files;
8498the configuration file requires some additional intelligence
8499to properly handle the RFC 822 group construct.
8500.pp
8501Version level seven configuration files
8502used new option names to replace old macros
8503(\c
8504.b $e
8505became
8506.b SmtpGreetingMessage ,
8507.b $l
8508became
8509.b UnixFromLine ,
8510and
8511.b $o
8512became
8513.b OperatorChars .
8514Also, prior to version seven,
8515the
8516.b F=q
8517flag (use 250 instead of 252 return value for
8518.sm "SMTP VRFY"
8519commands)
8520was assumed.
8521.pp
8522Version level eight configuration files allow
8523.b $#
8524on the left hand side of ruleset lines.
8525.pp
8526Version level nine configuration files allow
8527parentheses in rulesets, i.e. they are not treated
8528as comments and hence removed.
8529.pp
8530Version level ten configuration files allow
8531queue group definitions.
8532.pp
8533The
8534.b V
8535line may have an optional
8536.b / \c
8537.i vendor
8538to indicate that this configuration file uses modifications
8539specific to a particular vendor\**.
8540.(f
8541\**And of course, vendors are encouraged to add themselves
8542to the list of recognized vendors by editing the routine
8543.i setvendor
8544in
8545.i conf.c .
8546Please send e-mail to sendmail@Sendmail.ORG
8547to register your vendor dialect.
8548.)f
8549You may use
8550.q /Berkeley
8551to emphasize that this configuration file
8552uses the Berkeley dialect of
8553.i sendmail .
8554.sh 2 "K \*- Key File Declaration"
8555.pp
8556Special maps can be defined using the line:
8557.(b
8558Kmapname mapclass arguments
8559.)b
8560The
8561.i mapname
8562is the handle by which this map is referenced in the rewriting rules.
8563The
8564.i mapclass
8565is the name of a type of map;
8566these are compiled in to
8567.i sendmail .
8568The
8569.i arguments
8570are interpreted depending on the class;
8571typically,
8572there would be a single argument naming the file containing the map.
8573.pp
8574Maps are referenced using the syntax:
8575.(b
8576$( \fImap\fP \fIkey\fP $@ \fIarguments\fP $: \fIdefault\fP $)
8577.)b
8578where either or both of the
8579.i arguments
8580or
8581.i default
8582portion may be omitted.
8583The
8584.i "$@ arguments"
8585may appear more than once.
8586The indicated
8587.i key
8588and
8589.i arguments
8590are passed to the appropriate mapping function.
8591If it returns a value, it replaces the input.
8592If it does not return a value and the
8593.i default
8594is specified, the
8595.i default
8596replaces the input.
8597Otherwise, the input is unchanged.
8598.pp
8599The
8600.i arguments
8601are passed to the map for arbitrary use.
8602Most map classes can interpolate these arguments
8603into their values using the syntax
8604.q %\fIn\fP
8605(where
8606.i n
8607is a digit)
8608to indicate the corresponding
8609.i argument .
8610Argument
8611.q %0
8612indicates the database key.
8613For example, the rule
8614.(b
8615.ta 1.5i
8616R$\- ! $+ $: $(uucp $1 $@ $2 $: $2 @ $1 . UUCP $)
8617.)b
8618Looks up the UUCP name in a (user defined) UUCP map;
8619if not found it turns it into
8620.q \&.UUCP
8621form.
8622The database might contain records like:
8623.(b
8624decvax %1@%0.DEC.COM
8625research %1@%0.ATT.COM
8626.)b
8627Note that
8628.i default
8629clauses never do this mapping.
8630.pp
8631The built-in map with both name and class
8632.q host
8633is the host name canonicalization lookup.
8634Thus,
8635the syntax:
8636.(b
8637$(host \fIhostname\fP$)
8638.)b
8639is equivalent to:
8640.(b
8641$[\fIhostname\fP$]
8642.)b
8643.pp
8644There are many defined classes.
8645.ip dbm
8646Database lookups using the ndbm(3) library.
8647.i Sendmail
8648must be compiled with
8649.b NDBM
8650defined.
8651.ip btree
8652Database lookups using the btree interface to the Berkeley DB
8653library.
8654.i Sendmail
8655must be compiled with
8656.b NEWDB
8657defined.
8658.ip hash
8659Database lookups using the hash interface to the Berkeley DB
8660library.
8661.i Sendmail
8662must be compiled with
8663.b NEWDB
8664defined.
8665.ip nis
8666NIS lookups.
8667.i Sendmail
8668must be compiled with
8669.b NIS
8670defined.
8671.ip nisplus
8672NIS+ lookups.
8673.i Sendmail
8674must be compiled with
8675.b NISPLUS
8676defined.
8677The argument is the name of the table to use for lookups,
8678and the
8679.b \-k
8680and
8681.b \-v
8682flags may be used to set the key and value columns respectively.
8683.ip hesiod
8684Hesiod lookups.
8685.i Sendmail
8686must be compiled with
8687.b HESIOD
8688defined.
8689.ip ldap
8690LDAP X500 directory lookups.
8691.i Sendmail
8692must be compiled with
8693.b LDAPMAP
8694defined.
8695The map supports most of the standard arguments
8696and most of the command line arguments of the
8697.i ldapsearch
8698program.
8699Note that,
8700by default,
8701if a single query matches multiple values,
8702only the first value will be returned
8703unless the
8704.b \-z
8705(value separator)
8706map flag is set.
8707Also, the
8708.b \-1
8709map flag will treat a multiple value return
8710as if there were no matches.
8711.ip netinfo
8712NeXT NetInfo lookups.
8713.i Sendmail
8714must be compiled with
8715.b NETINFO
8716defined.
8717.ip text
8718Text file lookups.
8719The format of the text file is defined by the
8720.b \-k
8721(key field number),
8722.b \-v
8723(value field number),
8724and
8725.b \-z
8726(field delimiter)
8727flags.
8728.ip ph
8729PH query map.
8730Contributed and supported by
8731Mark Roth, roth@uiuc.edu.
8732For more information,
8733consult the web site
8734.q http://www-dev.cites.uiuc.edu/sendmail/ .
8735.ip nsd
8736nsd map for IRIX 6.5 and later.
8737Contributed and supported by Bob Mende of SGI,
8738mende@sgi.com.
8739.ip stab
8740Internal symbol table lookups.
8741Used internally for aliasing.
8742.ip implicit
8743Really should be called
8744.q alias
8745\(em this is used to get the default lookups
8746for alias files,
8747and is the default if no class is specified for alias files.
8748.ip user
8749Looks up users using
8750.i getpwnam (3).
8751The
8752.b \-v
8753flag can be used to specify the name of the field to return
8754(although this is normally used only to check the existence
8755of a user).
8756.ip host
8757Canonifies host domain names.
8758Given a host name it calls the name server
8759to find the canonical name for that host.
8760.ip bestmx
8761Returns the best MX record for a host name given as the key.
8762The current machine is always preferred \*-
8763that is, if the current machine is one of the hosts listed as a
8764lowest-preference MX record, then it will be guaranteed to be returned.
8765This can be used to find out if this machine is the target for an MX record,
8766and mail can be accepted on that basis.
8767If the
8768.b \-z
8769flag is given, then all MX names are returned,
8770separated by the given delimiter.
8771.ip dns
8772This map requires the option -R to specify the DNS resource record
8773type to lookup. The following types are supported:
8774A, AAAA, AFSDB, CNAME, MX, NS, PTR, SRV, and TXT.
8775A map lookup will return only one record.
8776Hence for some types, e.g., MX records, the return value might be a random
8777element of the list due to randomizing in the DNS resolver.
8778.ip sequence
8779The arguments on the `K' line are a list of maps;
8780the resulting map searches the argument maps in order
8781until it finds a match for the indicated key.
8782For example, if the key definition is:
8783.(b
8784Kmap1 ...
8785Kmap2 ...
8786Kseqmap sequence map1 map2
8787.)b
8788then a lookup against
8789.q seqmap
8790first does a lookup in map1.
8791If that is found, it returns immediately.
8792Otherwise, the same key is used for map2.
8793.ip syslog
8794the key is logged via
8795.i syslogd \|(8).
8796The lookup returns the empty string.
8797.ip switch
8798Much like the
8799.q sequence
8800map except that the order of maps is determined by the service switch.
8801The argument is the name of the service to be looked up;
8802the values from the service switch are appended to the map name
8803to create new map names.
8804For example, consider the key definition:
8805.(b
8806Kali switch aliases
8807.)b
8808together with the service switch entry:
8809.(b
8810aliases nis files
8811.)b
8812This causes a query against the map
8813.q ali
8814to search maps named
8815.q ali.nis
8816and
8817.q ali.files
8818in that order.
8819.ip dequote
8820Strip double quotes (") from a name.
8821It does not strip backslashes,
8822and will not strip quotes if the resulting string
8823would contain unscannable syntax
8824(that is, basic errors like unbalanced angle brackets;
8825more sophisticated errors such as unknown hosts are not checked).
8826The intent is for use when trying to accept mail from systems such as
8827DECnet
8828that routinely quote odd syntax such as
8829.(b
8830"49ers::ubell"
8831.)b
8832A typical usage is probably something like:
8833.(b
8834Kdequote dequote
8835
8836\&...
8837
8838R$\- $: $(dequote $1 $)
8839R$\- $+ $: $>3 $1 $2
8840.)b
8841Care must be taken to prevent unexpected results;
8842for example,
8843.(b
8844"|someprogram < input > output"
8845.)b
8846will have quotes stripped,
8847but the result is probably not what you had in mind.
8848Fortunately these cases are rare.
8849.ip regex
8850The map definition on the
8851.b K
8852line contains a regular expression.
8853Any key input is compared to that expression using the
8854POSIX regular expressions routines regcomp(), regerr(), and regexec().
8855Refer to the documentation for those routines for more information
8856about the regular expression matching.
8857No rewriting of the key is done if the
8858.b \-m
8859flag is used. Without it, the key is discarded or if
8860.b \-s
8861if used, it is substituted by the substring matches, delimited by
8862.b $|
8863or the string specified with the the
8864.b \-d
8865flag. The flags available for the map are
8866.(b
8867.ta 4n
8868-n not
8869-f case sensitive
8870-b basic regular expressions (default is extended)
8871-s substring match
8872-d set the delimiter used for -s
8873-a append string to key
8874-m match only, do not replace/discard value
8875-D perform no lookup in deferred delivery mode.
8876.)b
8877The
8878.b \-s
8879flag can include an optional parameter which can be used
8880to select the substrings in the result of the lookup. For example,
8881.(b
8882-s1,3,4
8883.)b
8884Notes: to match a
8885.b $
8886in a string,
8887\\$$
8888must be used.
8889If the pattern contains spaces, they must be replaced
8890with the blank substitution character, unless it is
8891space itself.
8892.ip program
8893The arguments on the
8894.b K
8895line are the pathname to a program and any initial parameters to be passed.
8896When the map is called,
8897the key is added to the initial parameters
8898and the program is invoked
8899as the default user/group id.
8900The first line of standard output is returned as the value of the lookup.
8901This has many potential security problems,
8902and has terrible performance;
8903it should be used only when absolutely necessary.
8904.ip macro
8905Set or clear a macro value.
8906To set a macro,
8907pass the value as the first argument in the map lookup.
8908To clear a macro,
8909do not pass an argument in the map lookup.
8910The map always returns the empty string.
8911Example of typical usage include:
8912.(b
8913Kstorage macro
8914
8915\&...
8916
8917# set macro ${MyMacro} to the ruleset match
8918R$+ $: $(storage {MyMacro} $@ $1 $) $1
8919# set macro ${MyMacro} to an empty string
8920R$* $: $(storage {MyMacro} $@ $) $1
8921# clear macro ${MyMacro}
8922R$\- $: $(storage {MyMacro} $) $1
8923.)b
8924.ip arith
8925Perform simple arithmetic operations.
8926The operation is given as key, currently
8927+, -, *, /, %,
8928|, & (bitwise OR, AND),
8929l (for less than), =,
8930and r (for random) are supported.
8931The two operands are given as arguments.
8932The lookup returns the result of the computation,
8933i.e.,
8934.sm TRUE
8935or
8936.sm FALSE
8937for comparisons, integer values otherwise.
8938The r operator returns a pseudo-random number whose value
8939lies between the first and second operand
8940(which requires that the first operand is smaller than the second).
8941All options which are possible for maps are ignored.
8942A simple example is:
8943.(b
8944Kcomp arith
8945
8946\&...
8947
8948Scheck_etrn
8949R$* $: $(comp l $@ $&{load_avg} $@ 7 $) $1
8950RFALSE $# error \&...
8951.)b
8952.ip socket
8953The socket map uses a simple request/reply protocol over TCP or UNIX domain
8954sockets to query an external server.
8955Both requests and replies are text based and encoded as netstrings,
8956i.e., a string "hello there" becomes:
8957.(b
895811:hello there,
8959.)b
8960Note: neither requests nor replies end with CRLF.
8961
8962The request consists of the database map name and the lookup key separated
8963by a space character:
8964
8965.(b
8966<mapname> ' ' <key>
8967.)b
8968
8969The server responds with a status indicator and the result (if any):
8970
8971.(b
8972<status> ' ' <result>
8973.)b
8974
8975The status indicator specifies the result of the lookup operation itself
8976and is one of the following upper case words:
8977.(b
8978.ta 9n
8979OK the key was found, result contains the looked up value
8980NOTFOUND the key was not found, the result is empty
8981TEMP a temporary failure occured
8982TIMEOUT a timeout occured on the server side
8983PERM a permanent failure occured
8984.)b
8985
8986In case of errors (status TEMP, TIMEOUT or PERM) the result field may
8987contain an explanatory message.
8988However, the explanatory message is not used any further by
8989.i sendmail .
8990
8991Example replies:
8992.(b
899331:OK resolved.address@example.com,
8994.)b
8995
8996.(b
899756:OK error:550 5.7.1 User does not accept mail from sender,
8998.)b
8999
9000in case of successful lookups, or:
9001.(b
90028:NOTFOUND,
9003.)b
9004
9005in case the key was not found, or:
9006.(b
900755:TEMP this text explains that we had a temporary failure,
9008.)b
9009
9010in case of a temporary map lookup failure.
9011
9012The socket map uses the same syntax as milters
9013(see Section "X \*- Mail Filter (Milter) Definitions")
9014to specify the remote endpoint, e.g.,
9015.(b
9016Ksocket mySocketMap inet:12345@127.0.0.1
9017.)b
9018
9019If multiple socket maps define the same remote endpoint, they will share
9020a single connection to this endpoint.
9021.pp
9022Most of these accept as arguments the same optional flags
9023and a filename
9024(or a mapname for NIS;
9025the filename is the root of the database path,
9026so that
9027.q .db
9028or some other extension appropriate for the database type
9029will be added to get the actual database name).
9030Known flags are:
9031.ip "\-o"
9032Indicates that this map is optional \*- that is,
9033if it cannot be opened,
9034no error is produced,
9035and
9036.i sendmail
9037will behave as if the map existed but was empty.
9038.ip "\-N, \-O"
9039If neither
9040.b \-N
9041or
9042.b \-O
9043are specified,
9044.i sendmail
9045uses an adaptive algorithm to decide whether or not to look for null bytes
9046on the end of keys.
9047It starts by trying both;
9048if it finds any key with a null byte it never tries again without a null byte
9049and vice versa.
9050If
9051.b \-N
9052is specified it never tries without a null byte and
9053if
9054.b \-O
9055is specified it never tries with a null byte.
9056Setting one of
9057these can speed matches but are never necessary.
9058If both
9059.b \-N
9060and
9061.b \-O
9062are specified,
9063.i sendmail
9064will never try any matches at all \(em
9065that is, everything will appear to fail.
9066.ip "\-a\fIx\fP"
9067Append the string
9068.i x
9069on successful matches.
9070For example, the default
9071.i host
9072map appends a dot on successful matches.
9073.ip "\-T\fIx\fP"
9074Append the string
9075.i x
9076on temporary failures.
9077For example,
9078.i x
9079would be appended if a DNS lookup returned
9080.q "server failed"
9081or an NIS lookup could not locate a server.
9082See also the
9083.b \-t
9084flag.
9085.ip "\-f"
9086Do not fold upper to lower case before looking up the key.
9087.ip "\-m"
9088Match only (without replacing the value).
9089If you only care about the existence of a key and not the value
9090(as you might when searching the NIS map
9091.q hosts.byname
9092for example),
9093this flag prevents the map from substituting the value.
9094However,
9095The \-a argument is still appended on a match,
9096and the default is still taken if the match fails.
9097.ip "\-k\fIkeycol\fP"
9098The key column name (for NIS+) or number
9099(for text lookups).
9100For LDAP maps this is an LDAP filter string
9101in which %s is replaced with the literal contents of the lookup key
9102and %0 is replaced with the LDAP escaped contents of the lookup key
9103according to RFC 2254.
9104If the flag
9105.b \-K
9106is used, then %1 through %9 are replaced with the LDAP escaped contents
9107of the arguments specified in the map lookup.
9108.ip "\-v\fIvalcol\fP"
9109The value column name (for NIS+) or number
9110(for text lookups).
9111For LDAP maps this is the name of one or more
9112attributes to be returned;
9113multiple attributes can be separated by commas.
9114If not specified, all attributes found in the match
9115will be returned.
9116The attributes listed can also include a type and one or more
9117objectClass values for matching as described in the LDAP section.
9118.ip "\-z\fIdelim\fP"
9119The column delimiter (for text lookups).
9120It can be a single character or one of the special strings
9121.q \|\en
9122or
9123.q \|\et
9124to indicate newline or tab respectively.
9125If omitted entirely,
9126the column separator is any sequence of white space.
9127For LDAP maps this is the separator character
9128to combine multiple values
9129into a single return string.
9130If not set,
9131the LDAP lookup will only return the first match found.
9132For DNS maps this is the separator character at which
9133the result of a query is cut off if is too long.
9134.ip "\-t"
9135Normally, when a map attempts to do a lookup
9136and the server fails
9137(e.g.,
9138.i sendmail
9139couldn't contact any name server;
9140this is
9141.i not
9142the same as an entry not being found in the map),
9143the message being processed is queued for future processing.
9144The
9145.b \-t
9146flag turns off this behavior,
9147letting the temporary failure (server down)
9148act as though it were a permanent failure (entry not found).
9149It is particularly useful for DNS lookups,
9150where someone else's misconfigured name server can cause problems
9151on your machine.
9152However, care must be taken to ensure that you don't bounce mail
9153that would be resolved correctly if you tried again.
9154A common strategy is to forward such mail
9155to another, possibly better connected, mail server.
9156.ip "\-D"
9157Perform no lookup in deferred delivery mode.
9158This flag is set by default for the
9159.i host
9160map.
9161.ip "\-S\fIspacesub\fP
9162The character to use to replace space characters
9163after a successful map lookup (esp. useful for regex
9164and syslog maps).
9165.ip "\-s\fIspacesub\fP
9166For the dequote map only,
9167the character to use to replace space characters
9168after a successful dequote.
9169.ip "\-q"
9170Don't dequote the key before lookup.
9171.ip "\-L\fIlevel\fP
9172For the syslog map only, it specifies the level
9173to use for the syslog call.
9174.ip "\-A"
9175When rebuilding an alias file,
9176the
9177.b \-A
9178flag causes duplicate entries in the text version
9179to be merged.
9180For example, two entries:
9181.(b
9182list: user1, user2
9183list: user3
9184.)b
9185would be treated as though it were the single entry
9186.(b
9187list: user1, user2, user3
9188.)b
9189in the presence of the
9190.b \-A
9191flag.
9192.pp
9193Some additional flags are available for the host and dns maps:
9194.ip "\-d"
9195delay: specify the resolver's retransmission time interval (in seconds).
9196.ip "\-r"
9197retry: specify the number of times to retransmit a resolver query.
9198.pp
9199The dns map has another flag:
9200.ip "\-B"
9201basedomain: specify a domain that is always appended to queries.
9202.pp
9203The following additional flags are present in the ldap map only:
9204.ip "\-R"
9205Do not auto chase referrals. sendmail must be compiled with
9206.b \-DLDAP_REFERRALS
9207to use this flag.
9208.ip "\-n"
9209Retrieve attribute names only.
9210.ip "\-V\fIsep\fP"
9211Retrieve both attributes name and value(s),
9212separated by
9213.i sep .
9214.ip "\-r\fIderef\fP"
9215Set the alias dereference option to one of never, always, search, or find.
9216.ip "\-s\fIscope\fP"
9217Set search scope to one of base, one (one level), or sub (subtree).
9218.ip "\-h\fIhost\fP"
9219LDAP server hostname.
9220Some LDAP libraries allow you to specify multiple, space-separated hosts for
9221redundancy.
9222In addition, each of the hosts listed can be followed by a colon and a port
9223number to override the default LDAP port.
9224.ip "\-p\fIport\fP"
9225LDAP service port.
9226.ip "\-H \fILDAPURI\fP"
9227Use the specified LDAP URI instead of specifying the hostname and port
9228separately with the the
9229.b \-h
9230and
9231.b \-p
9232options shown above.
9233For example,
9234.(b
9235-h server.example.com -p 389 -b dc=example,dc=com
9236.)b
9237is equivalent to
9238.(b
9239-H ldap://server.example.com:389 -b dc=example,dc=com
9240.)b
9241If the LDAP library supports it,
9242the LDAP URI format however can also request LDAP over SSL by using
9243.b ldaps://
9244instead of
9245.b ldap:// .
9246For example:
9247.(b
9248O LDAPDefaultSpec=-H ldaps://ldap.example.com -b dc=example,dc=com
9249.)b
9250Similarly, if the LDAP library supports it,
9251It can also be used to specify a UNIX domain socket using
9252.b ldapi:// :
9253.(b
9254O LDAPDefaultSpec=-H ldapi://socketfile -b dc=example,dc=com
9255.)b
9256.ip "\-b\fIbase\fP"
9257LDAP search base.
9258.ip "\-l\fItimelimit\fP"
9259Time limit for LDAP queries.
9260.ip "\-Z\fIsizelimit\fP"
9261Size (number of matches) limit for LDAP or DNS queries.
9262.ip "\-d\fIdistinguished_name\fP"
9263The distinguished name to use to login to the LDAP server.
9264.ip "\-M\fImethod\fP"
9265The method to authenticate to the LDAP server.
9266Should be one of
9267.b LDAP_AUTH_NONE ,
9268.b LDAP_AUTH_SIMPLE ,
9269or
9270.b LDAP_AUTH_KRBV4 .
9271.ip "\-P\fIpasswordfile\fP"
9272The file containing the secret key for the
9273.b LDAP_AUTH_SIMPLE
9274authentication method
9275or the name of the Kerberos ticket file for
9276.b LDAP_AUTH_KRBV4 .
9277.ip "\-1"
9278Force LDAP searches to only succeed if a single match is found.
9279If multiple values are found,
9280the search is treated as if no match was found.
9281.ip "\-w\fIversion\fP"
9282Set the LDAP API/protocol version to use.
9283The default depends on the LDAP client libraries in use.
9284For example,
9285.b "\-w 3"
9286will cause
9287.i sendmail
9288to use LDAPv3 when communicating with the LDAP server.
9289.ip "\-K"
9290Treat the LDAP search key as multi-argument and
9291replace %1 through %9 in the key with
9292the LDAP escaped contents of the lookup arguments specified in the map lookup.
9293.pp
9294The
9295.i dbm
9296map appends the strings
9297.q \&.pag
9298and
9299.q \&.dir
9300to the given filename;
9301the
9302.i hash
9303and
9304.i btree
9305maps append
9306.q \&.db .
9307For example, the map specification
9308.(b
9309Kuucp dbm \-o \-N /etc/mail/uucpmap
9310.)b
9311specifies an optional map named
9312.q uucp
9313of class
9314.q dbm ;
9315it always has null bytes at the end of every string,
9316and the data is located in
9317/etc/mail/uucpmap.{dir,pag}.
9318.pp
9319The program
9320.i makemap (8)
9321can be used to build any of the three database-oriented maps.
9322It takes the following flags:
9323.ip \-f
9324Do not fold upper to lower case in the map.
9325.ip \-N
9326Include null bytes in keys.
9327.ip \-o
9328Append to an existing (old) file.
9329.ip \-r
9330Allow replacement of existing keys;
9331normally, re-inserting an existing key is an error.
9332.ip \-v
9333Print what is happening.
9334.lp
9335The
9336.i sendmail
9337daemon does not have to be restarted to read the new maps
9338as long as you change them in place;
9339file locking is used so that the maps won't be read
9340while they are being updated.
9341.pp
9342New classes can be added in the routine
9343.b setupmaps
9344in file
9345.b conf.c .
9346.sh 2 "Q \*- Queue Group Declaration"
9347.pp
9348In addition to the option
9349.i QueueDirectory,
9350queue groups can be declared that define a (group of) queue directories
9351under a common name.
9352The syntax is as follows:
9353.(b F
9354.b Q \c
9355.i name
9356{, \c
9357.i field =\c
9358.i value \|}+
9359.)b
9360where
9361.i name
9362is the symbolic name of the queue group under which
9363it can be referenced in various places
9364and the
9365.q field=value
9366pairs define attributes of the queue group.
9367The name must only consist of alphanumeric characters.
9368Fields are:
9369.ip Flags
9370Flags for this queue group.
9371.ip Nice
9372The nice(2) increment for the queue group.
9373This value must be greater or equal zero.
9374.ip Interval
9375The time between two queue runs.
9376.ip Path
9377The queue directory of the group (required).
9378.ip Runners
9379The number of parallel runners processing the queue.
9380Note that
9381.b F=f
9382must be set if this value is greater than one.
9383.ip Jobs
9384The maximum number of jobs (messages delivered) per queue run.
9385.ip recipients
9386The maximum number of recipients per envelope.
9387Envelopes with more than this number of recipients will be split
9388into multiple envelopes in the same queue directory.
9389The default value 0 means no limit.
9390.lp
9391Only the first character of the field name is checked.
9392.pp
9393By default, a queue group named
9394.i mqueue
9395is defined that uses the value of the
9396.i QueueDirectory
9397option as path.
9398Notice: all paths that are used for queue groups must
9399be subdirectories of
9400.i QueueDirectory .
9401Since they can be symbolic links, this isn't a real restriction,
9402If
9403.i QueueDirectory
9404uses a wildcard, then the directory one level up is considered
9405the ``base'' directory which all other queue directories must share.
9406Please make sure that the queue directories do not overlap,
9407e.g., do not specify
9408.(b
9409O QueueDirectory=/var/spool/mqueue/*
9410Qone, P=/var/spool/mqueue/dir1
9411Qtwo, P=/var/spool/mqueue/dir2
9412.)b
9413because this also includes
9414.q dir1
9415and
9416.q dir2
9417in the default queue group.
9418However,
9419.(b
9420O QueueDirectory=/var/spool/mqueue/main*
9421Qone, P=/var/spool/mqueue/dir
9422Qtwo, P=/var/spool/mqueue/other*
9423.)b
9424is a valid queue group specification.
9425.pp
9426Options listed in the ``Flags'' field can be used to modify
9427the behavior of a queue group.
9428The ``f'' flag must be set if multiple queue runners are
9429supposed to work on the entries in a queue group.
9430Otherwise
9431.i sendmail
9432will work on the entries strictly sequentially.
9433.pp
9434The ``Interval'' field sets the time between queue runs.
9435If no queue group specific interval is set, then the parameter of the
9436.b -q
9437option from the command line is used.
9438.pp
9439To control the overall number of concurrently active queue runners
9440the option
9441.b MaxQueueChildren
9442can be set.
9443This limits the number of processes used for running the queues to
9444.b MaxQueueChildren ,
9445though at any one time fewer processes may be active
9446as a result of queue options, completed queue runs, system load, etc.
9447.pp
9448The maximum number of queue runners for an individual queue group can be
9449controlled via the
9450.b Runners
9451option.
9452If set to 0, entries in the queue will not be processed, which
9453is useful to ``quarantine'' queue files.
9454The number of runners per queue group may also be set with the option
9455.b MaxRunnersPerQueue ,
9456which applies to queue groups that have no individual limit.
9457That is, the default value for
9458.b Runners
9459is
9460.b MaxRunnersPerQueue
9461if set, otherwise 1.
9462.pp
9463The field Jobs describes the maximum number of jobs
9464(messages delivered) per queue run, which is the queue group specific
9465value of
9466.b MaxQueueRunSize .
9467.pp
9468Notice: queue groups should be declared after all queue related options
9469have been set because queue groups take their defaults from those options.
9470If an option is set after a queue group declaration, the values of
9471options in the queue group are set to the defaults of
9472.i sendmail
9473unless explicitly set in the declaration.
9474.pp
9475Each envelope is assigned to a queue group based on the algorithm
9476described in section
9477``Queue Groups and Queue Directories''.
9478.sh 2 "X \*- Mail Filter (Milter) Definitions"
9479.pp
9480The
9481.i sendmail
9482Mail Filter API (Milter) is designed to allow third-party programs access
9483to mail messages as they are being processed in order to filter
9484meta-information and content.
9485They are declared in the configuration file as:
9486.(b F
9487.b X \c
9488.i name
9489{, \c
9490.i field =\c
9491.i value \|}*
9492.)b
9493where
9494.i name
9495is the name of the filter
9496(used internally only)
9497and the
9498.q field=name
9499pairs define attributes of the filter.
9500Also see the documentation for the
9501.b InputMailFilters
9502option for more information.
9503.pp
9504Fields are:
9505.(b
9506.ta 1i
9507Socket The socket specification
9508Flags Special flags for this filter
9509Timeouts Timeouts for this filter
9510.)b
9511Only the first character of the field name is checked
9512(it's case-sensitive).
9513.pp
9514The socket specification is one of the following forms:
9515.(b F
9516.b S= \c
9517.b inet \c
9518.b :
9519.i port
9520.b @
9521.i host
9522.)b
9523.(b F
9524.b S= \c
9525.b inet6 \c
9526.b :
9527.i port
9528.b @
9529.i host
9530.)b
9531.(b F
9532.b S= \c
9533.b local \c
9534.b :
9535.i path
9536.)b
9537The first two describe an IPv4 or IPv6 socket listening on a certain
9538.i port
9539at a given
9540.i host
9541or IP address.
9542The final form describes a named socket on the filesystem at the given
9543.i path .
9544.pp
9545The following flags may be set in the filter description.
9546.nr ii 4n
9547.ip R
9548Reject connection if filter unavailable.
9549.ip T
9550Temporary fail connection if filter unavailable.
9551.pp
9552If neither F=R nor F=T is specified, the message is passed through
9553.i sendmail
9554in case of filter errors as if the failing filters were not present.
9555.pp
9556The timeouts can be set using the four fields inside of the
9557.b T=
9558equate:
9559.nr ii 4n
9560.ip C
9561Timeout for connecting to a filter.
9562If set to 0, the system's
9563.i connect()
9564timeout will be used.
9565.ip S
9566Timeout for sending information from the MTA to a filter.
9567.ip R
9568Timeout for reading reply from the filter.
9569.ip E
9570Overall timeout between sending end-of-message to filter and waiting for
9571the final acknowledgment.
9572.pp
9573Note the separator between each timeout field is a
9574.b ';' .
9575The default values (if not set) are:
9576.b T=C:5m;S:10s;R:10s;E:5m
9577where
9578.b s
9579is seconds and
9580.b m
9581is minutes.
9582.pp
9583Examples:
9584.(b
9585Xfilter1, S=local:/var/run/f1.sock, F=R
9586Xfilter2, S=inet6:999@localhost, F=T, T=S:1s;R:1s;E:5m
9587Xfilter3, S=inet:3333@localhost, T=C:2m
9588.)b
9589.sh 2 "The User Database"
9590.pp
9591The user database is deprecated in favor of ``virtusertable''
9592and ``genericstable'' as explained in the file
9593.b cf/README .
9594If you have a version of
9595.i sendmail
9596with the user database package
9597compiled in,
9598the handling of sender and recipient addresses
9599is modified.
9600.pp
9601The location of this database is controlled with the
9602.b UserDatabaseSpec
9603option.
9604.sh 3 "Structure of the user database"
9605.pp
9606The database is a sorted (BTree-based) structure.
9607User records are stored with the key:
9608.(b
9609\fIuser-name\fP\fB:\fP\fIfield-name\fP
9610.)b
9611The sorted database format ensures that user records are clustered together.
9612Meta-information is always stored with a leading colon.
9613.pp
9614Field names define both the syntax and semantics of the value.
9615Defined fields include:
9616.nr ii 1i
9617.ip maildrop
9618The delivery address for this user.
9619There may be multiple values of this record.
9620In particular,
9621mailing lists will have one
9622.i maildrop
9623record for each user on the list.
9624.ip "mailname"
9625The outgoing mailname for this user.
9626For each outgoing name,
9627there should be an appropriate
9628.i maildrop
9629record for that name to allow return mail.
9630See also
9631.i :default:mailname .
9632.ip mailsender
9633Changes any mail sent to this address to have the indicated envelope sender.
9634This is intended for mailing lists,
9635and will normally be the name of an appropriate -request address.
9636It is very similar to the owner-\c
9637.i list
9638syntax in the alias file.
9639.ip fullname
9640The full name of the user.
9641.ip office-address
9642The office address for this user.
9643.ip office-phone
9644The office phone number for this user.
9645.ip office-fax
9646The office FAX number for this user.
9647.ip home-address
9648The home address for this user.
9649.ip home-phone
9650The home phone number for this user.
9651.ip home-fax
9652The home FAX number for this user.
9653.ip project
9654A (short) description of the project this person is affiliated with.
9655In the University this is often just the name of their graduate advisor.
9656.ip plan
9657A pointer to a file from which plan information can be gathered.
9658.pp
9659As of this writing,
9660only a few of these fields are actually being used by
9661.i sendmail :
9662.i maildrop
9663and
9664.i mailname .
9665A
9666.i finger
9667program that uses the other fields is planned.
9668.sh 3 "User database semantics"
9669.pp
9670When the rewriting rules submit an address to the local mailer,
9671the user name is passed through the alias file.
9672If no alias is found (or if the alias points back to the same address),
9673the name (with
9674.q :maildrop
9675appended)
9676is then used as a key in the user database.
9677If no match occurs (or if the maildrop points at the same address),
9678forwarding is tried.
9679.pp
9680If the first token of the user name returned by ruleset 0
9681is an
9682.q @
9683sign, the user database lookup is skipped.
9684The intent is that the user database will act as a set of defaults
9685for a cluster (in our case, the Computer Science Division);
9686mail sent to a specific machine should ignore these defaults.
9687.pp
9688When mail is sent,
9689the name of the sending user is looked up in the database.
9690If that user has a
9691.q mailname
9692record,
9693the value of that record is used as their outgoing name.
9694For example, I might have a record:
9695.(b
9696eric:mailname Eric.Allman@CS.Berkeley.EDU
9697.)b
9698This would cause my outgoing mail to be sent as Eric.Allman.
9699.pp
9700If a
9701.q maildrop
9702is found for the user,
9703but no corresponding
9704.q mailname
9705record exists,
9706the record
9707.q :default:mailname
9708is consulted.
9709If present, this is the name of a host to override the local host.
9710For example, in our case we would set it to
9711.q CS.Berkeley.EDU .
9712The effect is that anyone known in the database
9713gets their outgoing mail stamped as
9714.q user@CS.Berkeley.EDU ,
9715but people not listed in the database use the local hostname.
9716.sh 3 "Creating the database\**"
9717.(f
9718\**These instructions are known to be incomplete.
9719Other features are available which provide similar functionality,
9720e.g., virtual hosting and mapping local addresses into a
9721generic form as explained in cf/README.
9722.)f
9723.pp
9724The user database is built from a text file
9725using the
9726.i makemap
9727utility
9728(in the distribution in the makemap subdirectory).
9729The text file is a series of lines corresponding to userdb records;
9730each line has a key and a value separated by white space.
9731The key is always in the format described above \*-
9732for example:
9733.(b
9734eric:maildrop
9735.)b
9736This file is normally installed in a system directory;
9737for example, it might be called
9738.i /etc/mail/userdb .
9739To make the database version of the map, run the program:
9740.(b
9741makemap btree /etc/mail/userdb < /etc/mail/userdb
9742.)b
9743Then create a config file that uses this.
9744For example, using the V8 M4 configuration, include the
9745following line in your .mc file:
9746.(b
9747define(\`confUSERDB_SPEC\', /etc/mail/userdb)
9748.)b
9749.sh 1 "OTHER CONFIGURATION"
9750.pp
9751There are some configuration changes that can be made by
9752recompiling
9753.i sendmail .
9754This section describes what changes can be made
9755and what has to be modified to make them.
9756In most cases this should be unnecessary
9757unless you are porting
9758.i sendmail
9759to a new environment.
9760.sh 2 "Parameters in devtools/OS/$oscf"
9761.pp
9762These parameters are intended to describe the compilation environment,
9763not site policy,
9764and should normally be defined in the operating system
9765configuration file.
9766.b "This section needs a complete rewrite."
9767.ip NDBM
9768If set,
9769the new version of the DBM library
9770that allows multiple databases will be used.
9771If neither NDBM nor NEWDB are set,
9772a much less efficient method of alias lookup is used.
9773.ip NEWDB
9774If set, use the new database package from Berkeley (from 4.4BSD).
9775This package is substantially faster than DBM or NDBM.
9776If NEWDB and NDBM are both set,
9777.i sendmail
9778will read DBM files,
9779but will create and use NEWDB files.
9780.ip NIS
9781Include support for NIS.
9782If set together with
9783.i both
9784NEWDB and NDBM,
9785.i sendmail
9786will create both DBM and NEWDB files if and only if
9787an alias file includes the substring
9788.q /yp/
9789in the name.
9790This is intended for compatibility with Sun Microsystems'
9791.i mkalias
9792program used on YP masters.
9793.ip NISPLUS
9794Compile in support for NIS+.
9795.ip NETINFO
9796Compile in support for NetInfo (NeXT stations).
9797.ip LDAPMAP
9798Compile in support for LDAP X500 queries.
9799Requires libldap and liblber
9800from the Umich LDAP 3.2 or 3.3 release
9801or equivalent libraries for other LDAP libraries
9802such as OpenLDAP.
9803.ip HESIOD
9804Compile in support for Hesiod.
9805.ip MAP_NSD
9806Compile in support for IRIX NSD lookups.
9807.ip MAP_REGEX
9808Compile in support for regular expression matching.
9809.ip DNSMAP
9810Compile in support for DNS map lookups in the
9811.i sendmail.cf
9812file.
9813.ip PH_MAP
9814Compile in support for ph lookups.
9815.ip SASL
9816Compile in support for SASL,
9817a required component for SMTP Authentication support.
9818.ip STARTTLS
9819Compile in support for STARTTLS.
9820.ip EGD
9821Compile in support for the "Entropy Gathering Daemon"
9822to provide better random data for TLS.
9823.ip TCPWRAPPERS
9824Compile in support for TCP Wrappers.
9825.ip _PATH_SENDMAILCF
9826The pathname of the sendmail.cf file.
9827.ip _PATH_SENDMAILPID
9828The pathname of the sendmail.pid file.
9829.ip SM_CONF_SHM
9830Compile in support for shared memory, see section about
9831"/var/spool/mqueue".
9832.ip MILTER
9833Compile in support for contacting external mail filters built with the
9834Milter API.
9835.pp
9836There are also several compilation flags to indicate the environment
9837such as
9838.q _AIX3
9839and
9840.q _SCO_unix_ .
9841See the sendmail/README
9842file for the latest scoop on these flags.
9843.sh 2 "Parameters in sendmail/conf.h"
9844.pp
9845Parameters and compilation options
9846are defined in conf.h.
9847Most of these need not normally be tweaked;
9848common parameters are all in sendmail.cf.
9849However, the sizes of certain primitive vectors, etc.,
9850are included in this file.
9851The numbers following the parameters
9852are their default value.
9853.pp
9854This document is not the best source of information
9855for compilation flags in conf.h \(em
9856see sendmail/README or sendmail/conf.h itself.
9857.nr ii 1.2i
9858.ip "MAXLINE [2048]"
9859The maximum line length of any input line.
9860If message lines exceed this length
9861they will still be processed correctly;
9862however, header lines,
9863configuration file lines,
9864alias lines,
9865etc.,
9866must fit within this limit.
9867.ip "MAXNAME [256]"
9868The maximum length of any name,
9869such as a host or a user name.
9870.ip "MAXPV [256]"
9871The maximum number of parameters to any mailer.
9872This limits the number of recipients that may be passed in one transaction.
9873It can be set to any arbitrary number above about 10,
9874since
9875.i sendmail
9876will break up a delivery into smaller batches as needed.
9877A higher number may reduce load on your system, however.
9878.ip "MAXQUEUEGROUPS [50]"
9879The maximum number of queue groups.
9880.ip "MAXATOM [1000]"
9881The maximum number of atoms
9882(tokens)
9883in a single address.
9884For example,
9885the address
9886.q "eric@CS.Berkeley.EDU"
9887is seven atoms.
9888.ip "MAXMAILERS [25]"
9889The maximum number of mailers that may be defined
9890in the configuration file.
9891This value is defined in include/sendmail/sendmail.h.
9892.ip "MAXRWSETS [200]"
9893The maximum number of rewriting sets
9894that may be defined.
9895The first half of these are reserved for numeric specification
9896(e.g., ``S92''),
9897while the upper half are reserved for auto-numbering
9898(e.g., ``Sfoo'').
9899Thus, with a value of 200 an attempt to use ``S99'' will succeed,
9900but ``S100'' will fail.
9901.ip "MAXPRIORITIES [25]"
9902The maximum number of values for the
9903.q Precedence:
9904field that may be defined
9905(using the
9906.b P
9907line in sendmail.cf).
9908.ip "MAXUSERENVIRON [100]"
9909The maximum number of items in the user environment
9910that will be passed to subordinate mailers.
9911.ip "MAXMXHOSTS [100]"
9912The maximum number of MX records we will accept for any single host.
9913.ip "MAXMAPSTACK [12]"
9914The maximum number of maps that may be "stacked" in a
9915.b sequence
9916class map.
9917.ip "MAXMIMEARGS [20]"
9918The maximum number of arguments in a MIME Content-Type: header;
9919additional arguments will be ignored.
9920.ip "MAXMIMENESTING [20]"
9921The maximum depth to which MIME messages may be nested
9922(that is, nested Message or Multipart documents;
9923this does not limit the number of components in a single Multipart document).
9924.ip "MAXDAEMONS [10]"
9925The maximum number of sockets sendmail will open for accepting connections
9926on different ports.
9927.ip "MAXMACNAMELEN [25]"
9928The maximum length of a macro name.
9929.lp
9930A number of other compilation options exist.
9931These specify whether or not specific code should be compiled in.
9932Ones marked with \(dg
9933are 0/1 valued.
9934.nr ii 1.2i
9935.ip NETINET\(dg
9936If set,
9937support for Internet protocol networking is compiled in.
9938Previous versions of
9939.i sendmail
9940referred to this as
9941.sm DAEMON ;
9942this old usage is now incorrect.
9943Defaults on;
9944turn it off in the Makefile
9945if your system doesn't support the Internet protocols.
9946.ip NETINET6\(dg
9947If set,
9948support for IPv6 networking is compiled in.
9949It must be separately enabled by adding
9950.b DaemonPortOptions
9951settings.
9952.ip NETISO\(dg
9953If set,
9954support for ISO protocol networking is compiled in
9955(it may be appropriate to #define this in the Makefile instead of conf.h).
9956.ip NETUNIX\(dg
9957If set,
9958support for UNIX domain sockets is compiled in.
9959This is used for control socket support.
9960.ip LOG
9961If set,
9962the
9963.i syslog
9964routine in use at some sites is used.
9965This makes an informational log record
9966for each message processed,
9967and makes a higher priority log record
9968for internal system errors.
9969.b "STRONGLY RECOMMENDED"
9970\(em if you want no logging, turn it off in the configuration file.
9971.ip MATCHGECOS\(dg
9972Compile in the code to do ``fuzzy matching'' on the GECOS field
9973in /etc/passwd.
9974This also requires that the
9975.b MatchGECOS
9976option be turned on.
9977.ip NAMED_BIND\(dg
9978Compile in code to use the
9979Berkeley Internet Name Domain (BIND) server
9980to resolve TCP/IP host names.
9981.ip NOTUNIX
9982If you are using a non-UNIX mail format,
9983you can set this flag to turn off special processing
9984of UNIX-style
9985.q "From "
9986lines.
9987.ip USERDB\(dg
9988Include the
9989.b experimental
9990Berkeley user information database package.
9991This adds a new level of local name expansion
9992between aliasing and forwarding.
9993It also uses the NEWDB package.
9994This may change in future releases.
9995.lp
9996The following options are normally turned on
9997in per-operating-system clauses in conf.h.
9998.ip IDENTPROTO\(dg
9999Compile in the IDENT protocol as defined in RFC 1413.
10000This defaults on for all systems except Ultrix,
10001which apparently has the interesting
10002.q feature
10003that when it receives a
10004.q "host unreachable"
10005message it closes all open connections to that host.
10006Since some firewall gateways send this error code
10007when you access an unauthorized port (such as 113, used by IDENT),
10008Ultrix cannot receive email from such hosts.
10009.ip SYSTEM5
10010Set all of the compilation parameters appropriate for System V.
10011.ip HASFLOCK\(dg
10012Use Berkeley-style
10013.b flock
10014instead of System V
10015.b lockf
10016to do file locking.
10017Due to the highly unusual semantics of locks
10018across forks in
10019.b lockf ,
10020this should always be used if at all possible.
10021.ip HASINITGROUPS
10022Set this if your system has the
10023.i initgroups()
10024call
10025(if you have multiple group support).
10026This is the default if SYSTEM5 is
10027.i not
10028defined or if you are on HPUX.
10029.ip HASUNAME
10030Set this if you have the
10031.i uname (2)
10032system call (or corresponding library routine).
10033Set by default if
10034SYSTEM5
10035is set.
10036.ip HASGETDTABLESIZE
10037Set this if you have the
10038.i getdtablesize (2)
10039system call.
10040.ip HASWAITPID
10041Set this if you have the
10042.i haswaitpid (2)
10043system call.
10044.ip FAST_PID_RECYCLE
10045Set this if your system can possibly
10046reuse the same pid in the same second of time.
10047.ip SFS_TYPE
10048The mechanism that can be used to get file system capacity information.
10049The values can be one of
10050SFS_USTAT (use the ustat(2) syscall),
10051SFS_4ARGS (use the four argument statfs(2) syscall),
10052SFS_VFS (use the two argument statfs(2) syscall including <sys/vfs.h>),
10053SFS_MOUNT (use the two argument statfs(2) syscall including <sys/mount.h>),
10054SFS_STATFS (use the two argument statfs(2) syscall including <sys/statfs.h>),
10055SFS_STATVFS (use the two argument statfs(2) syscall including <sys/statvfs.h>),
10056or
10057SFS_NONE (no way to get this information).
10058.ip LA_TYPE
10059The load average type.
10060Details are described below.
10061.lp
10062The are several built-in ways of computing the load average.
10063.i Sendmail
10064tries to auto-configure them based on imperfect guesses;
10065you can select one using the
10066.i cc
10067option
10068.b \-DLA_TYPE= \c
10069.i type ,
10070where
10071.i type
10072is:
10073.ip LA_INT
10074The kernel stores the load average in the kernel as an array of long integers.
10075The actual values are scaled by a factor FSCALE
10076(default 256).
10077.ip LA_SHORT
10078The kernel stores the load average in the kernel as an array of short integers.
10079The actual values are scaled by a factor FSCALE
10080(default 256).
10081.ip LA_FLOAT
10082The kernel stores the load average in the kernel as an array of
10083double precision floats.
10084.ip LA_MACH
10085Use MACH-style load averages.
10086.ip LA_SUBR
10087Call the
10088.i getloadavg
10089routine to get the load average as an array of doubles.
10090.ip LA_ZERO
10091Always return zero as the load average.
10092This is the fallback case.
10093.lp
10094If type
10095.sm LA_INT ,
10096.sm LA_SHORT ,
10097or
10098.sm LA_FLOAT
10099is specified,
10100you may also need to specify
10101.sm _PATH_UNIX
10102(the path to your system binary)
10103and
10104.sm LA_AVENRUN
10105(the name of the variable containing the load average in the kernel;
10106usually
10107.q _avenrun
10108or
10109.q avenrun ).
10110.sh 2 "Configuration in sendmail/conf.c"
10111.pp
10112The following changes can be made in conf.c.
10113.sh 3 "Built-in Header Semantics"
10114.pp
10115Not all header semantics are defined in the configuration file.
10116Header lines that should only be included by certain mailers
10117(as well as other more obscure semantics)
10118must be specified in the
10119.i HdrInfo
10120table in
10121.i conf.c .
10122This table contains the header name
10123(which should be in all lower case)
10124and a set of header control flags (described below),
10125The flags are:
10126.ip H_ACHECK
10127Normally when the check is made to see if a header line is compatible
10128with a mailer,
10129.i sendmail
10130will not delete an existing line.
10131If this flag is set,
10132.i sendmail
10133will delete
10134even existing header lines.
10135That is,
10136if this bit is set and the mailer does not have flag bits set
10137that intersect with the required mailer flags
10138in the header definition in
10139sendmail.cf,
10140the header line is
10141.i always
10142deleted.
10143.ip H_EOH
10144If this header field is set,
10145treat it like a blank line,
10146i.e.,
10147it will signal the end of the header
10148and the beginning of the message text.
10149.ip H_FORCE
10150Add this header entry
10151even if one existed in the message before.
10152If a header entry does not have this bit set,
10153.i sendmail
10154will not add another header line if a header line
10155of this name already existed.
10156This would normally be used to stamp the message
10157by everyone who handled it.
10158.ip H_TRACE
10159If set,
10160this is a timestamp
10161(trace)
10162field.
10163If the number of trace fields in a message
10164exceeds a preset amount
10165the message is returned
10166on the assumption that it has an aliasing loop.
10167.ip H_RCPT
10168If set,
10169this field contains recipient addresses.
10170This is used by the
10171.b \-t
10172flag to determine who to send to
10173when it is collecting recipients from the message.
10174.ip H_FROM
10175This flag indicates that this field
10176specifies a sender.
10177The order of these fields in the
10178.i HdrInfo
10179table specifies
10180.i sendmail 's
10181preference
10182for which field to return error messages to.
10183.ip H_ERRORSTO
10184Addresses in this header should receive error messages.
10185.ip H_CTE
10186This header is a Content-Transfer-Encoding header.
10187.ip H_CTYPE
10188This header is a Content-Type header.
10189.ip H_STRIPVAL
10190Strip the value from the header (for Bcc:).
10191.nr ii 5n
10192.lp
10193Let's look at a sample
10194.i HdrInfo
10195specification:
10196.(b
10197.ta 4n +\w'"content-transfer-encoding", 'u
10198struct hdrinfo HdrInfo[] =
10199\&{
10200 /* originator fields, most to least significant */
10201 "resent-sender", H_FROM,
10202 "resent-from", H_FROM,
10203 "sender", H_FROM,
10204 "from", H_FROM,
10205 "full-name", H_ACHECK,
10206 "errors-to", H_FROM\^|\^H_ERRORSTO,
10207 /* destination fields */
10208 "to", H_RCPT,
10209 "resent-to", H_RCPT,
10210 "cc", H_RCPT,
10211 "bcc", H_RCPT\^|\^H_STRIPVAL,
10212 /* message identification and control */
10213 "message", H_EOH,
10214 "text", H_EOH,
10215 /* trace fields */
10216 "received", H_TRACE\^|\^H_FORCE,
10217 /* miscellaneous fields */
10218 "content-transfer-encoding", H_CTE,
10219 "content-type", H_CTYPE,
10220
10221 NULL, 0,
10222};
10223.)b
10224This structure indicates that the
10225.q To: ,
10226.q Resent-To: ,
10227and
10228.q Cc:
10229fields
10230all specify recipient addresses.
10231Any
10232.q Full-Name:
10233field will be deleted unless the required mailer flag
10234(indicated in the configuration file)
10235is specified.
10236The
10237.q Message:
10238and
10239.q Text:
10240fields will terminate the header;
10241these are used by random dissenters around the network world.
10242The
10243.q Received:
10244field will always be added,
10245and can be used to trace messages.
10246.pp
10247There are a number of important points here.
10248First,
10249header fields are not added automatically just because they are in the
10250.i HdrInfo
10251structure;
10252they must be specified in the configuration file
10253in order to be added to the message.
10254Any header fields mentioned in the configuration file but not
10255mentioned in the
10256.i HdrInfo
10257structure have default processing performed;
10258that is,
10259they are added unless they were in the message already.
10260Second,
10261the
10262.i HdrInfo
10263structure only specifies cliched processing;
10264certain headers are processed specially by ad hoc code
10265regardless of the status specified in
10266.i HdrInfo .
10267For example,
10268the
10269.q Sender:
10270and
10271.q From:
10272fields are always scanned on ARPANET mail
10273to determine the sender\**;
10274.(f
10275\**Actually, this is no longer true in SMTP;
10276this information is contained in the envelope.
10277The older ARPANET protocols did not completely distinguish
10278envelope from header.
10279.)f
10280this is used to perform the
10281.q "return to sender"
10282function.
10283The
10284.q "From:"
10285and
10286.q "Full-Name:"
10287fields are used to determine the full name of the sender
10288if possible;
10289this is stored in the macro
10290.b $x
10291and used in a number of ways.
10292.sh 3 "Restricting Use of Email"
10293.pp
10294If it is necessary to restrict mail through a relay,
10295the
10296.i checkcompat
10297routine can be modified.
10298This routine is called for every recipient address.
10299It returns an exit status
10300indicating the status of the message.
10301The status
10302.sm EX_OK
10303accepts the address,
10304.sm EX_TEMPFAIL
10305queues the message for a later try,
10306and other values
10307(commonly
10308.sm EX_UNAVAILABLE )
10309reject the message.
10310It is up to
10311.i checkcompat
10312to print an error message
10313(using
10314.i usrerr )
10315if the message is rejected.
10316For example,
10317.i checkcompat
10318could read:
10319.(b
10320.re
10321.sz -1
10322.ta 4n +4n +4n +4n +4n +4n +4n
10323int
10324checkcompat(to, e)
10325 register ADDRESS *to;
10326 register ENVELOPE *e;
10327\&{
10328 register STAB *s;
10329
10330 s = stab("private", ST_MAILER, ST_FIND);
10331 if (s != NULL && e\->e_from.q_mailer != LocalMailer &&
10332 to->q_mailer == s->s_mailer)
10333 {
10334 usrerr("No private net mail allowed through this machine");
10335 return (EX_UNAVAILABLE);
10336 }
10337 if (MsgSize > 50000 && bitnset(M_LOCALMAILER, to\->q_mailer))
10338 {
10339 usrerr("Message too large for non-local delivery");
10340 e\->e_flags |= EF_NORETURN;
10341 return (EX_UNAVAILABLE);
10342 }
10343 return (EX_OK);
10344}
10345.sz
10346.)b
10347This would reject messages greater than 50000 bytes
10348unless they were local.
10349The
10350.i EF_NORETURN
10351flag can be set in
10352.i e\(->e_flags
10353to suppress the return of the actual body
10354of the message in the error return.
10355The actual use of this routine is highly dependent on the
10356implementation,
10357and use should be limited.
10358.sh 3 "New Database Map Classes"
10359.pp
10360New key maps can be added by creating a class initialization function
10361and a lookup function.
10362These are then added to the routine
10363.i setupmaps.
10364.pp
10365The initialization function is called as
10366.(b
10367\fIxxx\fP_map_init(MAP *map, char *args)
10368.)b
10369The
10370.i map
10371is an internal data structure.
10372The
10373.i args
10374is a pointer to the portion of the configuration file line
10375following the map class name;
10376flags and filenames can be extracted from this line.
10377The initialization function must return
10378.sm true
10379if it successfully opened the map,
10380.sm false
10381otherwise.
10382.pp
10383The lookup function is called as
10384.(b
10385\fIxxx\fP_map_lookup(MAP *map, char buf[], char **av, int *statp)
10386.)b
10387The
10388.i map
10389defines the map internally.
10390The
10391.i buf
10392has the input key.
10393This may be (and often is) used destructively.
10394The
10395.i av
10396is a list of arguments passed in from the rewrite line.
10397The lookup function should return a pointer to the new value.
10398If the map lookup fails,
10399.i *statp
10400should be set to an exit status code;
10401in particular, it should be set to
10402.sm EX_TEMPFAIL
10403if recovery is to be attempted by the higher level code.
10404.sh 3 "Queueing Function"
10405.pp
10406The routine
10407.i shouldqueue
10408is called to decide if a message should be queued
10409or processed immediately.
10410Typically this compares the message priority to the current load average.
10411The default definition is:
10412.(b
10413bool
10414shouldqueue(pri, ctime)
10415 long pri;
10416 time_t ctime;
10417{
10418 if (CurrentLA < QueueLA)
10419 return false;
10420 return (pri > (QueueFactor / (CurrentLA \- QueueLA + 1)));
10421}
10422.)b
10423If the current load average
10424(global variable
10425.i CurrentLA ,
10426which is set before this function is called)
10427is less than the low threshold load average
10428(option
10429.b x ,
10430variable
10431.i QueueLA ),
10432.i shouldqueue
10433returns
10434.sm false
10435immediately
10436(that is, it should
10437.i not
10438queue).
10439If the current load average exceeds the high threshold load average
10440(option
10441.b X ,
10442variable
10443.i RefuseLA ),
10444.i shouldqueue
10445returns
10446.sm true
10447immediately.
10448Otherwise, it computes the function based on the message priority,
10449the queue factor
10450(option
10451.b q ,
10452global variable
10453.i QueueFactor ),
10454and the current and threshold load averages.
10455.pp
10456An implementation wishing to take the actual age of the message into account
10457can also use the
10458.i ctime
10459parameter,
10460which is the time that the message was first submitted to
10461.i sendmail .
10462Note that the
10463.i pri
10464parameter is already weighted
10465by the number of times the message has been tried
10466(although this tends to lower the priority of the message with time);
10467the expectation is that the
10468.i ctime
10469would be used as an
10470.q "escape clause"
10471to ensure that messages are eventually processed.
10472.sh 3 "Refusing Incoming SMTP Connections"
10473.pp
10474The function
10475.i refuseconnections
10476returns
10477.sm true
10478if incoming SMTP connections should be refused.
10479The current implementation is based exclusively on the current load average
10480and the refuse load average option
10481(option
10482.b X ,
10483global variable
10484.i RefuseLA ):
10485.(b
10486bool
10487refuseconnections()
10488{
10489 return (RefuseLA > 0 && CurrentLA >= RefuseLA);
10490}
10491.)b
10492A more clever implementation
10493could look at more system resources.
10494.sh 3 "Load Average Computation"
10495.pp
10496The routine
10497.i getla
10498returns the current load average (as a rounded integer).
10499The distribution includes several possible implementations.
10500If you are porting to a new environment
10501you may need to add some new tweaks.\**
10502.(f
10503\**If you do, please send updates to
10504sendmail@Sendmail.ORG.
10505.)f
10506.sh 2 "Configuration in sendmail/daemon.c"
10507.pp
10508The file
10509.i sendmail/daemon.c
10510contains a number of routines that are dependent
10511on the local networking environment.
10512The version supplied assumes you have BSD style sockets.
10513.pp
10514In previous releases,
10515we recommended that you modify the routine
10516.i maphostname
10517if you wanted to generalize
10518.b $[
10519\&...\&
10520.b $]
10521lookups.
10522We now recommend that you create a new keyed map instead.
10523.sh 2 "LDAP"
10524.pp
10525In this section we assume that
10526.i sendmail
10527has been compiled with support for LDAP.
10528.sh 3 "LDAP Recursion"
10529.pp
10530LDAP Recursion allows you to add types to the search attributes on an
10531LDAP map specification.
10532The syntax is:
10533.ip "\-v \fIATTRIBUTE\fP[:\fITYPE\fP[:\fIOBJECTCLASS\fP[|\fIOBJECTCLASS\fP|...]]]
10534.pp
10535The new \fITYPE\fPs are:
10536.nr ii 1i
10537.ip NORMAL
10538This attribute type specifies the attribute to add to the results string.
10539This is the default.
10540.ip DN
10541Any matches for this attribute are expected to have a value of a
10542fully qualified distinguished name.
10543.i sendmail
10544will lookup that DN and apply the attributes requested to the
10545returned DN record.
10546.ip FILTER
10547Any matches for this attribute are expected to have a value of an
10548LDAP search filter.
10549.i sendmail
10550will perform a lookup with the same parameters as the original
10551search but replaces the search filter with the one specified here.
10552.ip URL
10553Any matches for this attribute are expected to have a value of an LDAP URL.
10554.i sendmail
10555will perform a lookup of that URL and use the results from the attributes
10556named in that URL.
10557Note however that the search is done using the current LDAP connection,
10558regardless of what is specified as the scheme, LDAP host, and LDAP
10559port in the LDAP URL.
10560.lp
10561Any untyped attributes are considered
10562.sm NORMAL
10563attributes as described above.
10564.pp
10565The optional \fIOBJECTCLASS\fP (| separated) list contains the
10566objectClass values for which that attribute applies.
10567If the list is given,
10568the attribute named will only be used if the LDAP record being returned is a
10569member of that object class.
10570Note that if these new value attribute \fITYPE\fPs are used in an
10571AliasFile
10572option setting, it will need to be double quoted to prevent
10573.i sendmail
10574from misparsing the colons.
10575.pp
10576Note that LDAP recursion attributes which do not ultimately point to an
10577LDAP record are not considered an error.
10578.sh 4 "Example"
10579.pp
10580Since examples usually help clarify, here is an example which uses all
10581four of the new types:
10582.(b
10583O LDAPDefaultSpec=-h ldap.example.com -b dc=example,dc=com
10584
10585Kexample ldap
10586 -z,
10587 -k (&(objectClass=sendmailMTAAliasObject)(sendmailMTAKey=%0))
10588 -v sendmailMTAAliasValue,mail:NORMAL:inetOrgPerson,
10589 uniqueMember:DN:groupOfUniqueNames,
10590 sendmailMTAAliasSearch:FILTER:sendmailMTAAliasObject,
10591 sendmailMTAAliasURL:URL:sendmailMTAAliasObject
10592.)b
10593.pp
10594That definition specifies that:
10595.bu
10596Any value in a
10597.sm sendmailMTAAliasValue
10598attribute will be added to the result string regardless of object class.
10599.bu
10600The
10601.sm mail
10602attribute will be added to the result string if
10603the LDAP record is a member of the
10604.sm inetOrgPerson
10605object class.
10606.bu
10607The
10608.sm uniqueMember
10609attribute is a recursive attribute, used only in
10610.sm groupOfUniqueNames
10611records, and should contain an LDAP DN pointing to another LDAP record.
10612The desire here is to return the
10613.sm mail
10614attribute from those DNs.
10615.bu
10616The
10617.sm sendmailMTAAliasSearch
10618attribute and
10619.sm sendmailMTAAliasURL
10620are both used only if referenced in a
10621.sm sendmailMTAAliasObject .
10622They are both recursive, the first for a new LDAP search string and the
10623latter for an LDAP URL.
10624.sh 2 "STARTTLS"
10625.pp
10626In this section we assume that
10627.i sendmail
10628has been compiled with support for STARTTLS.
10629To properly understand the use of STARTTLS in
10630.i sendmail ,
10631it is necessary to understand at least some basics about X.509 certificates
10632and public key cryptography.
10633This information can be found in books about SSL/TLS
10634or on WWW sites, e.g.,
10635.q http://www.OpenSSL.org/ .
10636.sh 3 "Certificates for STARTTLS"
10637.pp
10638When acting as a server,
10639.i sendmail
10640requires X.509 certificates to support STARTTLS:
10641one as certificate for the server (ServerCertFile and corresponding
10642private ServerKeyFile)
10643at least one root CA (CACertFile),
10644i.e., a certificate that is used to sign other certificates,
10645and a path to a directory which contains other CAs (CACertPath).
10646The file specified via
10647CACertFile
10648can contain several certificates of CAs.
10649The DNs of these certificates are sent
10650to the client during the TLS handshake (as part of the
10651CertificateRequest) as the list of acceptable CAs.
10652However, do not list too many root CAs in that file, otherwise
10653the TLS handshake may fail; e.g.,
10654.(b
10655error:14094417:SSL routines:SSL3_READ_BYTES:
10656sslv3 alert illegal parameter:s3_pkt.c:964:SSL alert number 47
10657.)b
10658You should probably put only the CA cert into that file
10659that signed your own cert(s), or at least only those you trust.
10660The CACertPath directory must contain the hashes of each CA certificate
10661as filenames (or as links to them).
10662Symbolic links can be generated with the following
10663two (Bourne) shell commands:
10664.(b
10665C=FileName_of_CA_Certificate
10666ln -s $C `openssl x509 -noout -hash < $C`.0
10667.)b
10668An X.509 certificate is also required for authentication in client mode
10669(ClientCertFile and corresponding private ClientKeyFile), however,
10670.i sendmail
10671will always use STARTTLS when offered by a server.
10672The client and server certificates can be identical.
10673Certificates can be obtained from a certificate authority
10674or created with the help of OpenSSL.
10675The required format for certificates and private keys is PEM.
10676To allow for automatic startup of sendmail, private keys
10677(ServerKeyFile, ClientKeyFile)
10678must be stored unencrypted.
10679The keys are only protected by the permissions of the file system.
10680Never make a private key available to a third party.
10681.sh 3 "PRNG for STARTTLS"
10682.pp
10683STARTTLS requires a strong pseudo random number generator (PRNG)
10684to operate properly.
10685Depending on the TLS library you use, it may be required to explicitly
10686initialize the PRNG with random data.
10687OpenSSL makes use of
10688.b /dev/urandom(4)
10689if available (this corresponds to the compile flag HASURANDOMDEV).
10690On systems which lack this support, a random file must be specified in the
10691.i sendmail.cf
10692file using the option RandFile.
10693It is
10694.b strongly
10695advised to use the "Entropy Gathering Daemon" EGD
10696from Brian Warner on those systems to provide useful random data.
10697In this case,
10698.i sendmail
10699must be compiled with the flag EGD, and the
10700RandFile option must point to the EGD socket.
10701If neither
10702.b /dev/urandom(4)
10703nor EGD are available, you have to make sure
10704that useful random data is available all the time in RandFile.
10705If the file hasn't been modified in the last 10 minutes before
10706it is supposed to be used by
10707.i sendmail
10708the content is considered obsolete.
10709One method for generating this file is:
10710.(b
10711openssl rand -out /etc/mail/randfile -rand \c
10712.i /path/to/file:... \c
10713256
10714.)b
10715See the OpenSSL documentation for more information.
10716In this case, the PRNG for TLS is only
10717seeded with other random data if the
10718.b DontBlameSendmail
10719option
10720.b InsufficientEntropy
10721is set.
10722This is most likely not sufficient for certain actions, e.g.,
10723generation of (temporary) keys.
10724.pp
10725Please see the OpenSSL documentation or other sources
10726for further information about certificates, their creation and their usage,
10727the importance of a good PRNG, and other aspects of TLS.
10728.sh 2 "Encoding of STARTTLS and AUTH related Macros"
10729.pp
10730Macros that contain STARTTLS and AUTH related data which comes from outside
10731sources, e.g., all macros containing information from certificates,
10732are encoded to avoid problems with non-printable or special characters.
10733The latter are '\\', '<', '>', '(', ')', '"', '+', and ' '.
10734All of these characters are replaced by their value in hexadecimal
10735with a leading '+'.
10736For example:
10737.(b
10738/C=US/ST=California/O=endmail.org/OU=private/CN=Darth Mail (Cert)/
10739Email=darth+cert@endmail.org
10740.)b
10741is encoded as:
10742.(b
10743/C=US/ST=California/O=endmail.org/OU=private/
10744CN=Darth+20Mail+20+28Cert+29/Email=darth+2Bcert@endmail.org
10745.)b
10746(line breaks have been inserted for readability).
10747The macros which are subject to this encoding are
10748{cert_subject}, {cert_issuer}, {cn_subject}, {cn_issuer},
10749as well as
10750{auth_authen} and {auth_author}.
10751.sh 1 "ACKNOWLEDGEMENTS"
10752.pp
10753I've worked on
10754.i sendmail
10755for many years,
10756and many employers have been remarkably patient
10757about letting me work on a large project
10758that was not part of my official job.
10759This includes time on the INGRES Project at
10760the University of California at Berkeley,
10761at Britton Lee,
10762and again on the Mammoth and Titan Projects at Berkeley.
10763.pp
10764Much of the second wave of improvements
10765resulting in version 8.1
10766should be credited to Bryan Costales of the
10767International Computer Science Institute.
10768As he passed me drafts of his book on
10769.i sendmail
10770I was inspired to start working on things again.
10771Bryan was also available to bounce ideas off of.
10772.pp
10773Gregory Neil Shapiro
10774of Worcester Polytechnic Institute
10775has become instrumental in all phases of
10776.i sendmail
10777support and development,
10778and was largely responsible for getting versions 8.8 and 8.9
10779out the door.
10780.pp
10781Many, many people contributed chunks of code and ideas to
10782.i sendmail .
10783It has proven to be a group network effort.
10784Version 8 in particular was a group project.
10785The following people and organizations made notable contributions:
10786.(l
10787Claus Assmann
10788John Beck, Hewlett-Packard & Sun Microsystems
10789Keith Bostic, CSRG, University of California, Berkeley
10790Andrew Cheng, Sun Microsystems
10791Michael J. Corrigan, University of California, San Diego
10792Bryan Costales, International Computer Science Institute & InfoBeat
10793Pa\*:r (Pell) Emanuelsson
10794Craig Everhart, Transarc Corporation
10795Per Hedeland, Ericsson
10796Tom Ivar Helbekkmo, Norwegian School of Economics
10797Kari Hurtta, Finnish Meteorological Institute
10798Allan E. Johannesen, WPI
10799Jonathan Kamens, OpenVision Technologies, Inc.
10800Takahiro Kanbe, Fuji Xerox Information Systems Co., Ltd.
10801Brian Kantor, University of California, San Diego
10802John Kennedy, Cal State University, Chico
10803Murray S. Kucherawy, HookUp Communication Corp.
10804Bruce Lilly, Sony U.S.
10805Karl London
10806Motonori Nakamura, Ritsumeikan University & Kyoto University
10807John Gardiner Myers, Carnegie Mellon University
10808Neil Rickert, Northern Illinois University
10809Gregory Neil Shapiro, WPI
10810Eric Schnoebelen, Convex Computer Corp.
10811Eric Wassenaar, National Institute for Nuclear and High Energy Physics, Amsterdam
10812Randall Winchester, University of Maryland
10813Christophe Wolfhugel, Pasteur Institute & Herve Schauer Consultants (Paris)
10814Exactis.com, Inc.
10815.)l
10816I apologize for anyone I have omitted, misspelled, misattributed, or
10817otherwise missed.
10818At this point, I suspect that at least a hundred people
10819have contributed code,
10820and many more have contributed ideas, comments, and encouragement.
10821I've tried to list them in the RELEASE_NOTES in the distribution directory.
10822I appreciate their contribution as well.
10823.pp
10824Special thanks are reserved for Michael Corrigan and Christophe Wolfhugel,
10825who besides being wonderful guinea pigs and contributors
10826have also consented to be added to the ``sendmail@Sendmail.ORG'' list
10827and, by answering the bulk of the questions sent to that list,
10828have freed me up to do other work.
10829.++ A
10830.+c "COMMAND LINE FLAGS"
10831.ba 0
10832.nr ii 1i
10833.pp
10834Arguments must be presented with flags before addresses.
10835The flags are:
10836.ip \-A\fIx\fP
10837Select an alternative .cf file which is either
10838.i sendmail.cf
10839for
10840.b \-Am
10841or
10842.i submit.cf
10843for
10844.b \-Ac .
10845By default the .cf file is chosen based on the operation mode.
10846For
10847.b -bm
10848(default),
10849.b -bs ,
10850and
10851.b -t
10852it is
10853.i submit.cf
10854if it exists, for all others it is
10855.i sendmail.cf .
10856.ip \-b\fIx\fP
10857Set operation mode to
10858.i x .
10859Operation modes are:
10860.(b
10861.ta 4n
10862m Deliver mail (default)
10863s Speak SMTP on input side
10864a\(dg ``Arpanet'' mode (get envelope sender information from header)
10865d Run as a daemon in background
10866D Run as a daemon in foreground
10867t Run in test mode
10868v Just verify addresses, don't collect or deliver
10869i Initialize the alias database
10870p Print the mail queue
10871P Print overview over the mail queue (requires shared memory)
10872h Print the persistent host status database
10873H Purge expired entries from the persistent host status database
10874.)b
10875.(f
10876\(dgDeprecated.
10877.)f
10878.ip \-B\fItype\fP
10879Indicate body type.
10880.ip \-C\fIfile\fP
10881Use a different configuration file.
10882.i Sendmail
10883runs as the invoking user (rather than root)
10884when this flag is specified.
10885.ip "\-D \fIlogfile\fP"
10886Send debugging output to the indicated
10887.i logfile
10888instead of stdout.
10889.ip \-d\fIlevel\fP
10890Set debugging level.
10891.ip "\-f\ \fIaddr\fP"
10892The envelope sender address is set to
10893.i addr .
10894This address may also be used in the From: header
10895if that header is missing during initial submission.
10896The envelope sender address is used as the recipient
10897for delivery status notifications
10898and may also appear in a Return-Path: header.
10899.ip \-F\ \fIname\fP
10900Sets the full name of this user to
10901.i name .
10902.ip \-G
10903When accepting messages via the command line,
10904indicate that they are for relay (gateway) submission.
10905sendmail may complain about syntactically invalid messages,
10906e.g., unqualified host names,
10907rather than fixing them when this flag is set.
10908sendmail will not do any canonicalization in this mode.
10909.ip "\-h\ \fIcnt\fP"
10910Sets the
10911.q "hop count"
10912to
10913.i cnt .
10914This represents the number of times this message has been processed
10915by
10916.i sendmail
10917(to the extent that it is supported by the underlying networks).
10918.i Cnt
10919is incremented during processing,
10920and if it reaches
10921MAXHOP
10922(currently 25)
10923.i sendmail
10924throws away the message with an error.
10925.ip "\-L \fItag\fP"
10926Sets the identifier used for syslog.
10927Note that this identifier is set
10928as early as possible.
10929However,
10930.i sendmail
10931may be used
10932if problems arise
10933before the command line arguments
10934are processed.
10935.ip \-n
10936Don't do aliasing or forwarding.
10937.ip "\-N \fInotifications\fP"
10938Tag all addresses being sent as wanting the indicated
10939.i notifications ,
10940which consists of the word
10941.q NEVER
10942or a comma-separated list of
10943.q SUCCESS ,
10944.q FAILURE ,
10945and
10946.q DELAY
10947for successful delivery,
10948failure,
10949and a message that is stuck in a queue somewhere.
10950The default is
10951.q FAILURE,DELAY .
10952.ip "\-r\ \fIaddr\fP"
10953An obsolete form of
10954.b \-f .
10955.ip \-o\fIx\|value\fP
10956Set option
10957.i x
10958to the specified
10959.i value .
10960These options are described in Section 5.6.
10961.ip \-O\fIoption\fP\fB=\fP\fIvalue\fP
10962Set
10963.i option
10964to the specified
10965.i value
10966(for long form option names).
10967These options are described in Section 5.6.
10968.ip \-M\fIx\|value\fP
10969Set macro
10970.i x
10971to the specified
10972.i value .
10973.ip \-p\fIprotocol\fP
10974Set the sending protocol.
10975Programs are encouraged to set this.
10976The protocol field can be in the form
10977.i protocol \c
10978.b : \c
10979.i host
10980to set both the sending protocol and sending host.
10981For example,
10982.q \-pUUCP:uunet
10983sets the sending protocol to UUCP
10984and the sending host to uunet.
10985(Some existing programs use \-oM to set the r and s macros;
10986this is equivalent to using \-p.)
10987.ip \-q\fItime\fP
10988Try to process the queued up mail.
10989If the time is given,
10990a
10991.i sendmail
10992will start one or more processes to run through the queue(s) at the specified
10993time interval to deliver queued mail; otherwise, it only runs once.
10994Each of these processes acts on a workgroup.
10995These processes are also known as workgroup processes or WGP's for short.
10996Each workgroup is responsible for controlling the processing of one or
10997more queues; workgroups help manage the use of system resources by sendmail.
10998Each workgroup may have one or more children concurrently processing
10999queues depending on the setting of \fIMaxQueueChildren\fP.
11000.ip \-qp\fItime\fP
11001Similar to \-q with a time argument,
11002except that instead of periodically starting WGP's
11003sendmail starts persistent WGP's
11004that alternate between processing queues and sleeping.
11005The sleep time is specified by the time argument; it defaults to 1 second,
11006except that a WGP always sleeps at least 5 seconds if their queues were
11007empty in the previous run.
11008Persistent processes are managed by a queue control process (QCP).
11009The QCP is the parent process of the WGP's.
11010Typically the QCP will be the sendmail daemon (when started with \-bd or \-bD)
11011or a special process (named Queue control) (when started without \-bd or \-bD).
11012If a persistent WGP ceases to be active for some reason
11013another WGP will be started by the QCP for the same workgroup
11014in most cases. When a persistent WGP has core dumped, the debug flag
11015\fIno_persistent_restart\fP is set or the specific persistent WGP has been
11016restarted too many times already then the WGP will not be started again
11017and a message will be logged to this effect.
11018To stop (SIGTERM) or restart (SIGHUP) persistent WGP's the appropriate
11019signal should be sent to the QCP. The QCP will propagate the signal to all of
11020the WGP's and if appropriate restart the persistent WGP's.
11021.ip \-q\fIGname\fP
11022Run the jobs in the queue group
11023.i name
11024once.
11025.ip \-q[!]\fIXstring\fP
11026Run the queue once,
11027limiting the jobs to those matching
11028.i Xstring .
11029The key letter
11030.i X
11031can be
11032.b I
11033to limit based on queue identifier,
11034.b R
11035to limit based on recipient,
11036.b S
11037to limit based on sender,
11038or
11039.b Q
11040to limit based on quarantine reason for quarantined jobs.
11041A particular queued job is accepted if one of the corresponding attributes
11042contains the indicated
11043.i string .
11044The optional ! character negates the condition tested.
11045Multiple
11046.i \-q\fIX\fP
11047flags are permitted,
11048with items with the same key letter
11049.q or'ed
11050together, and items with different key letters
11051.q and'ed
11052together.
11053.ip "\-Q[reason]"
11054Quarantine a normal queue items with the given reason or
11055unquarantine quarantined queue items if no reason is given.
11056This should only be used with some sort of item matching using
11057.b \-q[!]\fIXstring\fP
11058as described above.
11059.ip "\-R ret"
11060What information you want returned if the message bounces;
11061.i ret
11062can be
11063.q HDRS
11064for headers only or
11065.q FULL
11066for headers plus body.
11067This is a request only;
11068the other end is not required to honor the parameter.
11069If
11070.q HDRS
11071is specified local bounces also return only the headers.
11072.ip \-t
11073Read the header for
11074.q To: ,
11075.q Cc: ,
11076and
11077.q Bcc:
11078lines, and send to everyone listed in those lists.
11079The
11080.q Bcc:
11081line will be deleted before sending.
11082Any addresses in the argument vector will be deleted
11083from the send list.
11084.ip "\-V envid"
11085The indicated
11086.i envid
11087is passed with the envelope of the message
11088and returned if the message bounces.
11089.ip "\-X \fIlogfile\fP"
11090Log all traffic in and out of
11091.i sendmail
11092in the indicated
11093.i logfile
11094for debugging mailer problems.
11095This produces a lot of data very quickly and should be used sparingly.
11096.pp
11097There are a number of options that may be specified as
11098primitive flags.
11099These are the e, i, m, and v options.
11100Also,
11101the f option
11102may be specified as the
11103.b \-s
11104flag.
11105The DSN related options
11106.q "\-N" ,
11107.q "\-R" ,
11108and
11109.q "\-V"
11110have no effects on
11111.i sendmail
11112running as daemon.
11113.+c "QUEUE FILE FORMATS"
11114.pp
11115This appendix describes the format of the queue files.
11116These files live in a queue directory.
11117The individual qf, hf, Qf, df, and xf files
11118may be stored in separate
11119.i qf/ ,
11120.i df/ ,
11121and
11122.i xf/
11123subdirectories
11124if they are present in the queue directory.
11125.pp
11126All queue files have the name
11127.i ttYMDhmsNNppppp
11128where
11129.i YMDhmsNNppppp
11130is the
11131.i id
11132for this message
11133and the
11134.i tt
11135is a type.
11136The individual letters in the
11137.i id
11138are:
11139.nr ii 0.5i
11140.ip Y
11141Encoded year
11142.ip M
11143Encoded month
11144.ip D
11145Encoded day
11146.ip h
11147Encoded hour
11148.ip m
11149Encoded minute
11150.ip s
11151Encoded second
11152.ip NN
11153Encoded envelope number
11154.ip ppppp
11155At least five decimal digits of the process ID
11156.pp
11157All files with the same id collectively define one message.
11158Due to the use of memory-buffered files,
11159some of these files may never appear on disk.
11160.pp
11161The types are:
11162.nr ii 0.5i
11163.ip qf
11164The queue control file.
11165This file contains the information necessary to process the job.
11166.ip hf
11167The same as a queue control file, but for a quarantined queue job.
11168.ip df
11169The data file.
11170The message body (excluding the header) is kept in this file.
11171Sometimes the df file is not stored in the same directory as the qf file;
11172in this case,
11173the qf file contains a `d' record which names the queue directory
11174that contains the df file.
11175.ip tf
11176A temporary file.
11177This is an image of the
11178.b qf
11179file when it is being rebuilt.
11180It should be renamed to a
11181.b qf
11182file very quickly.
11183.ip xf
11184A transcript file,
11185existing during the life of a session
11186showing everything that happens
11187during that session.
11188Sometimes the xf file must be generated before a queue group has been selected;
11189in this case,
11190the xf file will be stored in a directory of the default queue group.
11191.ip Qf
11192A ``lost'' queue control file.
11193.i sendmail
11194renames a
11195.b qf
11196file to
11197.b Qf
11198if there is a severe (configuration) problem that cannot be solved without
11199human intervention.
11200Search the logfile for the queue file id to figure out what happened.
11201After you resolved the problem, you can rename the
11202.b Qf
11203file to
11204.b qf
11205and send it again.
11206.pp
11207The queue control file is structured as a series of lines
11208each beginning with a code letter.
11209The lines are as follows:
11210.ip V
11211The version number of the queue file format,
11212used to allow new
11213.i sendmail
11214binaries to read queue files created by older versions.
11215Defaults to version zero.
11216Must be the first line of the file if present.
11217For 8.12 the version number is 6.
11218.ip A
11219The information given by the AUTH= parameter of the
11220.q "MAIL FROM:"
11221command or $f@$j
11222if sendmail has been called directly.
11223.ip H
11224A header definition.
11225There may be any number of these lines.
11226The order is important:
11227they represent the order in the final message.
11228These use the same syntax
11229as header definitions in the configuration file.
11230.ip C
11231The controlling address.
11232The syntax is
11233.q localuser:aliasname .
11234Recipient addresses following this line
11235will be flagged so that deliveries will be run as the
11236.i localuser
11237(a user name from the /etc/passwd file);
11238.i aliasname
11239is the name of the alias that expanded to this address
11240(used for printing messages).
11241.ip q
11242The quarantine reason for quarantined queue items.
11243.ip Q
11244The ``original recipient'',
11245specified by the ORCPT= field in an ESMTP transaction.
11246Used exclusively for Delivery Status Notifications.
11247It applies only to the following `R' line.
11248.ip r
11249The ``final recipient''
11250used for Delivery Status Notifications.
11251It applies only to the following `R' line.
11252.ip R
11253A recipient address.
11254This will normally be completely aliased,
11255but is actually realiased when the job is processed.
11256There will be one line for each recipient.
11257Version 1 qf files
11258also include a leading colon-terminated list of flags,
11259which can be
11260`S' to return a message on successful final delivery,
11261`F' to return a message on failure,
11262`D' to return a message if the message is delayed,
11263`B' to indicate that the body should be returned,
11264`N' to suppress returning the body,
11265and
11266`P' to declare this as a ``primary'' (command line or SMTP-session) address.
11267.ip S
11268The sender address.
11269There may only be one of these lines.
11270.ip T
11271The job creation time.
11272This is used to compute when to time out the job.
11273.ip P
11274The current message priority.
11275This is used to order the queue.
11276Higher numbers mean lower priorities.
11277The priority changes
11278as the message sits in the queue.
11279The initial priority depends on the message class
11280and the size of the message.
11281.ip M
11282A message.
11283This line is printed by the
11284.i mailq
11285command,
11286and is generally used to store status information.
11287It can contain any text.
11288.ip F
11289Flag bits, represented as one letter per flag.
11290Defined flag bits are
11291.b r
11292indicating that this is a response message
11293and
11294.b w
11295indicating that a warning message has been sent
11296announcing that the mail has been delayed.
11297Other flag bits are:
11298.b 8 :
11299the body contains 8bit data,
11300.b b :
11301a Bcc: header should be removed,
11302.b d :
11303the mail has RET parameters (see RFC 1894),
11304.b n :
11305the body of the message should not be returned
11306in case of an error,
11307.b s :
11308the envelope has been split.
11309.ip N
11310The total number of delivery attempts.
11311.ip K
11312The time (as seconds since January 1, 1970)
11313of the last delivery attempt.
11314.ip d
11315If the df file is in a different directory than the qf file,
11316then a `d' record is present,
11317specifying the directory in which the df file resides.
11318.ip I
11319The i-number of the data file;
11320this can be used to recover your mail queue
11321after a disastrous disk crash.
11322.ip $
11323A macro definition.
11324The values of certain macros
11325are passed through to the queue run phase.
11326.ip B
11327The body type.
11328The remainder of the line is a text string defining the body type.
11329If this field is missing,
11330the body type is assumed to be
11331.q "undefined"
11332and no special processing is attempted.
11333Legal values are
11334.q 7BIT
11335and
11336.q 8BITMIME .
11337.ip Z
11338The original envelope id (from the ESMTP transaction).
11339For Deliver Status Notifications only.
11340.pp
11341As an example,
11342the following is a queue file sent to
11343.q eric@mammoth.Berkeley.EDU
11344and
11345.q bostic@okeeffe.CS.Berkeley.EDU \**:
11346.(f
11347\**This example is contrived and probably inaccurate for your environment.
11348Glance over it to get an idea;
11349nothing can replace looking at what your own system generates.
11350.)f
11351.(b
11352V4
11353T711358135
11354K904446490
11355N0
11356P2100941
11357$_eric@localhost
11358${daemon_flags}
11359Seric
11360Ceric:100:1000:sendmail@vangogh.CS.Berkeley.EDU
11361RPFD:eric@mammoth.Berkeley.EDU
11362RPFD:bostic@okeeffe.CS.Berkeley.EDU
11363H?P?Return-path: <^g>
11364H??Received: by vangogh.CS.Berkeley.EDU (5.108/2.7) id AAA06703;
11365 Fri, 17 Jul 1992 00:28:55 -0700
11366H??Received: from mail.CS.Berkeley.EDU by vangogh.CS.Berkeley.EDU (5.108/2.7)
11367 id AAA06698; Fri, 17 Jul 1992 00:28:54 -0700
11368H??Received: from [128.32.31.21] by mail.CS.Berkeley.EDU (5.96/2.5)
11369 id AA22777; Fri, 17 Jul 1992 03:29:14 -0400
11370H??Received: by foo.bar.baz.de (5.57/Ultrix3.0-C)
11371 id AA22757; Fri, 17 Jul 1992 09:31:25 GMT
11372H?F?From: eric@foo.bar.baz.de (Eric Allman)
11373H?x?Full-name: Eric Allman
11374H??Message-id: <9207170931.AA22757@foo.bar.baz.de>
11375H??To: sendmail@vangogh.CS.Berkeley.EDU
11376H??Subject: this is an example message
11377.)b
11378This shows
11379the person who sent the message,
11380the submission time
11381(in seconds since January 1, 1970),
11382the message priority,
11383the message class,
11384the recipients,
11385and the headers for the message.
11386.+c "SUMMARY OF SUPPORT FILES"
11387.pp
11388This is a summary of the support files
11389that
11390.i sendmail
11391creates or generates.
11392Many of these can be changed by editing the sendmail.cf file;
11393check there to find the actual pathnames.
11394.nr ii 1i
11395.ip "/usr/\*(SD/sendmail"
11396The binary of
11397.i sendmail .
11398.ip /usr/\*(SB/newaliases
11399A link to /usr/\*(SD/sendmail;
11400causes the alias database to be rebuilt.
11401Running this program is completely equivalent to giving
11402.i sendmail
11403the
11404.b \-bi
11405flag.
11406.ip /usr/\*(SB/mailq
11407Prints a listing of the mail queue.
11408This program is equivalent to using the
11409.b \-bp
11410flag to
11411.i sendmail .
11412.ip /etc/mail/sendmail.cf
11413The configuration file,
11414in textual form.
11415.ip /etc/mail/helpfile
11416The SMTP help file.
11417.ip /etc/mail/statistics
11418A statistics file; need not be present.
11419.ip /etc/mail/sendmail.pid
11420Created in daemon mode;
11421it contains the process id of the current SMTP daemon.
11422If you use this in scripts;
11423use ``head \-1'' to get just the first line;
11424the second line contains the command line used to invoke the daemon,
11425and later versions of
11426.i sendmail
11427may add more information to subsequent lines.
11428.ip /etc/mail/aliases
11429The textual version of the alias file.
11430.ip /etc/mail/aliases.db
11431The alias file in
11432.i hash \|(3)
11433format.
11434.ip /etc/mail/aliases.{pag,dir}
11435The alias file in
11436.i ndbm \|(3)
11437format.
11438.ip /var/spool/mqueue
11439The directory in which the mail queue(s)
11440and temporary files reside.
11441.ip /var/spool/mqueue/qf*
11442Control (queue) files for messages.
11443.ip /var/spool/mqueue/df*
11444Data files.
11445.ip /var/spool/mqueue/tf*
11446Temporary versions of the qf files,
11447used during queue file rebuild.
11448.ip /var/spool/mqueue/xf*
11449A transcript of the current session.
11450.if o \
11451\{\
11452. bp
11453. rs
11454. sp |4i
11455. ce 2
11456This page intentionally left blank;
11457replace it with a blank sheet for double-sided output.
11458.\}
11459.\".ro
11460.\".ls 1
11461.\".tp
11462.\".sp 2i
11463.\".in 0
11464.\".ce 100
11465.\".sz 24
11466.\".b SENDMAIL
11467.\".sz 14
11468.\".sp
11469.\"INSTALLATION AND OPERATION GUIDE
11470.\".sp
11471.\".sz 10
11472.\"Eric Allman
11473.\".sp
| 6790The
6791.i Family
6792key defaults to INET (IPv4).
6793IPv6 users who wish to also accept IPv6 connections
6794should add additional Family=inet6
6795.b DaemonPortOptions
6796lines.
6797The
6798.i InputMailFilters
6799key overrides the default list of input mail filters listed in the
6800.b InputMailFilters
6801option.
6802If multiple input mail filters are required, they must be separated
6803by semicolons (not commas).
6804.i Modifier
6805can be a sequence (without any delimiters)
6806of the following characters:
6807.(b
6808.ta 1i
6809a always require authentication
6810b bind to interface through which mail has been received
6811c perform hostname canonification (.cf)
6812f require fully qualified hostname (.cf)
6813s Run smtps (SMTP over SSL) instead of smtp
6814u allow unqualified addresses (.cf)
6815A disable AUTH (overrides 'a' modifier)
6816C don't perform hostname canonification
6817E disallow ETRN (see RFC 2476)
6818O optional; if opening the socket fails ignore it
6819S don't offer STARTTLS
6820.)b
6821That is, one way to specify a message submission agent (MSA) that
6822always requires authentication is:
6823.(b
6824O DaemonPortOptions=Name=MSA, Port=587, M=Ea
6825.)b
6826The modifiers that are marked with "(.cf)" have only
6827effect in the standard configuration file, in which
6828they are available via
6829.b ${daemon_flags} .
6830Notice: Do
6831.b not
6832use the ``a'' modifier on a public accessible MTA!
6833It should only be used for a MSA that is accessed by authorized
6834users for initial mail submission.
6835Users must authenticate to use a MSA which has this option turned on.
6836The flags ``c'' and ``C'' can change the default for
6837hostname canonification in the
6838.i sendmail.cf
6839file.
6840See the relevant documentation for
6841.sm FEATURE(nocanonify) .
6842The modifier ``f'' disallows addresses of the form
6843.b user@host
6844unless they are submitted directly.
6845The flag ``u'' allows unqualified sender addresses,
6846i.e., those without @host.
6847``b'' forces sendmail to bind to the interface
6848through which the e-mail has been
6849received for the outgoing connection.
6850.b WARNING:
6851Use ``b''
6852only if outgoing mail can be routed through the incoming connection's
6853interface to its destination. No attempt is made to catch problems due to a
6854misconfiguration of this parameter, use it only for virtual hosting
6855where each virtual interface can connect to every possible location.
6856This will also override possible settings via
6857.b ClientPortOptions.
6858Note,
6859.i sendmail
6860will listen on a new socket
6861for each occurence of the
6862.b DaemonPortOptions
6863option in a configuration file.
6864The modifier ``O'' causes sendmail to ignore a socket
6865if it can't be opened.
6866This applies to failures from the socket(2) and bind(2) calls.
6867.ip DefaultAuthInfo
6868[no short name]
6869Filename that contains default authentication information for outgoing
6870connections. This file must contain the user id, the authorization id,
6871the password (plain text), the realm and the list of mechanisms to use
6872on separate lines and must be readable by
6873root (or the trusted user) only.
6874If no realm is specified,
6875.b $j
6876is used.
6877If no mechanisms are specified, the list given by
6878.b AuthMechanisms
6879is used.
6880Notice: this option is deprecated and will be removed in future versions.
6881Moreover, it doesn't work for the MSP since it can't read the file
6882(the file must not be group/world-readable otherwise
6883.i sendmail
6884will complain).
6885Use the authinfo ruleset instead which provides more control over
6886the usage of the data anyway.
6887.ip DefaultCharSet=\fIcharset\fP
6888[no short name]
6889When a message that has 8-bit characters but is not in MIME format
6890is converted to MIME
6891(see the EightBitMode option)
6892a character set must be included in the Content-Type: header.
6893This character set is normally set from the Charset= field
6894of the mailer descriptor.
6895If that is not set, the value of this option is used.
6896If this option is not set, the value
6897.q unknown-8bit
6898is used.
6899.ip DataFileBufferSize=\fIthreshold\fP
6900[no short name]
6901Set the
6902.i threshold ,
6903in bytes,
6904before a memory-based
6905queue data file
6906becomes disk-based.
6907The default is 4096 bytes.
6908.ip DeadLetterDrop=\fIfile\fP
6909[no short name]
6910Defines the location of the system-wide dead.letter file,
6911formerly hardcoded to /usr/tmp/dead.letter.
6912If this option is not set (the default),
6913sendmail will not attempt to save to a system-wide dead.letter file
6914in the event
6915it cannot bounce the mail to the user or postmaster.
6916Instead, it will rename the qf file
6917as it has in the past
6918when the dead.letter file could not be opened.
6919.ip DefaultUser=\fIuser:group\fP
6920[u]
6921Set the default userid for mailers to
6922.i user:group .
6923If
6924.i group
6925is omitted and
6926.i user
6927is a user name
6928(as opposed to a numeric user id)
6929the default group listed in the /etc/passwd file for that user is used
6930as the default group.
6931Both
6932.i user
6933and
6934.i group
6935may be numeric.
6936Mailers without the
6937.i S
6938flag in the mailer definition
6939will run as this user.
6940Defaults to 1:1.
6941The value can also be given as a symbolic user name.\**
6942.(f
6943\**The old
6944.b g
6945option has been combined into the
6946.b DefaultUser
6947option.
6948.)f
6949.ip DelayLA=\fILA\fP
6950[no short name]
6951When the system load average exceeds
6952.i LA ,
6953.i sendmail
6954will sleep for one second on most SMTP commands and
6955before accepting connections.
6956.ip DeliverByMin=\fItime\fP
6957[0]
6958Set minimum time for Deliver By SMTP Service Extension (RFC 2852).
6959If 0, no time is listed, if less than 0, the extension is not offered,
6960if greater than 0, it is listed as minimum time
6961for the EHLO keyword DELIVERBY.
6962.ip DeliveryMode=\fIx\fP
6963[d]
6964Deliver in mode
6965.i x .
6966Legal modes are:
6967.(b
6968.ta 4n
6969i Deliver interactively (synchronously)
6970b Deliver in background (asynchronously)
6971q Just queue the message (deliver during queue run)
6972d Defer delivery and all map lookups (deliver during queue run)
6973.)b
6974Defaults to ``b'' if no option is specified,
6975``i'' if it is specified but given no argument
6976(i.e., ``Od'' is equivalent to ``Odi'').
6977The
6978.b \-v
6979command line flag sets this to
6980.b i .
6981Note: for internal reasons,
6982``i'' does not work
6983if a milter is enabled which can reject or delete recipients.
6984In that case the mode will be changed to ``b''.
6985.ip DialDelay=\fIsleeptime\fP
6986[no short name]
6987Dial-on-demand network connections can see timeouts
6988if a connection is opened before the call is set up.
6989If this is set to an interval and a connection times out
6990on the first connection being attempted
6991.i sendmail
6992will sleep for this amount of time and try again.
6993This should give your system time to establish the connection
6994to your service provider.
6995Units default to seconds, so
6996.q DialDelay=5
6997uses a five second delay.
6998Defaults to zero
6999(no retry).
7000This delay only applies to mailers which have the
7001Z flag set.
7002.ip DirectSubmissionModifiers=\fImodifiers\fP
7003Defines
7004.b ${daemon_flags}
7005for direct (command line) submissions.
7006If not set,
7007.b ${daemon_flags}
7008is either "CC f" if the option
7009.b \-G
7010is used or "c u" otherwise.
7011Note that only the the "CC", "c", "f", and "u" flags are checked.
7012.ip DontBlameSendmail=\fIoption,option,...\fP
7013[no short name]
7014In order to avoid possible cracking attempts
7015caused by world- and group-writable files and directories,
7016.i sendmail
7017does paranoid checking when opening most of its support files.
7018If for some reason you absolutely must run with,
7019for example,
7020a group-writable
7021.i /etc
7022directory,
7023then you will have to turn off this checking
7024(at the cost of making your system more vulnerable to attack).
7025The possible arguments have been described earlier.
7026The details of these flags are described above.
7027.\"XXX should have more here!!! XXX
7028.b "Use of this option is not recommended."
7029.ip DontExpandCnames
7030[no short name]
7031The standards say that all host addresses used in a mail message
7032must be fully canonical.
7033For example, if your host is named
7034.q Cruft.Foo.ORG
7035and also has an alias of
7036.q FTP.Foo.ORG ,
7037the former name must be used at all times.
7038This is enforced during host name canonification
7039($[ ... $] lookups).
7040If this option is set, the protocols are ignored and the
7041.q wrong
7042thing is done.
7043However, the IETF is moving toward changing this standard,
7044so the behavior may become acceptable.
7045Please note that hosts downstream may still rewrite the address
7046to be the true canonical name however.
7047.ip DontInitGroups
7048[no short name]
7049If set,
7050.i sendmail
7051will avoid using the initgroups(3) call.
7052If you are running NIS,
7053this causes a sequential scan of the groups.byname map,
7054which can cause your NIS server to be badly overloaded in a large domain.
7055The cost of this is that the only group found for users
7056will be their primary group (the one in the password file),
7057which will make file access permissions somewhat more restrictive.
7058Has no effect on systems that don't have group lists.
7059.ip DontProbeInterfaces
7060[no short name]
7061.i Sendmail
7062normally finds the names of all interfaces active on your machine
7063when it starts up
7064and adds their name to the
7065.b $=w
7066class of known host aliases.
7067If you have a large number of virtual interfaces
7068or if your DNS inverse lookups are slow
7069this can be time consuming.
7070This option turns off that probing.
7071However, you will need to be certain to include all variant names
7072in the
7073.b $=w
7074class by some other mechanism.
7075If set to
7076.b loopback ,
7077loopback interfaces (e.g., lo0) will not be probed.
7078.ip DontPruneRoutes
7079[R]
7080Normally,
7081.i sendmail
7082tries to eliminate any unnecessary explicit routes
7083when sending an error message
7084(as discussed in RFC 1123 \(sc 5.2.6).
7085For example,
7086when sending an error message to
7087.(b
7088<@known1,@known2,@known3:user@unknown>
7089.)b
7090.i sendmail
7091will strip off the
7092.q @known1,@known2
7093in order to make the route as direct as possible.
7094However, if the
7095.b R
7096option is set, this will be disabled,
7097and the mail will be sent to the first address in the route,
7098even if later addresses are known.
7099This may be useful if you are caught behind a firewall.
7100.ip DoubleBounceAddress=\fIerror-address\fP
7101[no short name]
7102If an error occurs when sending an error message,
7103send the error report
7104(termed a
7105.q "double bounce"
7106because it is an error
7107.q bounce
7108that occurs when trying to send another error
7109.q bounce )
7110to the indicated address.
7111The address is macro expanded
7112at the time of delivery.
7113If not set, defaults to
7114.q postmaster .
7115If set to an empty string, double bounces are dropped.
7116.ip EightBitMode=\fIaction\fP
7117[8]
7118Set handling of eight-bit data.
7119There are two kinds of eight-bit data:
7120that declared as such using the
7121.b BODY=8BITMIME
7122ESMTP declaration or the
7123.b \-B8BITMIME
7124command line flag,
7125and undeclared 8-bit data, that is,
7126input that just happens to be eight bits.
7127There are three basic operations that can happen:
7128undeclared 8-bit data can be automatically converted to 8BITMIME,
7129undeclared 8-bit data can be passed as-is without conversion to MIME
7130(``just send 8''),
7131and declared 8-bit data can be converted to 7-bits
7132for transmission to a non-8BITMIME mailer.
7133The possible
7134.i action s
7135are:
7136.(b
7137.\" r Reject undeclared 8-bit data;
7138.\" don't convert 8BITMIME\(->7BIT (``reject'')
7139 s Reject undeclared 8-bit data (``strict'')
7140.\" do convert 8BITMIME\(->7BIT (``strict'')
7141.\" c Convert undeclared 8-bit data to MIME;
7142.\" don't convert 8BITMIME\(->7BIT (``convert'')
7143 m Convert undeclared 8-bit data to MIME (``mime'')
7144.\" do convert 8BITMIME\(->7BIT (``mime'')
7145.\" j Pass undeclared 8-bit data;
7146.\" don't convert 8BITMIME\(->7BIT (``just send 8'')
7147 p Pass undeclared 8-bit data (``pass'')
7148.\" do convert 8BITMIME\(->7BIT (``pass'')
7149.\" a Adaptive algorithm: see below
7150.)b
7151.\"The adaptive algorithm is to accept 8-bit data,
7152.\"converting it to 8BITMIME only if the receiver understands that,
7153.\"otherwise just passing it as undeclared 8-bit data;
7154.\"8BITMIME\(->7BIT conversions are done.
7155In all cases properly declared 8BITMIME data will be converted to 7BIT
7156as needed.
7157.ip ErrorHeader=\fIfile-or-message\fP
7158[E]
7159Prepend error messages with the indicated message.
7160If it begins with a slash,
7161it is assumed to be the pathname of a file
7162containing a message (this is the recommended setting).
7163Otherwise, it is a literal message.
7164The error file might contain the name, email address, and/or phone number
7165of a local postmaster who could provide assistance
7166to end users.
7167If the option is missing or null,
7168or if it names a file which does not exist or which is not readable,
7169no message is printed.
7170.ip ErrorMode=\fIx\fP
7171[e]
7172Dispose of errors using mode
7173.i x .
7174The values for
7175.i x
7176are:
7177.(b
7178p Print error messages (default)
7179q No messages, just give exit status
7180m Mail back errors
7181w Write back errors (mail if user not logged in)
7182e Mail back errors (when applicable) and give zero exit stat always
7183.)b
7184Note that the last mode,
7185.q e ,
7186is for Berknet error processing and
7187should not be used in normal circumstances.
7188Note, too, that mode
7189.q q ,
7190only applies to errors recognized before sendmail forks for
7191background delivery.
7192.ip FallbackMXhost=\fIfallbackhost\fP
7193[V]
7194If specified, the
7195.i fallbackhost
7196acts like a very low priority MX
7197on every host.
7198MX records will be looked up for this host,
7199unless the name is surrounded by square brackets.
7200This is intended to be used by sites with poor network connectivity.
7201Messages which are undeliverable due to temporary address failures
7202(e.g., DNS failure)
7203also go to the FallbackMXhost.
7204.ip FallBackSmartHost=\fIhostname\fP
7205If specified, the
7206.i FallBackSmartHost
7207will be used in a last-ditch effort for each host.
7208This is intended to be used by sites with "fake internal DNS",
7209e.g., a company whose DNS accurately reflects the world
7210inside that company's domain but not outside.
7211.ip FastSplit
7212[no short name]
7213If set to a value greater than zero (the default is one),
7214it suppresses the MX lookups on addresses
7215when they are initially sorted, i.e., for the first delivery attempt.
7216This usually results in faster envelope splitting unless the MX records
7217are readily available in a local DNS cache.
7218To enforce initial sorting based on MX records set
7219.b FastSplit
7220to zero.
7221If the mail is submitted directly from the command line, then
7222the value also limits the number of processes to deliver the envelopes;
7223if more envelopes are created they are only queued up
7224and must be taken care of by a queue run.
7225Since the default submission method is via SMTP (either from a MUA
7226or via the MSP), the value of
7227.b FastSplit
7228is seldom used to limit the number of processes to deliver the envelopes.
7229.ip ForkEachJob
7230[Y]
7231If set,
7232deliver each job that is run from the queue in a separate process.
7233.ip ForwardPath=\fIpath\fP
7234[J]
7235Set the path for searching for users' .forward files.
7236The default is
7237.q $z/.forward .
7238Some sites that use the automounter may prefer to change this to
7239.q /var/forward/$u
7240to search a file with the same name as the user in a system directory.
7241It can also be set to a sequence of paths separated by colons;
7242.i sendmail
7243stops at the first file it can successfully and safely open.
7244For example,
7245.q /var/forward/$u:$z/.forward
7246will search first in /var/forward/\c
7247.i username
7248and then in
7249.i ~username /.forward
7250(but only if the first file does not exist).
7251.ip HeloName=\fIname\fP
7252[no short name]
7253Set the name to be used for HELO/EHLO (instead of $j).
7254.ip HoldExpensive
7255[c]
7256If an outgoing mailer is marked as being expensive,
7257don't connect immediately.
7258.ip HostsFile=\fIpath\fP
7259[no short name]
7260The path to the hosts database,
7261normally
7262.q /etc/hosts .
7263This option is only consulted when sendmail
7264is canonifying addresses,
7265and then only when
7266.q files
7267is in the
7268.q hosts
7269service switch entry.
7270In particular, this file is
7271.i never
7272used when looking up host addresses;
7273that is under the control of the system
7274.i gethostbyname (3)
7275routine.
7276.ip HostStatusDirectory=\fIpath\fP
7277[no short name]
7278The location of the long term host status information.
7279When set,
7280information about the status of hosts
7281(e.g., host down or not accepting connections)
7282will be shared between all
7283.i sendmail
7284processes;
7285normally, this information is only held within a single queue run.
7286This option requires a connection cache of at least 1 to function.
7287If the option begins with a leading `/',
7288it is an absolute pathname;
7289otherwise,
7290it is relative to the mail queue directory.
7291A suggested value for sites desiring persistent host status is
7292.q \&.hoststat
7293(i.e., a subdirectory of the queue directory).
7294.ip IgnoreDots
7295[i]
7296Ignore dots in incoming messages.
7297This is always disabled (that is, dots are always accepted)
7298when reading SMTP mail.
7299.ip InputMailFilters=\fIname,name,...\fP
7300A comma separated list of filters which determines which filters
7301(see the "X \*- Mail Filter (Milter) Definitions" section)
7302and the invocation sequence are contacted for incoming SMTP messages.
7303If none are set, no filters will be contacted.
7304.ip LDAPDefaultSpec=\fIspec\fP
7305[no short name]
7306Sets a default map specification for LDAP maps.
7307The value should only contain LDAP specific settings
7308such as
7309.q "-h host -p port -d bindDN" .
7310The settings will be used for all LDAP maps
7311unless the individual map specification overrides a setting.
7312This option should be set before any LDAP maps are defined.
7313.ip LogLevel=\fIn\fP
7314[L]
7315Set the log level to
7316.i n .
7317Defaults to 9.
7318.ip M\fIx\|value\fP
7319[no long version]
7320Set the macro
7321.i x
7322to
7323.i value .
7324This is intended only for use from the command line.
7325The
7326.b \-M
7327flag is preferred.
7328.ip MailboxDatabase
7329[no short name]
7330Type of lookup to find information about local mailboxes,
7331defaults to ``pw'' which uses
7332.i getpwnam .
7333Other types can be introduced by adding them to the source code,
7334see libsm/mbdb.c for details.
7335.ip UseMSP
7336[no short name]
7337Use as mail submission program, i.e.,
7338allow group writable queue files
7339if the group is the same as that of a set-group-ID sendmail binary.
7340See the file
7341.b sendmail/SECURITY
7342in the distribution tarball.
7343.ip MatchGECOS
7344[G]
7345Allow fuzzy matching on the GECOS field.
7346If this flag is set,
7347and the usual user name lookups fail
7348(that is, there is no alias with this name and a
7349.i getpwnam
7350fails),
7351sequentially search the password file
7352for a matching entry in the GECOS field.
7353This also requires that MATCHGECOS
7354be turned on during compilation.
7355This option is not recommended.
7356.ip MaxAliasRecursion=\fIN\fP
7357[no short name]
7358The maximum depth of alias recursion (default: 10).
7359.ip MaxDaemonChildren=\fIN\fP
7360[no short name]
7361If set,
7362.i sendmail
7363will refuse connections when it has more than
7364.i N
7365children processing incoming mail or automatic queue runs.
7366This does not limit the number of outgoing connections.
7367If the default
7368.b DeliveryMode
7369(background) is used, then
7370.i sendmail
7371may create an almost unlimited number of children
7372(depending on the number of transactions and the
7373relative execution times of mail receiption and mail delivery).
7374If the limit should be enforced, then a
7375.b DeliveryMode
7376other than background must be used.
7377If not set, there is no limit to the number of children --
7378that is, the system load average controls this.
7379.ip MaxHeadersLength=\fIN\fP
7380[no short name]
7381The maximum length of the sum of all headers.
7382This can be used to prevent a denial of service attack.
7383The default is no limit.
7384.ip MaxHopCount=\fIN\fP
7385[h]
7386The maximum hop count.
7387Messages that have been processed more than
7388.i N
7389times are assumed to be in a loop and are rejected.
7390Defaults to 25.
7391.ip MaxMessageSize=\fIN\fP
7392[no short name]
7393Specify the maximum message size
7394to be advertised in the ESMTP EHLO response.
7395Messages larger than this will be rejected.
7396If set to a value greater than zero,
7397that value will be listed in the SIZE response,
7398otherwise SIZE is advertised in the ESMTP EHLO response
7399without a parameter.
7400.ip MaxMimeHeaderLength=\fIN[/M]\fP
7401[no short name]
7402Sets the maximum length of certain MIME header field values to
7403.i N
7404characters.
7405These MIME header fields are determined by being a member of
7406class {checkMIMETextHeaders}, which currently contains only
7407the header Content-Description.
7408For some of these headers which take parameters,
7409the maximum length of each parameter is set to
7410.i M
7411if specified. If
7412.i /M
7413is not specified, one half of
7414.i N
7415will be used.
7416By default,
7417these values are 2048 and 1024, respectively.
7418To allow any length, a value of 0 can be specified.
7419.ip MaxNOOPCommands=\fIN\fP
7420Override the default of
7421.b MAXNOOPCOMMANDS
7422for the number of
7423.i useless
7424commands, see Section
7425"Measures against Denial of Service Attacks".
7426.ip MaxQueueChildren=\fIN\fP
7427[no short name]
7428When set, this limits the number of concurrent queue runner processes to
7429.i N.
7430This helps to control the amount of system resources used when processing
7431the queue. When there are multiple queue groups defined and the total number
7432of queue runners for these queue groups would exceed
7433.i MaxQueueChildren
7434then the queue groups will not all run concurrently. That is, some portion
7435of the queue groups will run concurrently such that
7436.i MaxQueueChildren
7437will not be exceeded, while the remaining queue groups will be run later (in
7438round robin order). See also
7439.i MaxRunnersPerQueue
7440and the section \fBQueue Group Declaration\fP.
7441Notice:
7442.i sendmail
7443does not count individual queue runners, but only sets of processes
7444that act on a workgroup.
7445Hence the actual number of queue runners may be lower than the limit
7446imposed by
7447.i MaxQueueChildren .
7448This discrepancy can be large if some queue runners have to wait
7449for a slow server and if short intervals are used.
7450.ip MaxQueueRunSize=\fIN\fP
7451[no short name]
7452The maximum number of jobs that will be processed
7453in a single queue run.
7454If not set, there is no limit on the size.
7455If you have very large queues or a very short queue run interval
7456this could be unstable.
7457However, since the first
7458.i N
7459jobs in queue directory order are run (rather than the
7460.i N
7461highest priority jobs)
7462this should be set as high as possible to avoid
7463.q losing
7464jobs that happen to fall late in the queue directory.
7465Note: this option also restricts the number of entries printed by
7466.i mailq .
7467That is, if
7468.i MaxQueueRunSize
7469is set to a value
7470.b N
7471larger than zero,
7472then only
7473.b N
7474entries are printed per queue group.
7475.ip MaxRecipientsPerMessage=\fIN\fP
7476[no short name]
7477The maximum number of recipients that will be accepted per message
7478in an SMTP transaction.
7479Note: setting this too low can interfere with sending mail from
7480MUAs that use SMTP for initial submission.
7481If not set, there is no limit on the number of recipients per envelope.
7482.ip MaxRunnersPerQueue=\fIN\fP
7483[no short name]
7484This sets the default maximum number of queue runners for queue groups.
7485Up to
7486.i N
7487queue runners will work in parallel on a queue group's messages.
7488This is useful where the processing of a message in the queue might
7489delay the processing of subsequent messages. Such a delay may be the result
7490of non-erroneous situations such as a low bandwidth connection.
7491May be overridden on a per queue group basis by setting the
7492.i Runners
7493option; see the section \fBQueue Group Declaration\fP.
7494The default is 1 when not set.
7495.ip MeToo
7496[m]
7497Send to me too,
7498even if I am in an alias expansion.
7499This option is deprecated
7500and will be removed from a future version.
7501.ip Milter
7502[no short name]
7503This option has several sub(sub)options.
7504The names of the suboptions are separated by dots.
7505At the first level the following options are available:
7506.(b
7507.ta \w'LogLevel'u+3n
7508LogLevel Log level for input mail filter actions, defaults to LogLevel.
7509macros Specifies list of macro to transmit to filters.
7510 See list below.
7511.)b
7512The ``macros'' option has the following suboptions
7513which specify the list of macro to transmit to milters
7514after a certain event occurred.
7515.(b
7516.ta \w'envfrom'u+3n
7517connect After session connection start
7518helo After EHLO/HELO command
7519envfrom After MAIL From command
7520envrcpt After RCPT To command
7521data After DATA command.
7522eoh After DATA command and header
7523eom After DATA command and terminating ``.''
7524.)b
7525By default the lists of macros are empty.
7526Example:
7527.(b
7528O Milter.LogLevel=12
7529O Milter.macros.connect=j, _, {daemon_name}
7530.)b
7531.ip MinFreeBlocks=\fIN\fP
7532[b]
7533Insist on at least
7534.i N
7535blocks free on the filesystem that holds the queue files
7536before accepting email via SMTP.
7537If there is insufficient space
7538.i sendmail
7539gives a 452 response
7540to the MAIL command.
7541This invites the sender to try again later.
7542.ip MinQueueAge=\fIage\fP
7543[no short name]
7544Don't process any queued jobs
7545that have been in the queue less than the indicated time interval.
7546This is intended to allow you to get responsiveness
7547by processing the queue fairly frequently
7548without thrashing your system by trying jobs too often.
7549The default units are minutes.
7550Note:
7551This option is ignored for queue runs that select a subset
7552of the queue, i.e.,
7553.q \-q[!][I|R|S|Q][string]
7554.ip MustQuoteChars=\fIs\fP
7555[no short name]
7556Sets the list of characters that must be quoted if used in a full name
7557that is in the phrase part of a ``phrase <address>'' syntax.
7558The default is ``\'.''.
7559The characters ``@,;:\e()[]'' are always added to this list.
7560.ip NiceQueueRun
7561[no short name]
7562The priority of queue runners (nice(3)).
7563This value must be greater or equal zero.
7564.ip NoRecipientAction
7565[no short name]
7566The action to take when you receive a message that has no valid
7567recipient headers (To:, Cc:, Bcc:, or Apparently-To: \(em
7568the last included for back compatibility with old
7569.i sendmail s).
7570It can be
7571.b None
7572to pass the message on unmodified,
7573which violates the protocol,
7574.b Add-To
7575to add a To: header with any recipients it can find in the envelope
7576(which might expose Bcc: recipients),
7577.b Add-Apparently-To
7578to add an Apparently-To: header
7579(this is only for back-compatibility
7580and is officially deprecated),
7581.b Add-To-Undisclosed
7582to add a header
7583.q "To: undisclosed-recipients:;"
7584to make the header legal without disclosing anything,
7585or
7586.b Add-Bcc
7587to add an empty Bcc: header.
7588.ip OldStyleHeaders
7589[o]
7590Assume that the headers may be in old format,
7591i.e.,
7592spaces delimit names.
7593This actually turns on
7594an adaptive algorithm:
7595if any recipient address contains a comma, parenthesis,
7596or angle bracket,
7597it will be assumed that commas already exist.
7598If this flag is not on,
7599only commas delimit names.
7600Headers are always output with commas between the names.
7601Defaults to off.
7602.ip OperatorChars=\fIcharlist\fP
7603[$o macro]
7604The list of characters that are considered to be
7605.q operators ,
7606that is, characters that delimit tokens.
7607All operator characters are tokens by themselves;
7608sequences of non-operator characters are also tokens.
7609White space characters separate tokens
7610but are not tokens themselves \(em for example,
7611.q AAA.BBB
7612has three tokens, but
7613.q "AAA BBB"
7614has two.
7615If not set, OperatorChars defaults to
7616.q \&.\|:\|@\|[\|] ;
7617additionally, the characters
7618.q (\|)\|<\|>\|,\|;
7619are always operators.
7620Note that OperatorChars must be set in the
7621configuration file before any rulesets.
7622.ip PidFile=\fIfilename\fP
7623[no short name]
7624Filename of the pid file.
7625(default is _PATH_SENDMAILPID).
7626The
7627.i filename
7628is macro-expanded before it is opened, and unlinked when
7629.i sendmail
7630exits.
7631.ip PostmasterCopy=\fIpostmaster\fP
7632[P]
7633If set,
7634copies of error messages will be sent to the named
7635.i postmaster .
7636Only the header of the failed message is sent.
7637Errors resulting from messages with a negative precedence will not be sent.
7638Since most errors are user problems,
7639this is probably not a good idea on large sites,
7640and arguably contains all sorts of privacy violations,
7641but it seems to be popular with certain operating systems vendors.
7642The address is macro expanded
7643at the time of delivery.
7644Defaults to no postmaster copies.
7645.ip PrivacyOptions=\fI\|opt,opt,...\fP
7646[p]
7647Set the privacy
7648.i opt ions.
7649``Privacy'' is really a misnomer;
7650many of these are just a way of insisting on stricter adherence
7651to the SMTP protocol.
7652The
7653.i opt ions
7654can be selected from:
7655.(b
7656.ta \w'noactualrecipient'u+3n
7657public Allow open access
7658needmailhelo Insist on HELO or EHLO command before MAIL
7659needexpnhelo Insist on HELO or EHLO command before EXPN
7660noexpn Disallow EXPN entirely, implies noverb.
7661needvrfyhelo Insist on HELO or EHLO command before VRFY
7662novrfy Disallow VRFY entirely
7663noetrn Disallow ETRN entirely
7664noverb Disallow VERB entirely
7665restrictmailq Restrict mailq command
7666restrictqrun Restrict \-q command line flag
7667restrictexpand Restrict \-bv and \-v command line flags
7668noreceipts Don't return success DSNs\**
7669nobodyreturn Don't return the body of a message with DSNs
7670goaway Disallow essentially all SMTP status queries
7671authwarnings Put X-Authentication-Warning: headers in messages
7672 and log warnings
7673noactualrecipient Don't put X-Actual-Recipient lines in DSNs
7674 which reveal the actual account that addresses map to.
7675.)b
7676.(f
7677\**N.B.:
7678the
7679.b noreceipts
7680flag turns off support for RFC 1891
7681(Delivery Status Notification).
7682.)f
7683The
7684.q goaway
7685pseudo-flag sets all flags except
7686.q noreceipts ,
7687.q restrictmailq ,
7688.q restrictqrun ,
7689.q restrictexpand ,
7690.q noetrn ,
7691and
7692.q nobodyreturn .
7693If mailq is restricted,
7694only people in the same group as the queue directory
7695can print the queue.
7696If queue runs are restricted,
7697only root and the owner of the queue directory
7698can run the queue.
7699The
7700.q restrictexpand
7701pseudo-flag instructs
7702.i sendmail
7703to drop privileges when the
7704.b \-bv
7705option is given by users who are neither root nor the TrustedUser
7706so users cannot read private aliases, forwards, or :include: files.
7707It will add the
7708.q NonRootSafeAddr
7709to the
7710.q DontBlameSendmail
7711option to prevent misleading unsafe address warnings.
7712It also overrides the
7713.b \-v
7714(verbose) command line option to prevent information leakage.
7715Authentication Warnings add warnings about various conditions
7716that may indicate attempts to spoof the mail system,
7717such as using a non-standard queue directory.
7718.ip ProcessTitlePrefix=\fIstring\fP
7719[no short name]
7720Prefix the process title shown on 'ps' listings with
7721.i string .
7722The
7723.i string
7724will be macro processed.
7725.ip QueueDirectory=\fIdir\fP
7726[Q]
7727The QueueDirectory option serves two purposes.
7728First, it specifies the directory or set of directories that comprise
7729the default queue group.
7730Second, it specifies the directory D which is the ancestor of all queue
7731directories, and which sendmail uses as its current working directory.
7732When sendmail dumps core, it leaves its core files in D.
7733There are two cases.
7734If \fIdir\fR ends with an asterisk (eg, \fI/var/spool/mqueue/qd*\fR),
7735then all of the directories or symbolic links to directories
7736beginning with `qd' in
7737.i /var/spool/mqueue
7738will be used as queue directories of the default queue group,
7739and
7740.i /var/spool/mqueue
7741will be used as the working directory D.
7742Otherwise,
7743\fIdir\fR must name a directory (usually \fI/var/spool/mqueue\fR):
7744the default queue group consists of the single queue directory \fIdir\fR,
7745and the working directory D is set to \fIdir\fR.
7746To define additional groups of queue directories,
7747use the configuration file `Q' command.
7748Do not change the queue directory structure
7749while sendmail is running.
7750.ip QueueFactor=\fIfactor\fP
7751[q]
7752Use
7753.i factor
7754as the multiplier in the map function
7755to decide when to just queue up jobs rather than run them.
7756This value is divided by the difference between the current load average
7757and the load average limit
7758(\c
7759.b QueueLA
7760option)
7761to determine the maximum message priority
7762that will be sent.
7763Defaults to 600000.
7764.ip QueueLA=\fILA\fP
7765[x]
7766When the system load average exceeds
7767.i LA
7768and the
7769.b QueueFactor
7770(\c
7771.b q )
7772option divided by the difference in the current load average and the
7773.b QueueLA
7774option plus one
7775is less than the priority of the message,
7776just queue messages
7777(i.e., don't try to send them).
7778Defaults to 8 multiplied by
7779the number of processors online on the system
7780(if that can be determined).
7781.ip QueueFileMode=\fImode\fP
7782[no short name]
7783Default permissions for queue files (octal).
7784If not set, sendmail uses 0600 unless its real
7785and effective uid are different in which case it uses 0644.
7786.ip QueueSortOrder=\fIalgorithm\fP
7787[no short name]
7788Sets the
7789.i algorithm
7790used for sorting the queue.
7791Only the first character of the value is used.
7792Legal values are
7793.q host
7794(to order by the name of the first host name of the first recipient),
7795.q filename
7796(to order by the name of the queue file name),
7797.q time
7798(to order by the submission/creation time),
7799.q random
7800(to order randomly),
7801.q modification
7802(to order by the modification time of the qf file (older entries first)),
7803.q none
7804(to not order),
7805and
7806.q priority
7807(to order by message priority).
7808Host ordering makes better use of the connection cache,
7809but may tend to process low priority messages
7810that go to a single host
7811over high priority messages that go to several hosts;
7812it probably shouldn't be used on slow network links.
7813Filename and modification time ordering saves the overhead of
7814reading all of the queued items
7815before starting the queue run.
7816Creation (submission) time ordering is almost always a bad idea,
7817since it allows large, bulk mail to go out
7818before smaller, personal mail,
7819but may have applicability on some hosts with very fast connections.
7820Random is useful if several queue runners are started by hand
7821which try to drain the same queue since odds are they will be working
7822on different parts of the queue at the same time.
7823Priority ordering is the default.
7824.ip QueueTimeout=\fItimeout\fP
7825[T]
7826A synonym for
7827.q Timeout.queuereturn .
7828Use that form instead of the
7829.q QueueTimeout
7830form.
7831.ip RandFile
7832[no short name]
7833Name of file containing random data or the name of the UNIX socket
7834if EGD is used.
7835A (required) prefix "egd:" or "file:" specifies the type.
7836STARTTLS requires this filename if the compile flag HASURANDOMDEV is not set
7837(see sendmail/README).
7838.ip ResolverOptions=\fIoptions\fP
7839[I]
7840Set resolver options.
7841Values can be set using
7842.b + \c
7843.i flag
7844and cleared using
7845.b \- \c
7846.i flag ;
7847the
7848.i flag s
7849can be
7850.q debug ,
7851.q aaonly ,
7852.q usevc ,
7853.q primary ,
7854.q igntc ,
7855.q recurse ,
7856.q defnames ,
7857.q stayopen ,
7858.q use_inet6 ,
7859or
7860.q dnsrch .
7861The string
7862.q HasWildcardMX
7863(without a
7864.b +
7865or
7866.b \- )
7867can be specified to turn off matching against MX records
7868when doing name canonifications.
7869The string
7870.q WorkAroundBrokenAAAA
7871(without a
7872.b +
7873or
7874.b \- )
7875can be specified to work around some broken nameservers
7876which return SERVFAIL (a temporary failure) on T_AAAA (IPv6) lookups.
7877Notice: it might be necessary to apply the same (or similar) options to
7878.i submit.cf
7879too.
7880.ip RequiresDirfsync
7881[no short name]
7882This option can be used to override the compile time flag
7883.b REQUIRES_DIR_FSYNC
7884at runtime by setting it to
7885.sm false .
7886If the compile time flag is not set, the option is ignored.
7887The flag turns on support for file systems that require to call
7888.i fsync()
7889for a directory if the meta-data in it has been changed.
7890This should be turned on at least for older versions of ReiserFS;
7891it is enabled by default for Linux.
7892According to some information this flag is not needed
7893anymore for kernel 2.4.16 and newer.
7894.ip RrtImpliesDsn
7895[R]
7896If this option is set, a
7897.q Return-Receipt-To:
7898header causes the request of a DSN, which is sent to
7899the envelope sender as required by RFC 1891,
7900not to the address given in the header.
7901.ip RunAsUser=\fIuser\fP
7902[no short name]
7903The
7904.i user
7905parameter may be a user name
7906(looked up in
7907.i /etc/passwd )
7908or a numeric user id;
7909either form can have
7910.q ":group"
7911attached
7912(where group can be numeric or symbolic).
7913If set to a non-zero (non-root) value,
7914.i sendmail
7915will change to this user id shortly after startup\**.
7916.(f
7917\**When running as a daemon,
7918it changes to this user after accepting a connection
7919but before reading any
7920.sm SMTP
7921commands.
7922.)f
7923This avoids a certain class of security problems.
7924However, this means that all
7925.q \&.forward
7926and
7927.q :include:
7928files must be readable by the indicated
7929.i user
7930and all files to be written must be writable by
7931.i user
7932Also, all file and program deliveries will be marked unsafe
7933unless the option
7934.b DontBlameSendmail=NonRootSafeAddr
7935is set,
7936in which case the delivery will be done as
7937.i user .
7938It is also incompatible with the
7939.b SafeFileEnvironment
7940option.
7941In other words, it may not actually add much to security on an average system,
7942and may in fact detract from security
7943(because other file permissions must be loosened).
7944However, it should be useful on firewalls and other
7945places where users don't have accounts and the aliases file is
7946well constrained.
7947.ip RecipientFactor=\fIfact\fP
7948[y]
7949The indicated
7950.i fact or
7951is added to the priority (thus
7952.i lowering
7953the priority of the job)
7954for each recipient,
7955i.e., this value penalizes jobs with large numbers of recipients.
7956Defaults to 30000.
7957.ip RefuseLA=\fILA\fP
7958[X]
7959When the system load average exceeds
7960.i LA ,
7961refuse incoming SMTP connections.
7962Defaults to 12 multiplied by
7963the number of processors online on the system
7964(if that can be determined).
7965.ip RejectLogInterval=\fItimeout\fP
7966[no short name]
7967Log interval when refusing connections for this long
7968(default: 3h).
7969.ip RetryFactor=\fIfact\fP
7970[Z]
7971The
7972.i fact or
7973is added to the priority
7974every time a job is processed.
7975Thus,
7976each time a job is processed,
7977its priority will be decreased by the indicated value.
7978In most environments this should be positive,
7979since hosts that are down are all too often down for a long time.
7980Defaults to 90000.
7981.ip SafeFileEnvironment=\fIdir\fP
7982[no short name]
7983If this option is set,
7984.i sendmail
7985will do a
7986.i chroot (2)
7987call into the indicated
7988.i dir ectory
7989before doing any file writes.
7990If the file name specified by the user begins with
7991.i dir ,
7992that partial path name will be stripped off before writing,
7993so (for example)
7994if the SafeFileEnvironment variable is set to
7995.q /safe
7996then aliases of
7997.q /safe/logs/file
7998and
7999.q /logs/file
8000actually indicate the same file.
8001Additionally, if this option is set,
8002.i sendmail
8003refuses to deliver to symbolic links.
8004.ip SaveFromLine
8005[f]
8006Save
8007UNIX-style
8008.q From
8009lines at the front of headers.
8010Normally they are assumed redundant
8011and discarded.
8012.ip SendMimeErrors
8013[j]
8014If set, send error messages in MIME format
8015(see RFC 2045 and RFC 1344 for details).
8016If disabled,
8017.i sendmail
8018will not return the DSN keyword in response to an EHLO
8019and will not do Delivery Status Notification processing as described in
8020RFC 1891.
8021.ip ServerCertFile
8022[no short name]
8023File containing the certificate of the server, i.e., this certificate
8024is used when sendmail acts as server
8025(used for STARTTLS).
8026.ip ServerKeyFile
8027[no short name]
8028File containing the private key belonging to the server certificate
8029(used for STARTTLS).
8030.ip ServiceSwitchFile=\fIfilename\fP
8031[no short name]
8032If your host operating system has a service switch abstraction
8033(e.g., /etc/nsswitch.conf on Solaris
8034or /etc/svc.conf on Ultrix and DEC OSF/1)
8035that service will be consulted and this option is ignored.
8036Otherwise, this is the name of a file
8037that provides the list of methods used to implement particular services.
8038The syntax is a series of lines,
8039each of which is a sequence of words.
8040The first word is the service name,
8041and following words are service types.
8042The services that
8043.i sendmail
8044consults directly are
8045.q aliases
8046and
8047.q hosts.
8048Service types can be
8049.q dns ,
8050.q nis ,
8051.q nisplus ,
8052or
8053.q files
8054(with the caveat that the appropriate support
8055must be compiled in
8056before the service can be referenced).
8057If ServiceSwitchFile is not specified, it defaults to
8058/etc/mail/service.switch.
8059If that file does not exist, the default switch is:
8060.(b
8061aliases files
8062hosts dns nis files
8063.)b
8064The default file is
8065.q /etc/mail/service.switch .
8066.ip SevenBitInput
8067[7]
8068Strip input to seven bits for compatibility with old systems.
8069This shouldn't be necessary.
8070.ip SharedMemoryKey
8071[no short name]
8072Key to use for shared memory segment;
8073if not set (or 0), shared memory will not be used.
8074If set to
8075-1
8076.i sendmail
8077can select a key itself provided that also
8078.b SharedMemoryKeyFile
8079is set.
8080Requires support for shared memory to be compiled into
8081.i sendmail .
8082If this option is set,
8083.i sendmail
8084can share some data between different instances.
8085For example, the number of entries in a queue directory
8086or the available space in a file system.
8087This allows for more efficient program execution, since only
8088one process needs to update the data instead of each individual
8089process gathering the data each time it is required.
8090.ip SharedMemoryKeyFile
8091[no short name]
8092If
8093.b SharedMemoryKey
8094is set to
8095-1
8096then the automatically selected shared memory key will be stored
8097in the specified file.
8098.ip SingleLineFromHeader
8099[no short name]
8100If set, From: lines that have embedded newlines are unwrapped
8101onto one line.
8102This is to get around a botch in Lotus Notes
8103that apparently cannot understand legally wrapped RFC 822 headers.
8104.ip SingleThreadDelivery
8105[no short name]
8106If set, a client machine will never try to open two SMTP connections
8107to a single server machine at the same time,
8108even in different processes.
8109That is, if another
8110.i sendmail
8111is already talking to some host a new
8112.i sendmail
8113will not open another connection.
8114This property is of mixed value;
8115although this reduces the load on the other machine,
8116it can cause mail to be delayed
8117(for example, if one
8118.i sendmail
8119is delivering a huge message, other
8120.i sendmail s
8121won't be able to send even small messages).
8122Also, it requires another file descriptor
8123(for the lock file)
8124per connection, so you may have to reduce the
8125.b ConnectionCacheSize
8126option to avoid running out of per-process file descriptors.
8127Requires the
8128.b HostStatusDirectory
8129option.
8130.ip SmtpGreetingMessage=\fImessage\fP
8131[$e macro]
8132The message printed when the SMTP server starts up.
8133Defaults to
8134.q "$j Sendmail $v ready at $b".
8135.ip SoftBounce
8136If set, issue temporary errors (4xy) instead of permanent errors (5xy).
8137This can be useful during testing of a new configuration to avoid
8138erroneous bouncing of mails.
8139.ip StatusFile=\fIfile\fP
8140[S]
8141Log summary statistics in the named
8142.i file .
8143If no file name is specified, "statistics" is used.
8144If not set,
8145no summary statistics are saved.
8146This file does not grow in size.
8147It can be printed using the
8148.i mailstats (8)
8149program.
8150.ip SuperSafe
8151[s]
8152This option can be set to True, False, Interactive, or PostMilter.
8153If set to True,
8154.i sendmail
8155will be super-safe when running things,
8156i.e., always instantiate the queue file,
8157even if you are going to attempt immediate delivery.
8158.i Sendmail
8159always instantiates the queue file
8160before returning control to the client
8161under any circumstances.
8162This should really
8163.i always
8164be set to True.
8165The Interactive value has been introduced in 8.12 and can
8166be used together with
8167.b DeliveryMode=i .
8168It skips some synchronization calls which are effectively
8169doubled in the code execution path for this mode.
8170If set to PostMilter,
8171.i sendmail
8172defers synchronizing the queue file until any milters have
8173signaled acceptance of the message.
8174PostMilter is useful only when
8175.i sendmail
8176is running as an SMTP server; in all other situations it
8177acts the same as True.
8178.ip TLSSrvOptions
8179[no short name]
8180List of options for SMTP STARTTLS for the server
8181consisting of single characters
8182with intervening white space or commas.
8183The flag ``V'' disables client verification, and hence
8184it is not possible to use a client certificate for relaying.
8185Currently there are no other flags available.
8186.ip TempFileMode=\fImode\fP
8187[F]
8188The file mode for transcript files, files to which
8189.i sendmail
8190delivers directly, files in the
8191.b HostStatusDirectory ,
8192and
8193.b StatusFile .
8194It is interpreted in octal by default.
8195Defaults to 0600.
8196.ip Timeout.\fItype\fP=\|\fItimeout\fP
8197[r; subsumes old T option as well]
8198Set timeout values.
8199For more information,
8200see section
8201.\" XREF
82024.1.
8203.ip TimeZoneSpec=\fItzinfo\fP
8204[t]
8205Set the local time zone info to
8206.i tzinfo
8207\*- for example,
8208.q PST8PDT .
8209Actually, if this is not set,
8210the TZ environment variable is cleared (so the system default is used);
8211if set but null, the user's TZ variable is used,
8212and if set and non-null the TZ variable is set to this value.
8213.ip TrustedUser=\fIuser\fP
8214[no short name]
8215The
8216.i user
8217parameter may be a user name
8218(looked up in
8219.i /etc/passwd )
8220or a numeric user id.
8221Trusted user for file ownership and starting the daemon. If set, generated
8222alias databases and the control socket (if configured) will automatically
8223be owned by this user.
8224.ip TryNullMXList
8225[w]
8226If this system is the
8227.q best
8228(that is, lowest preference)
8229MX for a given host,
8230its configuration rules should normally detect this situation
8231and treat that condition specially
8232by forwarding the mail to a UUCP feed,
8233treating it as local,
8234or whatever.
8235However, in some cases (such as Internet firewalls)
8236you may want to try to connect directly to that host
8237as though it had no MX records at all.
8238Setting this option causes
8239.i sendmail
8240to try this.
8241The downside is that errors in your configuration
8242are likely to be diagnosed as
8243.q "host unknown"
8244or
8245.q "message timed out"
8246instead of something more meaningful.
8247This option is disrecommended.
8248.ip UnixFromLine=\fIfromline\fP
8249[$l macro]
8250Defines the format used when
8251.i sendmail
8252must add a UNIX-style From_ line
8253(that is, a line beginning
8254.q From<space>user ).
8255Defaults to
8256.q "From $g $d" .
8257Don't change this unless your system uses a different UNIX mailbox format
8258(very unlikely).
8259.ip UnsafeGroupWrites
8260[no short name]
8261If set (default),
8262:include: and .forward files that are group writable are considered
8263.q unsafe ,
8264that is,
8265they cannot reference programs or write directly to files.
8266World writable :include: and .forward files
8267are always unsafe.
8268Note: use
8269.b DontBlameSendmail
8270instead; this option is deprecated.
8271.ip UseErrorsTo
8272[l]
8273If there is an
8274.q Errors-To:
8275header, send error messages to the addresses listed there.
8276They normally go to the envelope sender.
8277Use of this option causes
8278.i sendmail
8279to violate RFC 1123.
8280This option is disrecommended and deprecated.
8281.ip UserDatabaseSpec=\fIudbspec\fP
8282[U]
8283The user database specification.
8284.ip Verbose
8285[v]
8286Run in verbose mode.
8287If this is set,
8288.i sendmail
8289adjusts options
8290.b HoldExpensive
8291(old
8292.b c )
8293and
8294.b DeliveryMode
8295(old
8296.b d )
8297so that all mail is delivered completely
8298in a single job
8299so that you can see the entire delivery process.
8300Option
8301.b Verbose
8302should
8303.i never
8304be set in the configuration file;
8305it is intended for command line use only.
8306Note that the use of option
8307.b Verbose
8308can cause authentication information to leak, if you use a
8309sendmail client to authenticate to a server.
8310If the authentication mechanism uses plain text passwords
8311(as with LOGIN or PLAIN),
8312then the password could be compromised.
8313To avoid this, do not install sendmail set-user-ID root,
8314and disable the
8315.b VERB
8316SMTP command with a suitable
8317.b PrivacyOptions
8318setting.
8319.ip XscriptFileBufferSize=\fIthreshold\fP
8320[no short name]
8321Set the
8322.i threshold ,
8323in bytes,
8324before a memory-based
8325queue transcript file
8326becomes disk-based.
8327The default is 4096 bytes.
8328.lp
8329All options can be specified on the command line using the
8330\-O or \-o flag,
8331but most will cause
8332.i sendmail
8333to relinquish its set-user-ID permissions.
8334The options that will not cause this are
8335SevenBitInput [7],
8336EightBitMode [8],
8337MinFreeBlocks [b],
8338CheckpointInterval [C],
8339DeliveryMode [d],
8340ErrorMode [e],
8341IgnoreDots [i],
8342SendMimeErrors [j],
8343LogLevel [L],
8344MeToo [m],
8345OldStyleHeaders [o],
8346PrivacyOptions [p],
8347SuperSafe [s],
8348Verbose [v],
8349QueueSortOrder,
8350MinQueueAge,
8351DefaultCharSet,
8352Dial Delay,
8353NoRecipientAction,
8354ColonOkInAddr,
8355MaxQueueRunSize,
8356SingleLineFromHeader,
8357and
8358AllowBogusHELO.
8359Actually, PrivacyOptions [p] given on the command line
8360are added to those already specified in the
8361.i sendmail.cf
8362file, i.e., they can't be reset.
8363Also, M (define macro) when defining the r or s macros
8364is also considered
8365.q safe .
8366.sh 2 "P \*- Precedence Definitions"
8367.pp
8368Values for the
8369.q "Precedence:"
8370field may be defined using the
8371.b P
8372control line.
8373The syntax of this field is:
8374.(b
8375\fBP\fP\fIname\fP\fB=\fP\fInum\fP
8376.)b
8377When the
8378.i name
8379is found in a
8380.q Precedence:
8381field,
8382the message class is set to
8383.i num .
8384Higher numbers mean higher precedence.
8385Numbers less than zero
8386have the special property
8387that if an error occurs during processing
8388the body of the message will not be returned;
8389this is expected to be used for
8390.q "bulk"
8391mail such as through mailing lists.
8392The default precedence is zero.
8393For example,
8394our list of precedences is:
8395.(b
8396Pfirst-class=0
8397Pspecial-delivery=100
8398Plist=\-30
8399Pbulk=\-60
8400Pjunk=\-100
8401.)b
8402People writing mailing list exploders
8403are encouraged to use
8404.q "Precedence: list" .
8405Older versions of
8406.i sendmail
8407(which discarded all error returns for negative precedences)
8408didn't recognize this name, giving it a default precedence of zero.
8409This allows list maintainers to see error returns
8410on both old and new versions of
8411.i sendmail .
8412.sh 2 "V \*- Configuration Version Level"
8413.pp
8414To provide compatibility with old configuration files,
8415the
8416.b V
8417line has been added to define some very basic semantics
8418of the configuration file.
8419These are not intended to be long term supports;
8420rather, they describe compatibility features
8421which will probably be removed in future releases.
8422.pp
8423.b N.B.:
8424these version
8425.i levels
8426have nothing
8427to do with the version
8428.i number
8429on the files.
8430For example,
8431as of this writing
8432version 10 config files
8433(specifically, 8.10)
8434used version level 9 configurations.
8435.pp
8436.q Old
8437configuration files are defined as version level one.
8438Version level two files make the following changes:
8439.np
8440Host name canonification ($[ ... $])
8441appends a dot if the name is recognized;
8442this gives the config file a way of finding out if anything matched.
8443(Actually, this just initializes the
8444.q host
8445map with the
8446.q \-a.
8447flag \*- you can reset it to anything you prefer
8448by declaring the map explicitly.)
8449.np
8450Default host name extension is consistent throughout processing;
8451version level one configurations turned off domain extension
8452(that is, adding the local domain name)
8453during certain points in processing.
8454Version level two configurations are expected to include a trailing dot
8455to indicate that the name is already canonical.
8456.np
8457Local names that are not aliases
8458are passed through a new distinguished ruleset five;
8459this can be used to append a local relay.
8460This behavior can be prevented by resolving the local name
8461with an initial `@'.
8462That is, something that resolves to a local mailer and a user name of
8463.q vikki
8464will be passed through ruleset five,
8465but a user name of
8466.q @vikki
8467will have the `@' stripped,
8468will not be passed through ruleset five,
8469but will otherwise be treated the same as the prior example.
8470The expectation is that this might be used to implement a policy
8471where mail sent to
8472.q vikki
8473was handled by a central hub,
8474but mail sent to
8475.q vikki@localhost
8476was delivered directly.
8477.pp
8478Version level three files
8479allow # initiated comments on all lines.
8480Exceptions are backslash escaped # marks
8481and the $# syntax.
8482.pp
8483Version level four configurations
8484are completely equivalent to level three
8485for historical reasons.
8486.pp
8487Version level five configuration files
8488change the default definition of
8489.b $w
8490to be just the first component of the hostname.
8491.pp
8492Version level six configuration files
8493change many of the local processing options
8494(such as aliasing and matching the beginning of the address for
8495`|' characters)
8496to be mailer flags;
8497this allows fine-grained control over the special local processing.
8498Level six configuration files may also use long option names.
8499The
8500.b ColonOkInAddr
8501option (to allow colons in the local-part of addresses)
8502defaults
8503.b on
8504for lower numbered configuration files;
8505the configuration file requires some additional intelligence
8506to properly handle the RFC 822 group construct.
8507.pp
8508Version level seven configuration files
8509used new option names to replace old macros
8510(\c
8511.b $e
8512became
8513.b SmtpGreetingMessage ,
8514.b $l
8515became
8516.b UnixFromLine ,
8517and
8518.b $o
8519became
8520.b OperatorChars .
8521Also, prior to version seven,
8522the
8523.b F=q
8524flag (use 250 instead of 252 return value for
8525.sm "SMTP VRFY"
8526commands)
8527was assumed.
8528.pp
8529Version level eight configuration files allow
8530.b $#
8531on the left hand side of ruleset lines.
8532.pp
8533Version level nine configuration files allow
8534parentheses in rulesets, i.e. they are not treated
8535as comments and hence removed.
8536.pp
8537Version level ten configuration files allow
8538queue group definitions.
8539.pp
8540The
8541.b V
8542line may have an optional
8543.b / \c
8544.i vendor
8545to indicate that this configuration file uses modifications
8546specific to a particular vendor\**.
8547.(f
8548\**And of course, vendors are encouraged to add themselves
8549to the list of recognized vendors by editing the routine
8550.i setvendor
8551in
8552.i conf.c .
8553Please send e-mail to sendmail@Sendmail.ORG
8554to register your vendor dialect.
8555.)f
8556You may use
8557.q /Berkeley
8558to emphasize that this configuration file
8559uses the Berkeley dialect of
8560.i sendmail .
8561.sh 2 "K \*- Key File Declaration"
8562.pp
8563Special maps can be defined using the line:
8564.(b
8565Kmapname mapclass arguments
8566.)b
8567The
8568.i mapname
8569is the handle by which this map is referenced in the rewriting rules.
8570The
8571.i mapclass
8572is the name of a type of map;
8573these are compiled in to
8574.i sendmail .
8575The
8576.i arguments
8577are interpreted depending on the class;
8578typically,
8579there would be a single argument naming the file containing the map.
8580.pp
8581Maps are referenced using the syntax:
8582.(b
8583$( \fImap\fP \fIkey\fP $@ \fIarguments\fP $: \fIdefault\fP $)
8584.)b
8585where either or both of the
8586.i arguments
8587or
8588.i default
8589portion may be omitted.
8590The
8591.i "$@ arguments"
8592may appear more than once.
8593The indicated
8594.i key
8595and
8596.i arguments
8597are passed to the appropriate mapping function.
8598If it returns a value, it replaces the input.
8599If it does not return a value and the
8600.i default
8601is specified, the
8602.i default
8603replaces the input.
8604Otherwise, the input is unchanged.
8605.pp
8606The
8607.i arguments
8608are passed to the map for arbitrary use.
8609Most map classes can interpolate these arguments
8610into their values using the syntax
8611.q %\fIn\fP
8612(where
8613.i n
8614is a digit)
8615to indicate the corresponding
8616.i argument .
8617Argument
8618.q %0
8619indicates the database key.
8620For example, the rule
8621.(b
8622.ta 1.5i
8623R$\- ! $+ $: $(uucp $1 $@ $2 $: $2 @ $1 . UUCP $)
8624.)b
8625Looks up the UUCP name in a (user defined) UUCP map;
8626if not found it turns it into
8627.q \&.UUCP
8628form.
8629The database might contain records like:
8630.(b
8631decvax %1@%0.DEC.COM
8632research %1@%0.ATT.COM
8633.)b
8634Note that
8635.i default
8636clauses never do this mapping.
8637.pp
8638The built-in map with both name and class
8639.q host
8640is the host name canonicalization lookup.
8641Thus,
8642the syntax:
8643.(b
8644$(host \fIhostname\fP$)
8645.)b
8646is equivalent to:
8647.(b
8648$[\fIhostname\fP$]
8649.)b
8650.pp
8651There are many defined classes.
8652.ip dbm
8653Database lookups using the ndbm(3) library.
8654.i Sendmail
8655must be compiled with
8656.b NDBM
8657defined.
8658.ip btree
8659Database lookups using the btree interface to the Berkeley DB
8660library.
8661.i Sendmail
8662must be compiled with
8663.b NEWDB
8664defined.
8665.ip hash
8666Database lookups using the hash interface to the Berkeley DB
8667library.
8668.i Sendmail
8669must be compiled with
8670.b NEWDB
8671defined.
8672.ip nis
8673NIS lookups.
8674.i Sendmail
8675must be compiled with
8676.b NIS
8677defined.
8678.ip nisplus
8679NIS+ lookups.
8680.i Sendmail
8681must be compiled with
8682.b NISPLUS
8683defined.
8684The argument is the name of the table to use for lookups,
8685and the
8686.b \-k
8687and
8688.b \-v
8689flags may be used to set the key and value columns respectively.
8690.ip hesiod
8691Hesiod lookups.
8692.i Sendmail
8693must be compiled with
8694.b HESIOD
8695defined.
8696.ip ldap
8697LDAP X500 directory lookups.
8698.i Sendmail
8699must be compiled with
8700.b LDAPMAP
8701defined.
8702The map supports most of the standard arguments
8703and most of the command line arguments of the
8704.i ldapsearch
8705program.
8706Note that,
8707by default,
8708if a single query matches multiple values,
8709only the first value will be returned
8710unless the
8711.b \-z
8712(value separator)
8713map flag is set.
8714Also, the
8715.b \-1
8716map flag will treat a multiple value return
8717as if there were no matches.
8718.ip netinfo
8719NeXT NetInfo lookups.
8720.i Sendmail
8721must be compiled with
8722.b NETINFO
8723defined.
8724.ip text
8725Text file lookups.
8726The format of the text file is defined by the
8727.b \-k
8728(key field number),
8729.b \-v
8730(value field number),
8731and
8732.b \-z
8733(field delimiter)
8734flags.
8735.ip ph
8736PH query map.
8737Contributed and supported by
8738Mark Roth, roth@uiuc.edu.
8739For more information,
8740consult the web site
8741.q http://www-dev.cites.uiuc.edu/sendmail/ .
8742.ip nsd
8743nsd map for IRIX 6.5 and later.
8744Contributed and supported by Bob Mende of SGI,
8745mende@sgi.com.
8746.ip stab
8747Internal symbol table lookups.
8748Used internally for aliasing.
8749.ip implicit
8750Really should be called
8751.q alias
8752\(em this is used to get the default lookups
8753for alias files,
8754and is the default if no class is specified for alias files.
8755.ip user
8756Looks up users using
8757.i getpwnam (3).
8758The
8759.b \-v
8760flag can be used to specify the name of the field to return
8761(although this is normally used only to check the existence
8762of a user).
8763.ip host
8764Canonifies host domain names.
8765Given a host name it calls the name server
8766to find the canonical name for that host.
8767.ip bestmx
8768Returns the best MX record for a host name given as the key.
8769The current machine is always preferred \*-
8770that is, if the current machine is one of the hosts listed as a
8771lowest-preference MX record, then it will be guaranteed to be returned.
8772This can be used to find out if this machine is the target for an MX record,
8773and mail can be accepted on that basis.
8774If the
8775.b \-z
8776flag is given, then all MX names are returned,
8777separated by the given delimiter.
8778.ip dns
8779This map requires the option -R to specify the DNS resource record
8780type to lookup. The following types are supported:
8781A, AAAA, AFSDB, CNAME, MX, NS, PTR, SRV, and TXT.
8782A map lookup will return only one record.
8783Hence for some types, e.g., MX records, the return value might be a random
8784element of the list due to randomizing in the DNS resolver.
8785.ip sequence
8786The arguments on the `K' line are a list of maps;
8787the resulting map searches the argument maps in order
8788until it finds a match for the indicated key.
8789For example, if the key definition is:
8790.(b
8791Kmap1 ...
8792Kmap2 ...
8793Kseqmap sequence map1 map2
8794.)b
8795then a lookup against
8796.q seqmap
8797first does a lookup in map1.
8798If that is found, it returns immediately.
8799Otherwise, the same key is used for map2.
8800.ip syslog
8801the key is logged via
8802.i syslogd \|(8).
8803The lookup returns the empty string.
8804.ip switch
8805Much like the
8806.q sequence
8807map except that the order of maps is determined by the service switch.
8808The argument is the name of the service to be looked up;
8809the values from the service switch are appended to the map name
8810to create new map names.
8811For example, consider the key definition:
8812.(b
8813Kali switch aliases
8814.)b
8815together with the service switch entry:
8816.(b
8817aliases nis files
8818.)b
8819This causes a query against the map
8820.q ali
8821to search maps named
8822.q ali.nis
8823and
8824.q ali.files
8825in that order.
8826.ip dequote
8827Strip double quotes (") from a name.
8828It does not strip backslashes,
8829and will not strip quotes if the resulting string
8830would contain unscannable syntax
8831(that is, basic errors like unbalanced angle brackets;
8832more sophisticated errors such as unknown hosts are not checked).
8833The intent is for use when trying to accept mail from systems such as
8834DECnet
8835that routinely quote odd syntax such as
8836.(b
8837"49ers::ubell"
8838.)b
8839A typical usage is probably something like:
8840.(b
8841Kdequote dequote
8842
8843\&...
8844
8845R$\- $: $(dequote $1 $)
8846R$\- $+ $: $>3 $1 $2
8847.)b
8848Care must be taken to prevent unexpected results;
8849for example,
8850.(b
8851"|someprogram < input > output"
8852.)b
8853will have quotes stripped,
8854but the result is probably not what you had in mind.
8855Fortunately these cases are rare.
8856.ip regex
8857The map definition on the
8858.b K
8859line contains a regular expression.
8860Any key input is compared to that expression using the
8861POSIX regular expressions routines regcomp(), regerr(), and regexec().
8862Refer to the documentation for those routines for more information
8863about the regular expression matching.
8864No rewriting of the key is done if the
8865.b \-m
8866flag is used. Without it, the key is discarded or if
8867.b \-s
8868if used, it is substituted by the substring matches, delimited by
8869.b $|
8870or the string specified with the the
8871.b \-d
8872flag. The flags available for the map are
8873.(b
8874.ta 4n
8875-n not
8876-f case sensitive
8877-b basic regular expressions (default is extended)
8878-s substring match
8879-d set the delimiter used for -s
8880-a append string to key
8881-m match only, do not replace/discard value
8882-D perform no lookup in deferred delivery mode.
8883.)b
8884The
8885.b \-s
8886flag can include an optional parameter which can be used
8887to select the substrings in the result of the lookup. For example,
8888.(b
8889-s1,3,4
8890.)b
8891Notes: to match a
8892.b $
8893in a string,
8894\\$$
8895must be used.
8896If the pattern contains spaces, they must be replaced
8897with the blank substitution character, unless it is
8898space itself.
8899.ip program
8900The arguments on the
8901.b K
8902line are the pathname to a program and any initial parameters to be passed.
8903When the map is called,
8904the key is added to the initial parameters
8905and the program is invoked
8906as the default user/group id.
8907The first line of standard output is returned as the value of the lookup.
8908This has many potential security problems,
8909and has terrible performance;
8910it should be used only when absolutely necessary.
8911.ip macro
8912Set or clear a macro value.
8913To set a macro,
8914pass the value as the first argument in the map lookup.
8915To clear a macro,
8916do not pass an argument in the map lookup.
8917The map always returns the empty string.
8918Example of typical usage include:
8919.(b
8920Kstorage macro
8921
8922\&...
8923
8924# set macro ${MyMacro} to the ruleset match
8925R$+ $: $(storage {MyMacro} $@ $1 $) $1
8926# set macro ${MyMacro} to an empty string
8927R$* $: $(storage {MyMacro} $@ $) $1
8928# clear macro ${MyMacro}
8929R$\- $: $(storage {MyMacro} $) $1
8930.)b
8931.ip arith
8932Perform simple arithmetic operations.
8933The operation is given as key, currently
8934+, -, *, /, %,
8935|, & (bitwise OR, AND),
8936l (for less than), =,
8937and r (for random) are supported.
8938The two operands are given as arguments.
8939The lookup returns the result of the computation,
8940i.e.,
8941.sm TRUE
8942or
8943.sm FALSE
8944for comparisons, integer values otherwise.
8945The r operator returns a pseudo-random number whose value
8946lies between the first and second operand
8947(which requires that the first operand is smaller than the second).
8948All options which are possible for maps are ignored.
8949A simple example is:
8950.(b
8951Kcomp arith
8952
8953\&...
8954
8955Scheck_etrn
8956R$* $: $(comp l $@ $&{load_avg} $@ 7 $) $1
8957RFALSE $# error \&...
8958.)b
8959.ip socket
8960The socket map uses a simple request/reply protocol over TCP or UNIX domain
8961sockets to query an external server.
8962Both requests and replies are text based and encoded as netstrings,
8963i.e., a string "hello there" becomes:
8964.(b
896511:hello there,
8966.)b
8967Note: neither requests nor replies end with CRLF.
8968
8969The request consists of the database map name and the lookup key separated
8970by a space character:
8971
8972.(b
8973<mapname> ' ' <key>
8974.)b
8975
8976The server responds with a status indicator and the result (if any):
8977
8978.(b
8979<status> ' ' <result>
8980.)b
8981
8982The status indicator specifies the result of the lookup operation itself
8983and is one of the following upper case words:
8984.(b
8985.ta 9n
8986OK the key was found, result contains the looked up value
8987NOTFOUND the key was not found, the result is empty
8988TEMP a temporary failure occured
8989TIMEOUT a timeout occured on the server side
8990PERM a permanent failure occured
8991.)b
8992
8993In case of errors (status TEMP, TIMEOUT or PERM) the result field may
8994contain an explanatory message.
8995However, the explanatory message is not used any further by
8996.i sendmail .
8997
8998Example replies:
8999.(b
900031:OK resolved.address@example.com,
9001.)b
9002
9003.(b
900456:OK error:550 5.7.1 User does not accept mail from sender,
9005.)b
9006
9007in case of successful lookups, or:
9008.(b
90098:NOTFOUND,
9010.)b
9011
9012in case the key was not found, or:
9013.(b
901455:TEMP this text explains that we had a temporary failure,
9015.)b
9016
9017in case of a temporary map lookup failure.
9018
9019The socket map uses the same syntax as milters
9020(see Section "X \*- Mail Filter (Milter) Definitions")
9021to specify the remote endpoint, e.g.,
9022.(b
9023Ksocket mySocketMap inet:12345@127.0.0.1
9024.)b
9025
9026If multiple socket maps define the same remote endpoint, they will share
9027a single connection to this endpoint.
9028.pp
9029Most of these accept as arguments the same optional flags
9030and a filename
9031(or a mapname for NIS;
9032the filename is the root of the database path,
9033so that
9034.q .db
9035or some other extension appropriate for the database type
9036will be added to get the actual database name).
9037Known flags are:
9038.ip "\-o"
9039Indicates that this map is optional \*- that is,
9040if it cannot be opened,
9041no error is produced,
9042and
9043.i sendmail
9044will behave as if the map existed but was empty.
9045.ip "\-N, \-O"
9046If neither
9047.b \-N
9048or
9049.b \-O
9050are specified,
9051.i sendmail
9052uses an adaptive algorithm to decide whether or not to look for null bytes
9053on the end of keys.
9054It starts by trying both;
9055if it finds any key with a null byte it never tries again without a null byte
9056and vice versa.
9057If
9058.b \-N
9059is specified it never tries without a null byte and
9060if
9061.b \-O
9062is specified it never tries with a null byte.
9063Setting one of
9064these can speed matches but are never necessary.
9065If both
9066.b \-N
9067and
9068.b \-O
9069are specified,
9070.i sendmail
9071will never try any matches at all \(em
9072that is, everything will appear to fail.
9073.ip "\-a\fIx\fP"
9074Append the string
9075.i x
9076on successful matches.
9077For example, the default
9078.i host
9079map appends a dot on successful matches.
9080.ip "\-T\fIx\fP"
9081Append the string
9082.i x
9083on temporary failures.
9084For example,
9085.i x
9086would be appended if a DNS lookup returned
9087.q "server failed"
9088or an NIS lookup could not locate a server.
9089See also the
9090.b \-t
9091flag.
9092.ip "\-f"
9093Do not fold upper to lower case before looking up the key.
9094.ip "\-m"
9095Match only (without replacing the value).
9096If you only care about the existence of a key and not the value
9097(as you might when searching the NIS map
9098.q hosts.byname
9099for example),
9100this flag prevents the map from substituting the value.
9101However,
9102The \-a argument is still appended on a match,
9103and the default is still taken if the match fails.
9104.ip "\-k\fIkeycol\fP"
9105The key column name (for NIS+) or number
9106(for text lookups).
9107For LDAP maps this is an LDAP filter string
9108in which %s is replaced with the literal contents of the lookup key
9109and %0 is replaced with the LDAP escaped contents of the lookup key
9110according to RFC 2254.
9111If the flag
9112.b \-K
9113is used, then %1 through %9 are replaced with the LDAP escaped contents
9114of the arguments specified in the map lookup.
9115.ip "\-v\fIvalcol\fP"
9116The value column name (for NIS+) or number
9117(for text lookups).
9118For LDAP maps this is the name of one or more
9119attributes to be returned;
9120multiple attributes can be separated by commas.
9121If not specified, all attributes found in the match
9122will be returned.
9123The attributes listed can also include a type and one or more
9124objectClass values for matching as described in the LDAP section.
9125.ip "\-z\fIdelim\fP"
9126The column delimiter (for text lookups).
9127It can be a single character or one of the special strings
9128.q \|\en
9129or
9130.q \|\et
9131to indicate newline or tab respectively.
9132If omitted entirely,
9133the column separator is any sequence of white space.
9134For LDAP maps this is the separator character
9135to combine multiple values
9136into a single return string.
9137If not set,
9138the LDAP lookup will only return the first match found.
9139For DNS maps this is the separator character at which
9140the result of a query is cut off if is too long.
9141.ip "\-t"
9142Normally, when a map attempts to do a lookup
9143and the server fails
9144(e.g.,
9145.i sendmail
9146couldn't contact any name server;
9147this is
9148.i not
9149the same as an entry not being found in the map),
9150the message being processed is queued for future processing.
9151The
9152.b \-t
9153flag turns off this behavior,
9154letting the temporary failure (server down)
9155act as though it were a permanent failure (entry not found).
9156It is particularly useful for DNS lookups,
9157where someone else's misconfigured name server can cause problems
9158on your machine.
9159However, care must be taken to ensure that you don't bounce mail
9160that would be resolved correctly if you tried again.
9161A common strategy is to forward such mail
9162to another, possibly better connected, mail server.
9163.ip "\-D"
9164Perform no lookup in deferred delivery mode.
9165This flag is set by default for the
9166.i host
9167map.
9168.ip "\-S\fIspacesub\fP
9169The character to use to replace space characters
9170after a successful map lookup (esp. useful for regex
9171and syslog maps).
9172.ip "\-s\fIspacesub\fP
9173For the dequote map only,
9174the character to use to replace space characters
9175after a successful dequote.
9176.ip "\-q"
9177Don't dequote the key before lookup.
9178.ip "\-L\fIlevel\fP
9179For the syslog map only, it specifies the level
9180to use for the syslog call.
9181.ip "\-A"
9182When rebuilding an alias file,
9183the
9184.b \-A
9185flag causes duplicate entries in the text version
9186to be merged.
9187For example, two entries:
9188.(b
9189list: user1, user2
9190list: user3
9191.)b
9192would be treated as though it were the single entry
9193.(b
9194list: user1, user2, user3
9195.)b
9196in the presence of the
9197.b \-A
9198flag.
9199.pp
9200Some additional flags are available for the host and dns maps:
9201.ip "\-d"
9202delay: specify the resolver's retransmission time interval (in seconds).
9203.ip "\-r"
9204retry: specify the number of times to retransmit a resolver query.
9205.pp
9206The dns map has another flag:
9207.ip "\-B"
9208basedomain: specify a domain that is always appended to queries.
9209.pp
9210The following additional flags are present in the ldap map only:
9211.ip "\-R"
9212Do not auto chase referrals. sendmail must be compiled with
9213.b \-DLDAP_REFERRALS
9214to use this flag.
9215.ip "\-n"
9216Retrieve attribute names only.
9217.ip "\-V\fIsep\fP"
9218Retrieve both attributes name and value(s),
9219separated by
9220.i sep .
9221.ip "\-r\fIderef\fP"
9222Set the alias dereference option to one of never, always, search, or find.
9223.ip "\-s\fIscope\fP"
9224Set search scope to one of base, one (one level), or sub (subtree).
9225.ip "\-h\fIhost\fP"
9226LDAP server hostname.
9227Some LDAP libraries allow you to specify multiple, space-separated hosts for
9228redundancy.
9229In addition, each of the hosts listed can be followed by a colon and a port
9230number to override the default LDAP port.
9231.ip "\-p\fIport\fP"
9232LDAP service port.
9233.ip "\-H \fILDAPURI\fP"
9234Use the specified LDAP URI instead of specifying the hostname and port
9235separately with the the
9236.b \-h
9237and
9238.b \-p
9239options shown above.
9240For example,
9241.(b
9242-h server.example.com -p 389 -b dc=example,dc=com
9243.)b
9244is equivalent to
9245.(b
9246-H ldap://server.example.com:389 -b dc=example,dc=com
9247.)b
9248If the LDAP library supports it,
9249the LDAP URI format however can also request LDAP over SSL by using
9250.b ldaps://
9251instead of
9252.b ldap:// .
9253For example:
9254.(b
9255O LDAPDefaultSpec=-H ldaps://ldap.example.com -b dc=example,dc=com
9256.)b
9257Similarly, if the LDAP library supports it,
9258It can also be used to specify a UNIX domain socket using
9259.b ldapi:// :
9260.(b
9261O LDAPDefaultSpec=-H ldapi://socketfile -b dc=example,dc=com
9262.)b
9263.ip "\-b\fIbase\fP"
9264LDAP search base.
9265.ip "\-l\fItimelimit\fP"
9266Time limit for LDAP queries.
9267.ip "\-Z\fIsizelimit\fP"
9268Size (number of matches) limit for LDAP or DNS queries.
9269.ip "\-d\fIdistinguished_name\fP"
9270The distinguished name to use to login to the LDAP server.
9271.ip "\-M\fImethod\fP"
9272The method to authenticate to the LDAP server.
9273Should be one of
9274.b LDAP_AUTH_NONE ,
9275.b LDAP_AUTH_SIMPLE ,
9276or
9277.b LDAP_AUTH_KRBV4 .
9278.ip "\-P\fIpasswordfile\fP"
9279The file containing the secret key for the
9280.b LDAP_AUTH_SIMPLE
9281authentication method
9282or the name of the Kerberos ticket file for
9283.b LDAP_AUTH_KRBV4 .
9284.ip "\-1"
9285Force LDAP searches to only succeed if a single match is found.
9286If multiple values are found,
9287the search is treated as if no match was found.
9288.ip "\-w\fIversion\fP"
9289Set the LDAP API/protocol version to use.
9290The default depends on the LDAP client libraries in use.
9291For example,
9292.b "\-w 3"
9293will cause
9294.i sendmail
9295to use LDAPv3 when communicating with the LDAP server.
9296.ip "\-K"
9297Treat the LDAP search key as multi-argument and
9298replace %1 through %9 in the key with
9299the LDAP escaped contents of the lookup arguments specified in the map lookup.
9300.pp
9301The
9302.i dbm
9303map appends the strings
9304.q \&.pag
9305and
9306.q \&.dir
9307to the given filename;
9308the
9309.i hash
9310and
9311.i btree
9312maps append
9313.q \&.db .
9314For example, the map specification
9315.(b
9316Kuucp dbm \-o \-N /etc/mail/uucpmap
9317.)b
9318specifies an optional map named
9319.q uucp
9320of class
9321.q dbm ;
9322it always has null bytes at the end of every string,
9323and the data is located in
9324/etc/mail/uucpmap.{dir,pag}.
9325.pp
9326The program
9327.i makemap (8)
9328can be used to build any of the three database-oriented maps.
9329It takes the following flags:
9330.ip \-f
9331Do not fold upper to lower case in the map.
9332.ip \-N
9333Include null bytes in keys.
9334.ip \-o
9335Append to an existing (old) file.
9336.ip \-r
9337Allow replacement of existing keys;
9338normally, re-inserting an existing key is an error.
9339.ip \-v
9340Print what is happening.
9341.lp
9342The
9343.i sendmail
9344daemon does not have to be restarted to read the new maps
9345as long as you change them in place;
9346file locking is used so that the maps won't be read
9347while they are being updated.
9348.pp
9349New classes can be added in the routine
9350.b setupmaps
9351in file
9352.b conf.c .
9353.sh 2 "Q \*- Queue Group Declaration"
9354.pp
9355In addition to the option
9356.i QueueDirectory,
9357queue groups can be declared that define a (group of) queue directories
9358under a common name.
9359The syntax is as follows:
9360.(b F
9361.b Q \c
9362.i name
9363{, \c
9364.i field =\c
9365.i value \|}+
9366.)b
9367where
9368.i name
9369is the symbolic name of the queue group under which
9370it can be referenced in various places
9371and the
9372.q field=value
9373pairs define attributes of the queue group.
9374The name must only consist of alphanumeric characters.
9375Fields are:
9376.ip Flags
9377Flags for this queue group.
9378.ip Nice
9379The nice(2) increment for the queue group.
9380This value must be greater or equal zero.
9381.ip Interval
9382The time between two queue runs.
9383.ip Path
9384The queue directory of the group (required).
9385.ip Runners
9386The number of parallel runners processing the queue.
9387Note that
9388.b F=f
9389must be set if this value is greater than one.
9390.ip Jobs
9391The maximum number of jobs (messages delivered) per queue run.
9392.ip recipients
9393The maximum number of recipients per envelope.
9394Envelopes with more than this number of recipients will be split
9395into multiple envelopes in the same queue directory.
9396The default value 0 means no limit.
9397.lp
9398Only the first character of the field name is checked.
9399.pp
9400By default, a queue group named
9401.i mqueue
9402is defined that uses the value of the
9403.i QueueDirectory
9404option as path.
9405Notice: all paths that are used for queue groups must
9406be subdirectories of
9407.i QueueDirectory .
9408Since they can be symbolic links, this isn't a real restriction,
9409If
9410.i QueueDirectory
9411uses a wildcard, then the directory one level up is considered
9412the ``base'' directory which all other queue directories must share.
9413Please make sure that the queue directories do not overlap,
9414e.g., do not specify
9415.(b
9416O QueueDirectory=/var/spool/mqueue/*
9417Qone, P=/var/spool/mqueue/dir1
9418Qtwo, P=/var/spool/mqueue/dir2
9419.)b
9420because this also includes
9421.q dir1
9422and
9423.q dir2
9424in the default queue group.
9425However,
9426.(b
9427O QueueDirectory=/var/spool/mqueue/main*
9428Qone, P=/var/spool/mqueue/dir
9429Qtwo, P=/var/spool/mqueue/other*
9430.)b
9431is a valid queue group specification.
9432.pp
9433Options listed in the ``Flags'' field can be used to modify
9434the behavior of a queue group.
9435The ``f'' flag must be set if multiple queue runners are
9436supposed to work on the entries in a queue group.
9437Otherwise
9438.i sendmail
9439will work on the entries strictly sequentially.
9440.pp
9441The ``Interval'' field sets the time between queue runs.
9442If no queue group specific interval is set, then the parameter of the
9443.b -q
9444option from the command line is used.
9445.pp
9446To control the overall number of concurrently active queue runners
9447the option
9448.b MaxQueueChildren
9449can be set.
9450This limits the number of processes used for running the queues to
9451.b MaxQueueChildren ,
9452though at any one time fewer processes may be active
9453as a result of queue options, completed queue runs, system load, etc.
9454.pp
9455The maximum number of queue runners for an individual queue group can be
9456controlled via the
9457.b Runners
9458option.
9459If set to 0, entries in the queue will not be processed, which
9460is useful to ``quarantine'' queue files.
9461The number of runners per queue group may also be set with the option
9462.b MaxRunnersPerQueue ,
9463which applies to queue groups that have no individual limit.
9464That is, the default value for
9465.b Runners
9466is
9467.b MaxRunnersPerQueue
9468if set, otherwise 1.
9469.pp
9470The field Jobs describes the maximum number of jobs
9471(messages delivered) per queue run, which is the queue group specific
9472value of
9473.b MaxQueueRunSize .
9474.pp
9475Notice: queue groups should be declared after all queue related options
9476have been set because queue groups take their defaults from those options.
9477If an option is set after a queue group declaration, the values of
9478options in the queue group are set to the defaults of
9479.i sendmail
9480unless explicitly set in the declaration.
9481.pp
9482Each envelope is assigned to a queue group based on the algorithm
9483described in section
9484``Queue Groups and Queue Directories''.
9485.sh 2 "X \*- Mail Filter (Milter) Definitions"
9486.pp
9487The
9488.i sendmail
9489Mail Filter API (Milter) is designed to allow third-party programs access
9490to mail messages as they are being processed in order to filter
9491meta-information and content.
9492They are declared in the configuration file as:
9493.(b F
9494.b X \c
9495.i name
9496{, \c
9497.i field =\c
9498.i value \|}*
9499.)b
9500where
9501.i name
9502is the name of the filter
9503(used internally only)
9504and the
9505.q field=name
9506pairs define attributes of the filter.
9507Also see the documentation for the
9508.b InputMailFilters
9509option for more information.
9510.pp
9511Fields are:
9512.(b
9513.ta 1i
9514Socket The socket specification
9515Flags Special flags for this filter
9516Timeouts Timeouts for this filter
9517.)b
9518Only the first character of the field name is checked
9519(it's case-sensitive).
9520.pp
9521The socket specification is one of the following forms:
9522.(b F
9523.b S= \c
9524.b inet \c
9525.b :
9526.i port
9527.b @
9528.i host
9529.)b
9530.(b F
9531.b S= \c
9532.b inet6 \c
9533.b :
9534.i port
9535.b @
9536.i host
9537.)b
9538.(b F
9539.b S= \c
9540.b local \c
9541.b :
9542.i path
9543.)b
9544The first two describe an IPv4 or IPv6 socket listening on a certain
9545.i port
9546at a given
9547.i host
9548or IP address.
9549The final form describes a named socket on the filesystem at the given
9550.i path .
9551.pp
9552The following flags may be set in the filter description.
9553.nr ii 4n
9554.ip R
9555Reject connection if filter unavailable.
9556.ip T
9557Temporary fail connection if filter unavailable.
9558.pp
9559If neither F=R nor F=T is specified, the message is passed through
9560.i sendmail
9561in case of filter errors as if the failing filters were not present.
9562.pp
9563The timeouts can be set using the four fields inside of the
9564.b T=
9565equate:
9566.nr ii 4n
9567.ip C
9568Timeout for connecting to a filter.
9569If set to 0, the system's
9570.i connect()
9571timeout will be used.
9572.ip S
9573Timeout for sending information from the MTA to a filter.
9574.ip R
9575Timeout for reading reply from the filter.
9576.ip E
9577Overall timeout between sending end-of-message to filter and waiting for
9578the final acknowledgment.
9579.pp
9580Note the separator between each timeout field is a
9581.b ';' .
9582The default values (if not set) are:
9583.b T=C:5m;S:10s;R:10s;E:5m
9584where
9585.b s
9586is seconds and
9587.b m
9588is minutes.
9589.pp
9590Examples:
9591.(b
9592Xfilter1, S=local:/var/run/f1.sock, F=R
9593Xfilter2, S=inet6:999@localhost, F=T, T=S:1s;R:1s;E:5m
9594Xfilter3, S=inet:3333@localhost, T=C:2m
9595.)b
9596.sh 2 "The User Database"
9597.pp
9598The user database is deprecated in favor of ``virtusertable''
9599and ``genericstable'' as explained in the file
9600.b cf/README .
9601If you have a version of
9602.i sendmail
9603with the user database package
9604compiled in,
9605the handling of sender and recipient addresses
9606is modified.
9607.pp
9608The location of this database is controlled with the
9609.b UserDatabaseSpec
9610option.
9611.sh 3 "Structure of the user database"
9612.pp
9613The database is a sorted (BTree-based) structure.
9614User records are stored with the key:
9615.(b
9616\fIuser-name\fP\fB:\fP\fIfield-name\fP
9617.)b
9618The sorted database format ensures that user records are clustered together.
9619Meta-information is always stored with a leading colon.
9620.pp
9621Field names define both the syntax and semantics of the value.
9622Defined fields include:
9623.nr ii 1i
9624.ip maildrop
9625The delivery address for this user.
9626There may be multiple values of this record.
9627In particular,
9628mailing lists will have one
9629.i maildrop
9630record for each user on the list.
9631.ip "mailname"
9632The outgoing mailname for this user.
9633For each outgoing name,
9634there should be an appropriate
9635.i maildrop
9636record for that name to allow return mail.
9637See also
9638.i :default:mailname .
9639.ip mailsender
9640Changes any mail sent to this address to have the indicated envelope sender.
9641This is intended for mailing lists,
9642and will normally be the name of an appropriate -request address.
9643It is very similar to the owner-\c
9644.i list
9645syntax in the alias file.
9646.ip fullname
9647The full name of the user.
9648.ip office-address
9649The office address for this user.
9650.ip office-phone
9651The office phone number for this user.
9652.ip office-fax
9653The office FAX number for this user.
9654.ip home-address
9655The home address for this user.
9656.ip home-phone
9657The home phone number for this user.
9658.ip home-fax
9659The home FAX number for this user.
9660.ip project
9661A (short) description of the project this person is affiliated with.
9662In the University this is often just the name of their graduate advisor.
9663.ip plan
9664A pointer to a file from which plan information can be gathered.
9665.pp
9666As of this writing,
9667only a few of these fields are actually being used by
9668.i sendmail :
9669.i maildrop
9670and
9671.i mailname .
9672A
9673.i finger
9674program that uses the other fields is planned.
9675.sh 3 "User database semantics"
9676.pp
9677When the rewriting rules submit an address to the local mailer,
9678the user name is passed through the alias file.
9679If no alias is found (or if the alias points back to the same address),
9680the name (with
9681.q :maildrop
9682appended)
9683is then used as a key in the user database.
9684If no match occurs (or if the maildrop points at the same address),
9685forwarding is tried.
9686.pp
9687If the first token of the user name returned by ruleset 0
9688is an
9689.q @
9690sign, the user database lookup is skipped.
9691The intent is that the user database will act as a set of defaults
9692for a cluster (in our case, the Computer Science Division);
9693mail sent to a specific machine should ignore these defaults.
9694.pp
9695When mail is sent,
9696the name of the sending user is looked up in the database.
9697If that user has a
9698.q mailname
9699record,
9700the value of that record is used as their outgoing name.
9701For example, I might have a record:
9702.(b
9703eric:mailname Eric.Allman@CS.Berkeley.EDU
9704.)b
9705This would cause my outgoing mail to be sent as Eric.Allman.
9706.pp
9707If a
9708.q maildrop
9709is found for the user,
9710but no corresponding
9711.q mailname
9712record exists,
9713the record
9714.q :default:mailname
9715is consulted.
9716If present, this is the name of a host to override the local host.
9717For example, in our case we would set it to
9718.q CS.Berkeley.EDU .
9719The effect is that anyone known in the database
9720gets their outgoing mail stamped as
9721.q user@CS.Berkeley.EDU ,
9722but people not listed in the database use the local hostname.
9723.sh 3 "Creating the database\**"
9724.(f
9725\**These instructions are known to be incomplete.
9726Other features are available which provide similar functionality,
9727e.g., virtual hosting and mapping local addresses into a
9728generic form as explained in cf/README.
9729.)f
9730.pp
9731The user database is built from a text file
9732using the
9733.i makemap
9734utility
9735(in the distribution in the makemap subdirectory).
9736The text file is a series of lines corresponding to userdb records;
9737each line has a key and a value separated by white space.
9738The key is always in the format described above \*-
9739for example:
9740.(b
9741eric:maildrop
9742.)b
9743This file is normally installed in a system directory;
9744for example, it might be called
9745.i /etc/mail/userdb .
9746To make the database version of the map, run the program:
9747.(b
9748makemap btree /etc/mail/userdb < /etc/mail/userdb
9749.)b
9750Then create a config file that uses this.
9751For example, using the V8 M4 configuration, include the
9752following line in your .mc file:
9753.(b
9754define(\`confUSERDB_SPEC\', /etc/mail/userdb)
9755.)b
9756.sh 1 "OTHER CONFIGURATION"
9757.pp
9758There are some configuration changes that can be made by
9759recompiling
9760.i sendmail .
9761This section describes what changes can be made
9762and what has to be modified to make them.
9763In most cases this should be unnecessary
9764unless you are porting
9765.i sendmail
9766to a new environment.
9767.sh 2 "Parameters in devtools/OS/$oscf"
9768.pp
9769These parameters are intended to describe the compilation environment,
9770not site policy,
9771and should normally be defined in the operating system
9772configuration file.
9773.b "This section needs a complete rewrite."
9774.ip NDBM
9775If set,
9776the new version of the DBM library
9777that allows multiple databases will be used.
9778If neither NDBM nor NEWDB are set,
9779a much less efficient method of alias lookup is used.
9780.ip NEWDB
9781If set, use the new database package from Berkeley (from 4.4BSD).
9782This package is substantially faster than DBM or NDBM.
9783If NEWDB and NDBM are both set,
9784.i sendmail
9785will read DBM files,
9786but will create and use NEWDB files.
9787.ip NIS
9788Include support for NIS.
9789If set together with
9790.i both
9791NEWDB and NDBM,
9792.i sendmail
9793will create both DBM and NEWDB files if and only if
9794an alias file includes the substring
9795.q /yp/
9796in the name.
9797This is intended for compatibility with Sun Microsystems'
9798.i mkalias
9799program used on YP masters.
9800.ip NISPLUS
9801Compile in support for NIS+.
9802.ip NETINFO
9803Compile in support for NetInfo (NeXT stations).
9804.ip LDAPMAP
9805Compile in support for LDAP X500 queries.
9806Requires libldap and liblber
9807from the Umich LDAP 3.2 or 3.3 release
9808or equivalent libraries for other LDAP libraries
9809such as OpenLDAP.
9810.ip HESIOD
9811Compile in support for Hesiod.
9812.ip MAP_NSD
9813Compile in support for IRIX NSD lookups.
9814.ip MAP_REGEX
9815Compile in support for regular expression matching.
9816.ip DNSMAP
9817Compile in support for DNS map lookups in the
9818.i sendmail.cf
9819file.
9820.ip PH_MAP
9821Compile in support for ph lookups.
9822.ip SASL
9823Compile in support for SASL,
9824a required component for SMTP Authentication support.
9825.ip STARTTLS
9826Compile in support for STARTTLS.
9827.ip EGD
9828Compile in support for the "Entropy Gathering Daemon"
9829to provide better random data for TLS.
9830.ip TCPWRAPPERS
9831Compile in support for TCP Wrappers.
9832.ip _PATH_SENDMAILCF
9833The pathname of the sendmail.cf file.
9834.ip _PATH_SENDMAILPID
9835The pathname of the sendmail.pid file.
9836.ip SM_CONF_SHM
9837Compile in support for shared memory, see section about
9838"/var/spool/mqueue".
9839.ip MILTER
9840Compile in support for contacting external mail filters built with the
9841Milter API.
9842.pp
9843There are also several compilation flags to indicate the environment
9844such as
9845.q _AIX3
9846and
9847.q _SCO_unix_ .
9848See the sendmail/README
9849file for the latest scoop on these flags.
9850.sh 2 "Parameters in sendmail/conf.h"
9851.pp
9852Parameters and compilation options
9853are defined in conf.h.
9854Most of these need not normally be tweaked;
9855common parameters are all in sendmail.cf.
9856However, the sizes of certain primitive vectors, etc.,
9857are included in this file.
9858The numbers following the parameters
9859are their default value.
9860.pp
9861This document is not the best source of information
9862for compilation flags in conf.h \(em
9863see sendmail/README or sendmail/conf.h itself.
9864.nr ii 1.2i
9865.ip "MAXLINE [2048]"
9866The maximum line length of any input line.
9867If message lines exceed this length
9868they will still be processed correctly;
9869however, header lines,
9870configuration file lines,
9871alias lines,
9872etc.,
9873must fit within this limit.
9874.ip "MAXNAME [256]"
9875The maximum length of any name,
9876such as a host or a user name.
9877.ip "MAXPV [256]"
9878The maximum number of parameters to any mailer.
9879This limits the number of recipients that may be passed in one transaction.
9880It can be set to any arbitrary number above about 10,
9881since
9882.i sendmail
9883will break up a delivery into smaller batches as needed.
9884A higher number may reduce load on your system, however.
9885.ip "MAXQUEUEGROUPS [50]"
9886The maximum number of queue groups.
9887.ip "MAXATOM [1000]"
9888The maximum number of atoms
9889(tokens)
9890in a single address.
9891For example,
9892the address
9893.q "eric@CS.Berkeley.EDU"
9894is seven atoms.
9895.ip "MAXMAILERS [25]"
9896The maximum number of mailers that may be defined
9897in the configuration file.
9898This value is defined in include/sendmail/sendmail.h.
9899.ip "MAXRWSETS [200]"
9900The maximum number of rewriting sets
9901that may be defined.
9902The first half of these are reserved for numeric specification
9903(e.g., ``S92''),
9904while the upper half are reserved for auto-numbering
9905(e.g., ``Sfoo'').
9906Thus, with a value of 200 an attempt to use ``S99'' will succeed,
9907but ``S100'' will fail.
9908.ip "MAXPRIORITIES [25]"
9909The maximum number of values for the
9910.q Precedence:
9911field that may be defined
9912(using the
9913.b P
9914line in sendmail.cf).
9915.ip "MAXUSERENVIRON [100]"
9916The maximum number of items in the user environment
9917that will be passed to subordinate mailers.
9918.ip "MAXMXHOSTS [100]"
9919The maximum number of MX records we will accept for any single host.
9920.ip "MAXMAPSTACK [12]"
9921The maximum number of maps that may be "stacked" in a
9922.b sequence
9923class map.
9924.ip "MAXMIMEARGS [20]"
9925The maximum number of arguments in a MIME Content-Type: header;
9926additional arguments will be ignored.
9927.ip "MAXMIMENESTING [20]"
9928The maximum depth to which MIME messages may be nested
9929(that is, nested Message or Multipart documents;
9930this does not limit the number of components in a single Multipart document).
9931.ip "MAXDAEMONS [10]"
9932The maximum number of sockets sendmail will open for accepting connections
9933on different ports.
9934.ip "MAXMACNAMELEN [25]"
9935The maximum length of a macro name.
9936.lp
9937A number of other compilation options exist.
9938These specify whether or not specific code should be compiled in.
9939Ones marked with \(dg
9940are 0/1 valued.
9941.nr ii 1.2i
9942.ip NETINET\(dg
9943If set,
9944support for Internet protocol networking is compiled in.
9945Previous versions of
9946.i sendmail
9947referred to this as
9948.sm DAEMON ;
9949this old usage is now incorrect.
9950Defaults on;
9951turn it off in the Makefile
9952if your system doesn't support the Internet protocols.
9953.ip NETINET6\(dg
9954If set,
9955support for IPv6 networking is compiled in.
9956It must be separately enabled by adding
9957.b DaemonPortOptions
9958settings.
9959.ip NETISO\(dg
9960If set,
9961support for ISO protocol networking is compiled in
9962(it may be appropriate to #define this in the Makefile instead of conf.h).
9963.ip NETUNIX\(dg
9964If set,
9965support for UNIX domain sockets is compiled in.
9966This is used for control socket support.
9967.ip LOG
9968If set,
9969the
9970.i syslog
9971routine in use at some sites is used.
9972This makes an informational log record
9973for each message processed,
9974and makes a higher priority log record
9975for internal system errors.
9976.b "STRONGLY RECOMMENDED"
9977\(em if you want no logging, turn it off in the configuration file.
9978.ip MATCHGECOS\(dg
9979Compile in the code to do ``fuzzy matching'' on the GECOS field
9980in /etc/passwd.
9981This also requires that the
9982.b MatchGECOS
9983option be turned on.
9984.ip NAMED_BIND\(dg
9985Compile in code to use the
9986Berkeley Internet Name Domain (BIND) server
9987to resolve TCP/IP host names.
9988.ip NOTUNIX
9989If you are using a non-UNIX mail format,
9990you can set this flag to turn off special processing
9991of UNIX-style
9992.q "From "
9993lines.
9994.ip USERDB\(dg
9995Include the
9996.b experimental
9997Berkeley user information database package.
9998This adds a new level of local name expansion
9999between aliasing and forwarding.
10000It also uses the NEWDB package.
10001This may change in future releases.
10002.lp
10003The following options are normally turned on
10004in per-operating-system clauses in conf.h.
10005.ip IDENTPROTO\(dg
10006Compile in the IDENT protocol as defined in RFC 1413.
10007This defaults on for all systems except Ultrix,
10008which apparently has the interesting
10009.q feature
10010that when it receives a
10011.q "host unreachable"
10012message it closes all open connections to that host.
10013Since some firewall gateways send this error code
10014when you access an unauthorized port (such as 113, used by IDENT),
10015Ultrix cannot receive email from such hosts.
10016.ip SYSTEM5
10017Set all of the compilation parameters appropriate for System V.
10018.ip HASFLOCK\(dg
10019Use Berkeley-style
10020.b flock
10021instead of System V
10022.b lockf
10023to do file locking.
10024Due to the highly unusual semantics of locks
10025across forks in
10026.b lockf ,
10027this should always be used if at all possible.
10028.ip HASINITGROUPS
10029Set this if your system has the
10030.i initgroups()
10031call
10032(if you have multiple group support).
10033This is the default if SYSTEM5 is
10034.i not
10035defined or if you are on HPUX.
10036.ip HASUNAME
10037Set this if you have the
10038.i uname (2)
10039system call (or corresponding library routine).
10040Set by default if
10041SYSTEM5
10042is set.
10043.ip HASGETDTABLESIZE
10044Set this if you have the
10045.i getdtablesize (2)
10046system call.
10047.ip HASWAITPID
10048Set this if you have the
10049.i haswaitpid (2)
10050system call.
10051.ip FAST_PID_RECYCLE
10052Set this if your system can possibly
10053reuse the same pid in the same second of time.
10054.ip SFS_TYPE
10055The mechanism that can be used to get file system capacity information.
10056The values can be one of
10057SFS_USTAT (use the ustat(2) syscall),
10058SFS_4ARGS (use the four argument statfs(2) syscall),
10059SFS_VFS (use the two argument statfs(2) syscall including <sys/vfs.h>),
10060SFS_MOUNT (use the two argument statfs(2) syscall including <sys/mount.h>),
10061SFS_STATFS (use the two argument statfs(2) syscall including <sys/statfs.h>),
10062SFS_STATVFS (use the two argument statfs(2) syscall including <sys/statvfs.h>),
10063or
10064SFS_NONE (no way to get this information).
10065.ip LA_TYPE
10066The load average type.
10067Details are described below.
10068.lp
10069The are several built-in ways of computing the load average.
10070.i Sendmail
10071tries to auto-configure them based on imperfect guesses;
10072you can select one using the
10073.i cc
10074option
10075.b \-DLA_TYPE= \c
10076.i type ,
10077where
10078.i type
10079is:
10080.ip LA_INT
10081The kernel stores the load average in the kernel as an array of long integers.
10082The actual values are scaled by a factor FSCALE
10083(default 256).
10084.ip LA_SHORT
10085The kernel stores the load average in the kernel as an array of short integers.
10086The actual values are scaled by a factor FSCALE
10087(default 256).
10088.ip LA_FLOAT
10089The kernel stores the load average in the kernel as an array of
10090double precision floats.
10091.ip LA_MACH
10092Use MACH-style load averages.
10093.ip LA_SUBR
10094Call the
10095.i getloadavg
10096routine to get the load average as an array of doubles.
10097.ip LA_ZERO
10098Always return zero as the load average.
10099This is the fallback case.
10100.lp
10101If type
10102.sm LA_INT ,
10103.sm LA_SHORT ,
10104or
10105.sm LA_FLOAT
10106is specified,
10107you may also need to specify
10108.sm _PATH_UNIX
10109(the path to your system binary)
10110and
10111.sm LA_AVENRUN
10112(the name of the variable containing the load average in the kernel;
10113usually
10114.q _avenrun
10115or
10116.q avenrun ).
10117.sh 2 "Configuration in sendmail/conf.c"
10118.pp
10119The following changes can be made in conf.c.
10120.sh 3 "Built-in Header Semantics"
10121.pp
10122Not all header semantics are defined in the configuration file.
10123Header lines that should only be included by certain mailers
10124(as well as other more obscure semantics)
10125must be specified in the
10126.i HdrInfo
10127table in
10128.i conf.c .
10129This table contains the header name
10130(which should be in all lower case)
10131and a set of header control flags (described below),
10132The flags are:
10133.ip H_ACHECK
10134Normally when the check is made to see if a header line is compatible
10135with a mailer,
10136.i sendmail
10137will not delete an existing line.
10138If this flag is set,
10139.i sendmail
10140will delete
10141even existing header lines.
10142That is,
10143if this bit is set and the mailer does not have flag bits set
10144that intersect with the required mailer flags
10145in the header definition in
10146sendmail.cf,
10147the header line is
10148.i always
10149deleted.
10150.ip H_EOH
10151If this header field is set,
10152treat it like a blank line,
10153i.e.,
10154it will signal the end of the header
10155and the beginning of the message text.
10156.ip H_FORCE
10157Add this header entry
10158even if one existed in the message before.
10159If a header entry does not have this bit set,
10160.i sendmail
10161will not add another header line if a header line
10162of this name already existed.
10163This would normally be used to stamp the message
10164by everyone who handled it.
10165.ip H_TRACE
10166If set,
10167this is a timestamp
10168(trace)
10169field.
10170If the number of trace fields in a message
10171exceeds a preset amount
10172the message is returned
10173on the assumption that it has an aliasing loop.
10174.ip H_RCPT
10175If set,
10176this field contains recipient addresses.
10177This is used by the
10178.b \-t
10179flag to determine who to send to
10180when it is collecting recipients from the message.
10181.ip H_FROM
10182This flag indicates that this field
10183specifies a sender.
10184The order of these fields in the
10185.i HdrInfo
10186table specifies
10187.i sendmail 's
10188preference
10189for which field to return error messages to.
10190.ip H_ERRORSTO
10191Addresses in this header should receive error messages.
10192.ip H_CTE
10193This header is a Content-Transfer-Encoding header.
10194.ip H_CTYPE
10195This header is a Content-Type header.
10196.ip H_STRIPVAL
10197Strip the value from the header (for Bcc:).
10198.nr ii 5n
10199.lp
10200Let's look at a sample
10201.i HdrInfo
10202specification:
10203.(b
10204.ta 4n +\w'"content-transfer-encoding", 'u
10205struct hdrinfo HdrInfo[] =
10206\&{
10207 /* originator fields, most to least significant */
10208 "resent-sender", H_FROM,
10209 "resent-from", H_FROM,
10210 "sender", H_FROM,
10211 "from", H_FROM,
10212 "full-name", H_ACHECK,
10213 "errors-to", H_FROM\^|\^H_ERRORSTO,
10214 /* destination fields */
10215 "to", H_RCPT,
10216 "resent-to", H_RCPT,
10217 "cc", H_RCPT,
10218 "bcc", H_RCPT\^|\^H_STRIPVAL,
10219 /* message identification and control */
10220 "message", H_EOH,
10221 "text", H_EOH,
10222 /* trace fields */
10223 "received", H_TRACE\^|\^H_FORCE,
10224 /* miscellaneous fields */
10225 "content-transfer-encoding", H_CTE,
10226 "content-type", H_CTYPE,
10227
10228 NULL, 0,
10229};
10230.)b
10231This structure indicates that the
10232.q To: ,
10233.q Resent-To: ,
10234and
10235.q Cc:
10236fields
10237all specify recipient addresses.
10238Any
10239.q Full-Name:
10240field will be deleted unless the required mailer flag
10241(indicated in the configuration file)
10242is specified.
10243The
10244.q Message:
10245and
10246.q Text:
10247fields will terminate the header;
10248these are used by random dissenters around the network world.
10249The
10250.q Received:
10251field will always be added,
10252and can be used to trace messages.
10253.pp
10254There are a number of important points here.
10255First,
10256header fields are not added automatically just because they are in the
10257.i HdrInfo
10258structure;
10259they must be specified in the configuration file
10260in order to be added to the message.
10261Any header fields mentioned in the configuration file but not
10262mentioned in the
10263.i HdrInfo
10264structure have default processing performed;
10265that is,
10266they are added unless they were in the message already.
10267Second,
10268the
10269.i HdrInfo
10270structure only specifies cliched processing;
10271certain headers are processed specially by ad hoc code
10272regardless of the status specified in
10273.i HdrInfo .
10274For example,
10275the
10276.q Sender:
10277and
10278.q From:
10279fields are always scanned on ARPANET mail
10280to determine the sender\**;
10281.(f
10282\**Actually, this is no longer true in SMTP;
10283this information is contained in the envelope.
10284The older ARPANET protocols did not completely distinguish
10285envelope from header.
10286.)f
10287this is used to perform the
10288.q "return to sender"
10289function.
10290The
10291.q "From:"
10292and
10293.q "Full-Name:"
10294fields are used to determine the full name of the sender
10295if possible;
10296this is stored in the macro
10297.b $x
10298and used in a number of ways.
10299.sh 3 "Restricting Use of Email"
10300.pp
10301If it is necessary to restrict mail through a relay,
10302the
10303.i checkcompat
10304routine can be modified.
10305This routine is called for every recipient address.
10306It returns an exit status
10307indicating the status of the message.
10308The status
10309.sm EX_OK
10310accepts the address,
10311.sm EX_TEMPFAIL
10312queues the message for a later try,
10313and other values
10314(commonly
10315.sm EX_UNAVAILABLE )
10316reject the message.
10317It is up to
10318.i checkcompat
10319to print an error message
10320(using
10321.i usrerr )
10322if the message is rejected.
10323For example,
10324.i checkcompat
10325could read:
10326.(b
10327.re
10328.sz -1
10329.ta 4n +4n +4n +4n +4n +4n +4n
10330int
10331checkcompat(to, e)
10332 register ADDRESS *to;
10333 register ENVELOPE *e;
10334\&{
10335 register STAB *s;
10336
10337 s = stab("private", ST_MAILER, ST_FIND);
10338 if (s != NULL && e\->e_from.q_mailer != LocalMailer &&
10339 to->q_mailer == s->s_mailer)
10340 {
10341 usrerr("No private net mail allowed through this machine");
10342 return (EX_UNAVAILABLE);
10343 }
10344 if (MsgSize > 50000 && bitnset(M_LOCALMAILER, to\->q_mailer))
10345 {
10346 usrerr("Message too large for non-local delivery");
10347 e\->e_flags |= EF_NORETURN;
10348 return (EX_UNAVAILABLE);
10349 }
10350 return (EX_OK);
10351}
10352.sz
10353.)b
10354This would reject messages greater than 50000 bytes
10355unless they were local.
10356The
10357.i EF_NORETURN
10358flag can be set in
10359.i e\(->e_flags
10360to suppress the return of the actual body
10361of the message in the error return.
10362The actual use of this routine is highly dependent on the
10363implementation,
10364and use should be limited.
10365.sh 3 "New Database Map Classes"
10366.pp
10367New key maps can be added by creating a class initialization function
10368and a lookup function.
10369These are then added to the routine
10370.i setupmaps.
10371.pp
10372The initialization function is called as
10373.(b
10374\fIxxx\fP_map_init(MAP *map, char *args)
10375.)b
10376The
10377.i map
10378is an internal data structure.
10379The
10380.i args
10381is a pointer to the portion of the configuration file line
10382following the map class name;
10383flags and filenames can be extracted from this line.
10384The initialization function must return
10385.sm true
10386if it successfully opened the map,
10387.sm false
10388otherwise.
10389.pp
10390The lookup function is called as
10391.(b
10392\fIxxx\fP_map_lookup(MAP *map, char buf[], char **av, int *statp)
10393.)b
10394The
10395.i map
10396defines the map internally.
10397The
10398.i buf
10399has the input key.
10400This may be (and often is) used destructively.
10401The
10402.i av
10403is a list of arguments passed in from the rewrite line.
10404The lookup function should return a pointer to the new value.
10405If the map lookup fails,
10406.i *statp
10407should be set to an exit status code;
10408in particular, it should be set to
10409.sm EX_TEMPFAIL
10410if recovery is to be attempted by the higher level code.
10411.sh 3 "Queueing Function"
10412.pp
10413The routine
10414.i shouldqueue
10415is called to decide if a message should be queued
10416or processed immediately.
10417Typically this compares the message priority to the current load average.
10418The default definition is:
10419.(b
10420bool
10421shouldqueue(pri, ctime)
10422 long pri;
10423 time_t ctime;
10424{
10425 if (CurrentLA < QueueLA)
10426 return false;
10427 return (pri > (QueueFactor / (CurrentLA \- QueueLA + 1)));
10428}
10429.)b
10430If the current load average
10431(global variable
10432.i CurrentLA ,
10433which is set before this function is called)
10434is less than the low threshold load average
10435(option
10436.b x ,
10437variable
10438.i QueueLA ),
10439.i shouldqueue
10440returns
10441.sm false
10442immediately
10443(that is, it should
10444.i not
10445queue).
10446If the current load average exceeds the high threshold load average
10447(option
10448.b X ,
10449variable
10450.i RefuseLA ),
10451.i shouldqueue
10452returns
10453.sm true
10454immediately.
10455Otherwise, it computes the function based on the message priority,
10456the queue factor
10457(option
10458.b q ,
10459global variable
10460.i QueueFactor ),
10461and the current and threshold load averages.
10462.pp
10463An implementation wishing to take the actual age of the message into account
10464can also use the
10465.i ctime
10466parameter,
10467which is the time that the message was first submitted to
10468.i sendmail .
10469Note that the
10470.i pri
10471parameter is already weighted
10472by the number of times the message has been tried
10473(although this tends to lower the priority of the message with time);
10474the expectation is that the
10475.i ctime
10476would be used as an
10477.q "escape clause"
10478to ensure that messages are eventually processed.
10479.sh 3 "Refusing Incoming SMTP Connections"
10480.pp
10481The function
10482.i refuseconnections
10483returns
10484.sm true
10485if incoming SMTP connections should be refused.
10486The current implementation is based exclusively on the current load average
10487and the refuse load average option
10488(option
10489.b X ,
10490global variable
10491.i RefuseLA ):
10492.(b
10493bool
10494refuseconnections()
10495{
10496 return (RefuseLA > 0 && CurrentLA >= RefuseLA);
10497}
10498.)b
10499A more clever implementation
10500could look at more system resources.
10501.sh 3 "Load Average Computation"
10502.pp
10503The routine
10504.i getla
10505returns the current load average (as a rounded integer).
10506The distribution includes several possible implementations.
10507If you are porting to a new environment
10508you may need to add some new tweaks.\**
10509.(f
10510\**If you do, please send updates to
10511sendmail@Sendmail.ORG.
10512.)f
10513.sh 2 "Configuration in sendmail/daemon.c"
10514.pp
10515The file
10516.i sendmail/daemon.c
10517contains a number of routines that are dependent
10518on the local networking environment.
10519The version supplied assumes you have BSD style sockets.
10520.pp
10521In previous releases,
10522we recommended that you modify the routine
10523.i maphostname
10524if you wanted to generalize
10525.b $[
10526\&...\&
10527.b $]
10528lookups.
10529We now recommend that you create a new keyed map instead.
10530.sh 2 "LDAP"
10531.pp
10532In this section we assume that
10533.i sendmail
10534has been compiled with support for LDAP.
10535.sh 3 "LDAP Recursion"
10536.pp
10537LDAP Recursion allows you to add types to the search attributes on an
10538LDAP map specification.
10539The syntax is:
10540.ip "\-v \fIATTRIBUTE\fP[:\fITYPE\fP[:\fIOBJECTCLASS\fP[|\fIOBJECTCLASS\fP|...]]]
10541.pp
10542The new \fITYPE\fPs are:
10543.nr ii 1i
10544.ip NORMAL
10545This attribute type specifies the attribute to add to the results string.
10546This is the default.
10547.ip DN
10548Any matches for this attribute are expected to have a value of a
10549fully qualified distinguished name.
10550.i sendmail
10551will lookup that DN and apply the attributes requested to the
10552returned DN record.
10553.ip FILTER
10554Any matches for this attribute are expected to have a value of an
10555LDAP search filter.
10556.i sendmail
10557will perform a lookup with the same parameters as the original
10558search but replaces the search filter with the one specified here.
10559.ip URL
10560Any matches for this attribute are expected to have a value of an LDAP URL.
10561.i sendmail
10562will perform a lookup of that URL and use the results from the attributes
10563named in that URL.
10564Note however that the search is done using the current LDAP connection,
10565regardless of what is specified as the scheme, LDAP host, and LDAP
10566port in the LDAP URL.
10567.lp
10568Any untyped attributes are considered
10569.sm NORMAL
10570attributes as described above.
10571.pp
10572The optional \fIOBJECTCLASS\fP (| separated) list contains the
10573objectClass values for which that attribute applies.
10574If the list is given,
10575the attribute named will only be used if the LDAP record being returned is a
10576member of that object class.
10577Note that if these new value attribute \fITYPE\fPs are used in an
10578AliasFile
10579option setting, it will need to be double quoted to prevent
10580.i sendmail
10581from misparsing the colons.
10582.pp
10583Note that LDAP recursion attributes which do not ultimately point to an
10584LDAP record are not considered an error.
10585.sh 4 "Example"
10586.pp
10587Since examples usually help clarify, here is an example which uses all
10588four of the new types:
10589.(b
10590O LDAPDefaultSpec=-h ldap.example.com -b dc=example,dc=com
10591
10592Kexample ldap
10593 -z,
10594 -k (&(objectClass=sendmailMTAAliasObject)(sendmailMTAKey=%0))
10595 -v sendmailMTAAliasValue,mail:NORMAL:inetOrgPerson,
10596 uniqueMember:DN:groupOfUniqueNames,
10597 sendmailMTAAliasSearch:FILTER:sendmailMTAAliasObject,
10598 sendmailMTAAliasURL:URL:sendmailMTAAliasObject
10599.)b
10600.pp
10601That definition specifies that:
10602.bu
10603Any value in a
10604.sm sendmailMTAAliasValue
10605attribute will be added to the result string regardless of object class.
10606.bu
10607The
10608.sm mail
10609attribute will be added to the result string if
10610the LDAP record is a member of the
10611.sm inetOrgPerson
10612object class.
10613.bu
10614The
10615.sm uniqueMember
10616attribute is a recursive attribute, used only in
10617.sm groupOfUniqueNames
10618records, and should contain an LDAP DN pointing to another LDAP record.
10619The desire here is to return the
10620.sm mail
10621attribute from those DNs.
10622.bu
10623The
10624.sm sendmailMTAAliasSearch
10625attribute and
10626.sm sendmailMTAAliasURL
10627are both used only if referenced in a
10628.sm sendmailMTAAliasObject .
10629They are both recursive, the first for a new LDAP search string and the
10630latter for an LDAP URL.
10631.sh 2 "STARTTLS"
10632.pp
10633In this section we assume that
10634.i sendmail
10635has been compiled with support for STARTTLS.
10636To properly understand the use of STARTTLS in
10637.i sendmail ,
10638it is necessary to understand at least some basics about X.509 certificates
10639and public key cryptography.
10640This information can be found in books about SSL/TLS
10641or on WWW sites, e.g.,
10642.q http://www.OpenSSL.org/ .
10643.sh 3 "Certificates for STARTTLS"
10644.pp
10645When acting as a server,
10646.i sendmail
10647requires X.509 certificates to support STARTTLS:
10648one as certificate for the server (ServerCertFile and corresponding
10649private ServerKeyFile)
10650at least one root CA (CACertFile),
10651i.e., a certificate that is used to sign other certificates,
10652and a path to a directory which contains other CAs (CACertPath).
10653The file specified via
10654CACertFile
10655can contain several certificates of CAs.
10656The DNs of these certificates are sent
10657to the client during the TLS handshake (as part of the
10658CertificateRequest) as the list of acceptable CAs.
10659However, do not list too many root CAs in that file, otherwise
10660the TLS handshake may fail; e.g.,
10661.(b
10662error:14094417:SSL routines:SSL3_READ_BYTES:
10663sslv3 alert illegal parameter:s3_pkt.c:964:SSL alert number 47
10664.)b
10665You should probably put only the CA cert into that file
10666that signed your own cert(s), or at least only those you trust.
10667The CACertPath directory must contain the hashes of each CA certificate
10668as filenames (or as links to them).
10669Symbolic links can be generated with the following
10670two (Bourne) shell commands:
10671.(b
10672C=FileName_of_CA_Certificate
10673ln -s $C `openssl x509 -noout -hash < $C`.0
10674.)b
10675An X.509 certificate is also required for authentication in client mode
10676(ClientCertFile and corresponding private ClientKeyFile), however,
10677.i sendmail
10678will always use STARTTLS when offered by a server.
10679The client and server certificates can be identical.
10680Certificates can be obtained from a certificate authority
10681or created with the help of OpenSSL.
10682The required format for certificates and private keys is PEM.
10683To allow for automatic startup of sendmail, private keys
10684(ServerKeyFile, ClientKeyFile)
10685must be stored unencrypted.
10686The keys are only protected by the permissions of the file system.
10687Never make a private key available to a third party.
10688.sh 3 "PRNG for STARTTLS"
10689.pp
10690STARTTLS requires a strong pseudo random number generator (PRNG)
10691to operate properly.
10692Depending on the TLS library you use, it may be required to explicitly
10693initialize the PRNG with random data.
10694OpenSSL makes use of
10695.b /dev/urandom(4)
10696if available (this corresponds to the compile flag HASURANDOMDEV).
10697On systems which lack this support, a random file must be specified in the
10698.i sendmail.cf
10699file using the option RandFile.
10700It is
10701.b strongly
10702advised to use the "Entropy Gathering Daemon" EGD
10703from Brian Warner on those systems to provide useful random data.
10704In this case,
10705.i sendmail
10706must be compiled with the flag EGD, and the
10707RandFile option must point to the EGD socket.
10708If neither
10709.b /dev/urandom(4)
10710nor EGD are available, you have to make sure
10711that useful random data is available all the time in RandFile.
10712If the file hasn't been modified in the last 10 minutes before
10713it is supposed to be used by
10714.i sendmail
10715the content is considered obsolete.
10716One method for generating this file is:
10717.(b
10718openssl rand -out /etc/mail/randfile -rand \c
10719.i /path/to/file:... \c
10720256
10721.)b
10722See the OpenSSL documentation for more information.
10723In this case, the PRNG for TLS is only
10724seeded with other random data if the
10725.b DontBlameSendmail
10726option
10727.b InsufficientEntropy
10728is set.
10729This is most likely not sufficient for certain actions, e.g.,
10730generation of (temporary) keys.
10731.pp
10732Please see the OpenSSL documentation or other sources
10733for further information about certificates, their creation and their usage,
10734the importance of a good PRNG, and other aspects of TLS.
10735.sh 2 "Encoding of STARTTLS and AUTH related Macros"
10736.pp
10737Macros that contain STARTTLS and AUTH related data which comes from outside
10738sources, e.g., all macros containing information from certificates,
10739are encoded to avoid problems with non-printable or special characters.
10740The latter are '\\', '<', '>', '(', ')', '"', '+', and ' '.
10741All of these characters are replaced by their value in hexadecimal
10742with a leading '+'.
10743For example:
10744.(b
10745/C=US/ST=California/O=endmail.org/OU=private/CN=Darth Mail (Cert)/
10746Email=darth+cert@endmail.org
10747.)b
10748is encoded as:
10749.(b
10750/C=US/ST=California/O=endmail.org/OU=private/
10751CN=Darth+20Mail+20+28Cert+29/Email=darth+2Bcert@endmail.org
10752.)b
10753(line breaks have been inserted for readability).
10754The macros which are subject to this encoding are
10755{cert_subject}, {cert_issuer}, {cn_subject}, {cn_issuer},
10756as well as
10757{auth_authen} and {auth_author}.
10758.sh 1 "ACKNOWLEDGEMENTS"
10759.pp
10760I've worked on
10761.i sendmail
10762for many years,
10763and many employers have been remarkably patient
10764about letting me work on a large project
10765that was not part of my official job.
10766This includes time on the INGRES Project at
10767the University of California at Berkeley,
10768at Britton Lee,
10769and again on the Mammoth and Titan Projects at Berkeley.
10770.pp
10771Much of the second wave of improvements
10772resulting in version 8.1
10773should be credited to Bryan Costales of the
10774International Computer Science Institute.
10775As he passed me drafts of his book on
10776.i sendmail
10777I was inspired to start working on things again.
10778Bryan was also available to bounce ideas off of.
10779.pp
10780Gregory Neil Shapiro
10781of Worcester Polytechnic Institute
10782has become instrumental in all phases of
10783.i sendmail
10784support and development,
10785and was largely responsible for getting versions 8.8 and 8.9
10786out the door.
10787.pp
10788Many, many people contributed chunks of code and ideas to
10789.i sendmail .
10790It has proven to be a group network effort.
10791Version 8 in particular was a group project.
10792The following people and organizations made notable contributions:
10793.(l
10794Claus Assmann
10795John Beck, Hewlett-Packard & Sun Microsystems
10796Keith Bostic, CSRG, University of California, Berkeley
10797Andrew Cheng, Sun Microsystems
10798Michael J. Corrigan, University of California, San Diego
10799Bryan Costales, International Computer Science Institute & InfoBeat
10800Pa\*:r (Pell) Emanuelsson
10801Craig Everhart, Transarc Corporation
10802Per Hedeland, Ericsson
10803Tom Ivar Helbekkmo, Norwegian School of Economics
10804Kari Hurtta, Finnish Meteorological Institute
10805Allan E. Johannesen, WPI
10806Jonathan Kamens, OpenVision Technologies, Inc.
10807Takahiro Kanbe, Fuji Xerox Information Systems Co., Ltd.
10808Brian Kantor, University of California, San Diego
10809John Kennedy, Cal State University, Chico
10810Murray S. Kucherawy, HookUp Communication Corp.
10811Bruce Lilly, Sony U.S.
10812Karl London
10813Motonori Nakamura, Ritsumeikan University & Kyoto University
10814John Gardiner Myers, Carnegie Mellon University
10815Neil Rickert, Northern Illinois University
10816Gregory Neil Shapiro, WPI
10817Eric Schnoebelen, Convex Computer Corp.
10818Eric Wassenaar, National Institute for Nuclear and High Energy Physics, Amsterdam
10819Randall Winchester, University of Maryland
10820Christophe Wolfhugel, Pasteur Institute & Herve Schauer Consultants (Paris)
10821Exactis.com, Inc.
10822.)l
10823I apologize for anyone I have omitted, misspelled, misattributed, or
10824otherwise missed.
10825At this point, I suspect that at least a hundred people
10826have contributed code,
10827and many more have contributed ideas, comments, and encouragement.
10828I've tried to list them in the RELEASE_NOTES in the distribution directory.
10829I appreciate their contribution as well.
10830.pp
10831Special thanks are reserved for Michael Corrigan and Christophe Wolfhugel,
10832who besides being wonderful guinea pigs and contributors
10833have also consented to be added to the ``sendmail@Sendmail.ORG'' list
10834and, by answering the bulk of the questions sent to that list,
10835have freed me up to do other work.
10836.++ A
10837.+c "COMMAND LINE FLAGS"
10838.ba 0
10839.nr ii 1i
10840.pp
10841Arguments must be presented with flags before addresses.
10842The flags are:
10843.ip \-A\fIx\fP
10844Select an alternative .cf file which is either
10845.i sendmail.cf
10846for
10847.b \-Am
10848or
10849.i submit.cf
10850for
10851.b \-Ac .
10852By default the .cf file is chosen based on the operation mode.
10853For
10854.b -bm
10855(default),
10856.b -bs ,
10857and
10858.b -t
10859it is
10860.i submit.cf
10861if it exists, for all others it is
10862.i sendmail.cf .
10863.ip \-b\fIx\fP
10864Set operation mode to
10865.i x .
10866Operation modes are:
10867.(b
10868.ta 4n
10869m Deliver mail (default)
10870s Speak SMTP on input side
10871a\(dg ``Arpanet'' mode (get envelope sender information from header)
10872d Run as a daemon in background
10873D Run as a daemon in foreground
10874t Run in test mode
10875v Just verify addresses, don't collect or deliver
10876i Initialize the alias database
10877p Print the mail queue
10878P Print overview over the mail queue (requires shared memory)
10879h Print the persistent host status database
10880H Purge expired entries from the persistent host status database
10881.)b
10882.(f
10883\(dgDeprecated.
10884.)f
10885.ip \-B\fItype\fP
10886Indicate body type.
10887.ip \-C\fIfile\fP
10888Use a different configuration file.
10889.i Sendmail
10890runs as the invoking user (rather than root)
10891when this flag is specified.
10892.ip "\-D \fIlogfile\fP"
10893Send debugging output to the indicated
10894.i logfile
10895instead of stdout.
10896.ip \-d\fIlevel\fP
10897Set debugging level.
10898.ip "\-f\ \fIaddr\fP"
10899The envelope sender address is set to
10900.i addr .
10901This address may also be used in the From: header
10902if that header is missing during initial submission.
10903The envelope sender address is used as the recipient
10904for delivery status notifications
10905and may also appear in a Return-Path: header.
10906.ip \-F\ \fIname\fP
10907Sets the full name of this user to
10908.i name .
10909.ip \-G
10910When accepting messages via the command line,
10911indicate that they are for relay (gateway) submission.
10912sendmail may complain about syntactically invalid messages,
10913e.g., unqualified host names,
10914rather than fixing them when this flag is set.
10915sendmail will not do any canonicalization in this mode.
10916.ip "\-h\ \fIcnt\fP"
10917Sets the
10918.q "hop count"
10919to
10920.i cnt .
10921This represents the number of times this message has been processed
10922by
10923.i sendmail
10924(to the extent that it is supported by the underlying networks).
10925.i Cnt
10926is incremented during processing,
10927and if it reaches
10928MAXHOP
10929(currently 25)
10930.i sendmail
10931throws away the message with an error.
10932.ip "\-L \fItag\fP"
10933Sets the identifier used for syslog.
10934Note that this identifier is set
10935as early as possible.
10936However,
10937.i sendmail
10938may be used
10939if problems arise
10940before the command line arguments
10941are processed.
10942.ip \-n
10943Don't do aliasing or forwarding.
10944.ip "\-N \fInotifications\fP"
10945Tag all addresses being sent as wanting the indicated
10946.i notifications ,
10947which consists of the word
10948.q NEVER
10949or a comma-separated list of
10950.q SUCCESS ,
10951.q FAILURE ,
10952and
10953.q DELAY
10954for successful delivery,
10955failure,
10956and a message that is stuck in a queue somewhere.
10957The default is
10958.q FAILURE,DELAY .
10959.ip "\-r\ \fIaddr\fP"
10960An obsolete form of
10961.b \-f .
10962.ip \-o\fIx\|value\fP
10963Set option
10964.i x
10965to the specified
10966.i value .
10967These options are described in Section 5.6.
10968.ip \-O\fIoption\fP\fB=\fP\fIvalue\fP
10969Set
10970.i option
10971to the specified
10972.i value
10973(for long form option names).
10974These options are described in Section 5.6.
10975.ip \-M\fIx\|value\fP
10976Set macro
10977.i x
10978to the specified
10979.i value .
10980.ip \-p\fIprotocol\fP
10981Set the sending protocol.
10982Programs are encouraged to set this.
10983The protocol field can be in the form
10984.i protocol \c
10985.b : \c
10986.i host
10987to set both the sending protocol and sending host.
10988For example,
10989.q \-pUUCP:uunet
10990sets the sending protocol to UUCP
10991and the sending host to uunet.
10992(Some existing programs use \-oM to set the r and s macros;
10993this is equivalent to using \-p.)
10994.ip \-q\fItime\fP
10995Try to process the queued up mail.
10996If the time is given,
10997a
10998.i sendmail
10999will start one or more processes to run through the queue(s) at the specified
11000time interval to deliver queued mail; otherwise, it only runs once.
11001Each of these processes acts on a workgroup.
11002These processes are also known as workgroup processes or WGP's for short.
11003Each workgroup is responsible for controlling the processing of one or
11004more queues; workgroups help manage the use of system resources by sendmail.
11005Each workgroup may have one or more children concurrently processing
11006queues depending on the setting of \fIMaxQueueChildren\fP.
11007.ip \-qp\fItime\fP
11008Similar to \-q with a time argument,
11009except that instead of periodically starting WGP's
11010sendmail starts persistent WGP's
11011that alternate between processing queues and sleeping.
11012The sleep time is specified by the time argument; it defaults to 1 second,
11013except that a WGP always sleeps at least 5 seconds if their queues were
11014empty in the previous run.
11015Persistent processes are managed by a queue control process (QCP).
11016The QCP is the parent process of the WGP's.
11017Typically the QCP will be the sendmail daemon (when started with \-bd or \-bD)
11018or a special process (named Queue control) (when started without \-bd or \-bD).
11019If a persistent WGP ceases to be active for some reason
11020another WGP will be started by the QCP for the same workgroup
11021in most cases. When a persistent WGP has core dumped, the debug flag
11022\fIno_persistent_restart\fP is set or the specific persistent WGP has been
11023restarted too many times already then the WGP will not be started again
11024and a message will be logged to this effect.
11025To stop (SIGTERM) or restart (SIGHUP) persistent WGP's the appropriate
11026signal should be sent to the QCP. The QCP will propagate the signal to all of
11027the WGP's and if appropriate restart the persistent WGP's.
11028.ip \-q\fIGname\fP
11029Run the jobs in the queue group
11030.i name
11031once.
11032.ip \-q[!]\fIXstring\fP
11033Run the queue once,
11034limiting the jobs to those matching
11035.i Xstring .
11036The key letter
11037.i X
11038can be
11039.b I
11040to limit based on queue identifier,
11041.b R
11042to limit based on recipient,
11043.b S
11044to limit based on sender,
11045or
11046.b Q
11047to limit based on quarantine reason for quarantined jobs.
11048A particular queued job is accepted if one of the corresponding attributes
11049contains the indicated
11050.i string .
11051The optional ! character negates the condition tested.
11052Multiple
11053.i \-q\fIX\fP
11054flags are permitted,
11055with items with the same key letter
11056.q or'ed
11057together, and items with different key letters
11058.q and'ed
11059together.
11060.ip "\-Q[reason]"
11061Quarantine a normal queue items with the given reason or
11062unquarantine quarantined queue items if no reason is given.
11063This should only be used with some sort of item matching using
11064.b \-q[!]\fIXstring\fP
11065as described above.
11066.ip "\-R ret"
11067What information you want returned if the message bounces;
11068.i ret
11069can be
11070.q HDRS
11071for headers only or
11072.q FULL
11073for headers plus body.
11074This is a request only;
11075the other end is not required to honor the parameter.
11076If
11077.q HDRS
11078is specified local bounces also return only the headers.
11079.ip \-t
11080Read the header for
11081.q To: ,
11082.q Cc: ,
11083and
11084.q Bcc:
11085lines, and send to everyone listed in those lists.
11086The
11087.q Bcc:
11088line will be deleted before sending.
11089Any addresses in the argument vector will be deleted
11090from the send list.
11091.ip "\-V envid"
11092The indicated
11093.i envid
11094is passed with the envelope of the message
11095and returned if the message bounces.
11096.ip "\-X \fIlogfile\fP"
11097Log all traffic in and out of
11098.i sendmail
11099in the indicated
11100.i logfile
11101for debugging mailer problems.
11102This produces a lot of data very quickly and should be used sparingly.
11103.pp
11104There are a number of options that may be specified as
11105primitive flags.
11106These are the e, i, m, and v options.
11107Also,
11108the f option
11109may be specified as the
11110.b \-s
11111flag.
11112The DSN related options
11113.q "\-N" ,
11114.q "\-R" ,
11115and
11116.q "\-V"
11117have no effects on
11118.i sendmail
11119running as daemon.
11120.+c "QUEUE FILE FORMATS"
11121.pp
11122This appendix describes the format of the queue files.
11123These files live in a queue directory.
11124The individual qf, hf, Qf, df, and xf files
11125may be stored in separate
11126.i qf/ ,
11127.i df/ ,
11128and
11129.i xf/
11130subdirectories
11131if they are present in the queue directory.
11132.pp
11133All queue files have the name
11134.i ttYMDhmsNNppppp
11135where
11136.i YMDhmsNNppppp
11137is the
11138.i id
11139for this message
11140and the
11141.i tt
11142is a type.
11143The individual letters in the
11144.i id
11145are:
11146.nr ii 0.5i
11147.ip Y
11148Encoded year
11149.ip M
11150Encoded month
11151.ip D
11152Encoded day
11153.ip h
11154Encoded hour
11155.ip m
11156Encoded minute
11157.ip s
11158Encoded second
11159.ip NN
11160Encoded envelope number
11161.ip ppppp
11162At least five decimal digits of the process ID
11163.pp
11164All files with the same id collectively define one message.
11165Due to the use of memory-buffered files,
11166some of these files may never appear on disk.
11167.pp
11168The types are:
11169.nr ii 0.5i
11170.ip qf
11171The queue control file.
11172This file contains the information necessary to process the job.
11173.ip hf
11174The same as a queue control file, but for a quarantined queue job.
11175.ip df
11176The data file.
11177The message body (excluding the header) is kept in this file.
11178Sometimes the df file is not stored in the same directory as the qf file;
11179in this case,
11180the qf file contains a `d' record which names the queue directory
11181that contains the df file.
11182.ip tf
11183A temporary file.
11184This is an image of the
11185.b qf
11186file when it is being rebuilt.
11187It should be renamed to a
11188.b qf
11189file very quickly.
11190.ip xf
11191A transcript file,
11192existing during the life of a session
11193showing everything that happens
11194during that session.
11195Sometimes the xf file must be generated before a queue group has been selected;
11196in this case,
11197the xf file will be stored in a directory of the default queue group.
11198.ip Qf
11199A ``lost'' queue control file.
11200.i sendmail
11201renames a
11202.b qf
11203file to
11204.b Qf
11205if there is a severe (configuration) problem that cannot be solved without
11206human intervention.
11207Search the logfile for the queue file id to figure out what happened.
11208After you resolved the problem, you can rename the
11209.b Qf
11210file to
11211.b qf
11212and send it again.
11213.pp
11214The queue control file is structured as a series of lines
11215each beginning with a code letter.
11216The lines are as follows:
11217.ip V
11218The version number of the queue file format,
11219used to allow new
11220.i sendmail
11221binaries to read queue files created by older versions.
11222Defaults to version zero.
11223Must be the first line of the file if present.
11224For 8.12 the version number is 6.
11225.ip A
11226The information given by the AUTH= parameter of the
11227.q "MAIL FROM:"
11228command or $f@$j
11229if sendmail has been called directly.
11230.ip H
11231A header definition.
11232There may be any number of these lines.
11233The order is important:
11234they represent the order in the final message.
11235These use the same syntax
11236as header definitions in the configuration file.
11237.ip C
11238The controlling address.
11239The syntax is
11240.q localuser:aliasname .
11241Recipient addresses following this line
11242will be flagged so that deliveries will be run as the
11243.i localuser
11244(a user name from the /etc/passwd file);
11245.i aliasname
11246is the name of the alias that expanded to this address
11247(used for printing messages).
11248.ip q
11249The quarantine reason for quarantined queue items.
11250.ip Q
11251The ``original recipient'',
11252specified by the ORCPT= field in an ESMTP transaction.
11253Used exclusively for Delivery Status Notifications.
11254It applies only to the following `R' line.
11255.ip r
11256The ``final recipient''
11257used for Delivery Status Notifications.
11258It applies only to the following `R' line.
11259.ip R
11260A recipient address.
11261This will normally be completely aliased,
11262but is actually realiased when the job is processed.
11263There will be one line for each recipient.
11264Version 1 qf files
11265also include a leading colon-terminated list of flags,
11266which can be
11267`S' to return a message on successful final delivery,
11268`F' to return a message on failure,
11269`D' to return a message if the message is delayed,
11270`B' to indicate that the body should be returned,
11271`N' to suppress returning the body,
11272and
11273`P' to declare this as a ``primary'' (command line or SMTP-session) address.
11274.ip S
11275The sender address.
11276There may only be one of these lines.
11277.ip T
11278The job creation time.
11279This is used to compute when to time out the job.
11280.ip P
11281The current message priority.
11282This is used to order the queue.
11283Higher numbers mean lower priorities.
11284The priority changes
11285as the message sits in the queue.
11286The initial priority depends on the message class
11287and the size of the message.
11288.ip M
11289A message.
11290This line is printed by the
11291.i mailq
11292command,
11293and is generally used to store status information.
11294It can contain any text.
11295.ip F
11296Flag bits, represented as one letter per flag.
11297Defined flag bits are
11298.b r
11299indicating that this is a response message
11300and
11301.b w
11302indicating that a warning message has been sent
11303announcing that the mail has been delayed.
11304Other flag bits are:
11305.b 8 :
11306the body contains 8bit data,
11307.b b :
11308a Bcc: header should be removed,
11309.b d :
11310the mail has RET parameters (see RFC 1894),
11311.b n :
11312the body of the message should not be returned
11313in case of an error,
11314.b s :
11315the envelope has been split.
11316.ip N
11317The total number of delivery attempts.
11318.ip K
11319The time (as seconds since January 1, 1970)
11320of the last delivery attempt.
11321.ip d
11322If the df file is in a different directory than the qf file,
11323then a `d' record is present,
11324specifying the directory in which the df file resides.
11325.ip I
11326The i-number of the data file;
11327this can be used to recover your mail queue
11328after a disastrous disk crash.
11329.ip $
11330A macro definition.
11331The values of certain macros
11332are passed through to the queue run phase.
11333.ip B
11334The body type.
11335The remainder of the line is a text string defining the body type.
11336If this field is missing,
11337the body type is assumed to be
11338.q "undefined"
11339and no special processing is attempted.
11340Legal values are
11341.q 7BIT
11342and
11343.q 8BITMIME .
11344.ip Z
11345The original envelope id (from the ESMTP transaction).
11346For Deliver Status Notifications only.
11347.pp
11348As an example,
11349the following is a queue file sent to
11350.q eric@mammoth.Berkeley.EDU
11351and
11352.q bostic@okeeffe.CS.Berkeley.EDU \**:
11353.(f
11354\**This example is contrived and probably inaccurate for your environment.
11355Glance over it to get an idea;
11356nothing can replace looking at what your own system generates.
11357.)f
11358.(b
11359V4
11360T711358135
11361K904446490
11362N0
11363P2100941
11364$_eric@localhost
11365${daemon_flags}
11366Seric
11367Ceric:100:1000:sendmail@vangogh.CS.Berkeley.EDU
11368RPFD:eric@mammoth.Berkeley.EDU
11369RPFD:bostic@okeeffe.CS.Berkeley.EDU
11370H?P?Return-path: <^g>
11371H??Received: by vangogh.CS.Berkeley.EDU (5.108/2.7) id AAA06703;
11372 Fri, 17 Jul 1992 00:28:55 -0700
11373H??Received: from mail.CS.Berkeley.EDU by vangogh.CS.Berkeley.EDU (5.108/2.7)
11374 id AAA06698; Fri, 17 Jul 1992 00:28:54 -0700
11375H??Received: from [128.32.31.21] by mail.CS.Berkeley.EDU (5.96/2.5)
11376 id AA22777; Fri, 17 Jul 1992 03:29:14 -0400
11377H??Received: by foo.bar.baz.de (5.57/Ultrix3.0-C)
11378 id AA22757; Fri, 17 Jul 1992 09:31:25 GMT
11379H?F?From: eric@foo.bar.baz.de (Eric Allman)
11380H?x?Full-name: Eric Allman
11381H??Message-id: <9207170931.AA22757@foo.bar.baz.de>
11382H??To: sendmail@vangogh.CS.Berkeley.EDU
11383H??Subject: this is an example message
11384.)b
11385This shows
11386the person who sent the message,
11387the submission time
11388(in seconds since January 1, 1970),
11389the message priority,
11390the message class,
11391the recipients,
11392and the headers for the message.
11393.+c "SUMMARY OF SUPPORT FILES"
11394.pp
11395This is a summary of the support files
11396that
11397.i sendmail
11398creates or generates.
11399Many of these can be changed by editing the sendmail.cf file;
11400check there to find the actual pathnames.
11401.nr ii 1i
11402.ip "/usr/\*(SD/sendmail"
11403The binary of
11404.i sendmail .
11405.ip /usr/\*(SB/newaliases
11406A link to /usr/\*(SD/sendmail;
11407causes the alias database to be rebuilt.
11408Running this program is completely equivalent to giving
11409.i sendmail
11410the
11411.b \-bi
11412flag.
11413.ip /usr/\*(SB/mailq
11414Prints a listing of the mail queue.
11415This program is equivalent to using the
11416.b \-bp
11417flag to
11418.i sendmail .
11419.ip /etc/mail/sendmail.cf
11420The configuration file,
11421in textual form.
11422.ip /etc/mail/helpfile
11423The SMTP help file.
11424.ip /etc/mail/statistics
11425A statistics file; need not be present.
11426.ip /etc/mail/sendmail.pid
11427Created in daemon mode;
11428it contains the process id of the current SMTP daemon.
11429If you use this in scripts;
11430use ``head \-1'' to get just the first line;
11431the second line contains the command line used to invoke the daemon,
11432and later versions of
11433.i sendmail
11434may add more information to subsequent lines.
11435.ip /etc/mail/aliases
11436The textual version of the alias file.
11437.ip /etc/mail/aliases.db
11438The alias file in
11439.i hash \|(3)
11440format.
11441.ip /etc/mail/aliases.{pag,dir}
11442The alias file in
11443.i ndbm \|(3)
11444format.
11445.ip /var/spool/mqueue
11446The directory in which the mail queue(s)
11447and temporary files reside.
11448.ip /var/spool/mqueue/qf*
11449Control (queue) files for messages.
11450.ip /var/spool/mqueue/df*
11451Data files.
11452.ip /var/spool/mqueue/tf*
11453Temporary versions of the qf files,
11454used during queue file rebuild.
11455.ip /var/spool/mqueue/xf*
11456A transcript of the current session.
11457.if o \
11458\{\
11459. bp
11460. rs
11461. sp |4i
11462. ce 2
11463This page intentionally left blank;
11464replace it with a blank sheet for double-sided output.
11465.\}
11466.\".ro
11467.\".ls 1
11468.\".tp
11469.\".sp 2i
11470.\".in 0
11471.\".ce 100
11472.\".sz 24
11473.\".b SENDMAIL
11474.\".sz 14
11475.\".sp
11476.\"INSTALLATION AND OPERATION GUIDE
11477.\".sp
11478.\".sz 10
11479.\"Eric Allman
11480.\".sp
|
11474.\"Version $Revision: 8.749 $
| 11481.\"Version $Revision: 8.751 $
|
11475.\".ce 0
11476.bp 3
11477.ce
11478.sz 12
11479TABLE OF CONTENTS
11480.sz 10
11481.sp
11482.\" remove some things to avoid "out of temp file space" problem
11483.rm sh
11484.rm (x
11485.rm )x
11486.rm ip
11487.rm pp
11488.rm lp
11489.rm he
11490.rm fo
11491.rm eh
11492.rm oh
11493.rm ef
11494.rm of
11495.xp
11496.if o \
11497\{\
11498. bp
11499. rs
11500. sp |4i
11501. ce 2
11502This page intentionally left blank;
11503replace it with a blank sheet for double-sided output.
11504.\}
| 11482.\".ce 0
11483.bp 3
11484.ce
11485.sz 12
11486TABLE OF CONTENTS
11487.sz 10
11488.sp
11489.\" remove some things to avoid "out of temp file space" problem
11490.rm sh
11491.rm (x
11492.rm )x
11493.rm ip
11494.rm pp
11495.rm lp
11496.rm he
11497.rm fo
11498.rm eh
11499.rm oh
11500.rm ef
11501.rm of
11502.xp
11503.if o \
11504\{\
11505. bp
11506. rs
11507. sp |4i
11508. ce 2
11509This page intentionally left blank;
11510replace it with a blank sheet for double-sided output.
11511.\}
|