1.\" Copyright (c) 1998-2002 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-2002 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.609.2.2 2002/06/25 20:30:35 ca Exp $
| 12.\" $Id: op.me,v 8.609.2.5 2002/08/04 19:12:07 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.ie !c \(dg \{\
24.char \(dg *
25.de DG
26an asterick
27..
28.\}
29.el \{\
30.de DG
31a dagger
32..
33.\}
34.\"
35.\" Define \(dd as "#" for text output and create a new .DD macro
36.\" which describes the symbol.
37.\"
38.ie !c \(dd \{\
39.char \(dd #
40.de DD
41a pound sign
42..
43.\}
44.el \{\
45.de DD
46a double dagger
47..
48.\}
49.eh 'SMM:08-%''Sendmail Installation and Operation Guide'
50.oh 'Sendmail Installation and Operation Guide''SMM:08-%'
51.\" SD is lib if sendmail is installed in /usr/lib, sbin if in /usr/sbin
52.ds SD sbin
53.\" SB is bin if newaliases/mailq are installed in /usr/bin, ucb if in /usr/ucb
54.ds SB bin
55.nr si 3n
56.de $0
57.(x
58.in \\$3u*3n
59.ti -3n
60\\$2. \\$1
61.)x
62..
63.de $C
64.(x
65.in 0
66\\$1 \\$2. \\$3
67.)x
68..
69.+c
70.(l C
71.sz 16
72.b SENDMAIL\u\s-6TM\s0\d
73.sz 12
74.sp
75.b "INSTALLATION AND OPERATION GUIDE"
76.(f
77.b DISCLAIMER:
78This documentation is under modification.
79.)f
80.sz 10
81.sp
82.r
83Eric Allman
84Gregory Neil Shapiro
85Claus Assmann
86Sendmail, Inc.
87.sp
88.de Ve
89Version \\$2
90..
| 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.ie !c \(dg \{\
24.char \(dg *
25.de DG
26an asterick
27..
28.\}
29.el \{\
30.de DG
31a dagger
32..
33.\}
34.\"
35.\" Define \(dd as "#" for text output and create a new .DD macro
36.\" which describes the symbol.
37.\"
38.ie !c \(dd \{\
39.char \(dd #
40.de DD
41a pound sign
42..
43.\}
44.el \{\
45.de DD
46a double dagger
47..
48.\}
49.eh 'SMM:08-%''Sendmail Installation and Operation Guide'
50.oh 'Sendmail Installation and Operation Guide''SMM:08-%'
51.\" SD is lib if sendmail is installed in /usr/lib, sbin if in /usr/sbin
52.ds SD sbin
53.\" SB is bin if newaliases/mailq are installed in /usr/bin, ucb if in /usr/ucb
54.ds SB bin
55.nr si 3n
56.de $0
57.(x
58.in \\$3u*3n
59.ti -3n
60\\$2. \\$1
61.)x
62..
63.de $C
64.(x
65.in 0
66\\$1 \\$2. \\$3
67.)x
68..
69.+c
70.(l C
71.sz 16
72.b SENDMAIL\u\s-6TM\s0\d
73.sz 12
74.sp
75.b "INSTALLATION AND OPERATION GUIDE"
76.(f
77.b DISCLAIMER:
78This documentation is under modification.
79.)f
80.sz 10
81.sp
82.r
83Eric Allman
84Gregory Neil Shapiro
85Claus Assmann
86Sendmail, Inc.
87.sp
88.de Ve
89Version \\$2
90..
|
91.Ve $Revision: 8.609.2.2 $
| 91.Ve $Revision: 8.609.2.5 $
|
92.rm Ve
93.sp
94For Sendmail Version 8.12
95.)l
96.(f
97Sendmail is a trademark of Sendmail, Inc.
98.)f
99.sp 2
100.pp
101.i Sendmail \u\s-2TM\s0\d
102implements a general purpose internetwork mail routing facility
103under the UNIX\(rg
104operating system.
105It is not tied to any one transport protocol \*-
106its function may be likened to a crossbar switch,
107relaying messages from one domain into another.
108In the process,
109it can do a limited amount of message header editing
110to put the message into a format that is appropriate
111for the receiving domain.
112All of this is done under the control of a configuration file.
113.pp
114Due to the requirements of flexibility
115for
116.i sendmail ,
117the configuration file can seem somewhat unapproachable.
118However, there are only a few basic configurations
119for most sites,
120for which standard configuration files have been supplied.
121Most other configurations
122can be built by adjusting an existing configuration file
123incrementally.
124.pp
125.i Sendmail
126is based on
127RFC 821 (Simple Mail Transport Protocol),
128RFC 822 (Internet Mail Headers Format),
129RFC 974 (MX routing),
130RFC 1123 (Internet Host Requirements),
131RFC 1413 (Identification server),
132RFC 1652 (SMTP 8BITMIME Extension),
133RFC 1869 (SMTP Service Extensions),
134RFC 1870 (SMTP SIZE Extension),
135RFC 1891 (SMTP Delivery Status Notifications),
136RFC 1892 (Multipart/Report),
137RFC 1893 (Enhanced Mail System Status Codes),
138RFC 1894 (Delivery Status Notifications),
139RFC 1985 (SMTP Service Extension for Remote Message Queue Starting),
140RFC 2033 (Local Message Transmission Protocol),
141RFC 2034 (SMTP Service Extension for Returning Enhanced Error Codes),
142RFC 2045 (MIME),
143RFC 2476 (Message Submission),
144RFC 2487 (SMTP Service Extension for Secure SMTP over TLS),
145RFC 2554 (SMTP Service Extension for Authentication),
146RFC 2821 (Simple Mail Transfer Protocol),
147RFC 2822 (Internet Message Format),
148RFC 2852 (Deliver By SMTP Service Extension),
149and
150RFC 2920 (SMTP Service Extension for Command Pipelining).
151However, since
152.i sendmail
153is designed to work in a wider world,
154in many cases it can be configured to exceed these protocols.
155These cases are described herein.
156.pp
157Although
158.i sendmail
159is intended to run
160without the need for monitoring,
161it has a number of features
162that may be used to monitor or adjust the operation
163under unusual circumstances.
164These features are described.
165.pp
166Section one describes how to do a basic
167.i sendmail
168installation.
169Section two
170explains the day-to-day information you should know
171to maintain your mail system.
172If you have a relatively normal site,
173these two sections should contain sufficient information
174for you to install
175.i sendmail
176and keep it happy.
177Section three
178has information regarding the command line arguments.
179Section four
180describes some parameters that may be safely tweaked.
181Section five
182contains the nitty-gritty information about the configuration
183file.
184This section is for masochists
185and people who must write their own configuration file.
186Section six
187describes configuration that can be done at compile time.
188The appendixes give a brief
189but detailed explanation of a number of features
190not described in the rest of the paper.
191.bp 7
192.sh 1 "BASIC INSTALLATION"
193.pp
194There are two basic steps to installing
195.i sendmail .
196First, you have to compile and install the binary.
197If
198.i sendmail
199has already been ported to your operating system
200that should be simple.
201Second, you must build a run-time configuration file.
202This is a file that
203.i sendmail
204reads when it starts up
205that describes the mailers it knows about,
206how to parse addresses,
207how to rewrite the message header,
208and the settings of various options.
209Although the configuration file can be quite complex,
210a configuration can usually be built
211using an M4-based configuration language.
212Assuming you have the standard
213.i sendmail
214distribution, see
215.i cf/README
216for further information.
217.pp
218The remainder of this section will describe the installation of
219.i sendmail
220assuming you can use one of the existing configurations
221and that the standard installation parameters are acceptable.
222All pathnames and examples
223are given from the root of the
224.i sendmail
225subtree,
226normally
227.i /usr/src/usr.\*(SD/sendmail
228on 4.4BSD-based systems.
229.pp
230Continue with the next section if you need/want to compile
231.i sendmail
232yourself.
233If you have a running binary already on your system,
234you should probably skip to section 1.2.
235.sh 2 "Compiling Sendmail"
236.pp
237All
238.i sendmail
239source is in the
240.i sendmail
241subdirectory.
242To compile sendmail,
243.q cd
244into the
245.i sendmail
246directory and type
247.(b
248\&./Build
249.)b
250This will leave the binary in an appropriately named subdirectory,
251e.g.,
252obj.BSD-OS.2.1.i386.
253It works for multiple object versions
254compiled out of the same directory.
255.sh 3 "Tweaking the Build Invocation"
256.pp
257You can give parameters on the
258.i Build
259command.
260In most cases these are only used when the
261.i obj.*
262directory is first created.
263To restart from scratch, use
264.i -c .
265These commands include:
266.nr ii 0.5i
267.ip "\-L \fIlibdirs\fP"
268A list of directories to search for libraries.
269.ip "\-I \fIincdirs\fP"
270A list of directories to search for include files.
271.ip "\-E \fIenvar\fP=\fIvalue\fP"
272Set an environment variable to an indicated
273.i value
274before compiling.
275.ip "\-c"
276Create a new
277.i obj.*
278tree before running.
279.ip "\-f \fIsiteconfig\fP"
280Read the indicated site configuration file.
281If this parameter is not specified,
282.i Build
283includes
284.i all
285of the files
286.i $BUILDTOOLS/Site/site.$oscf.m4
287and
288.i $BUILDTOOLS/Site/site.config.m4 ,
289where $BUILDTOOLS is normally
290.i \&../devtools
291and $oscf is the same name as used on the
292.i obj.*
293directory.
294See below for a description of the site configuration file.
295.ip "\-S"
296Skip auto-configuration.
297.i Build
298will avoid auto-detecting libraries if this is set.
299All libraries and map definitions must be specified
300in the site configuration file.
301.lp
302Most other parameters are passed to the
303.i make
304program; for details see
305.i $BUILDTOOLS/README .
306.sh 3 "Creating a Site Configuration File"
307.\"XXX
308.pp
309(This section is not yet complete.
310For now, see the file devtools/README for details.)
311See sendmail/README for various compilation flags that can be set.
312.sh 3 "Tweaking the Makefile"
313.pp
314.\" .b "XXX This should all be in the Site Configuration File section."
315.i Sendmail
316supports two different formats
317for the local (on disk) version of databases,
318notably the
319.i aliases
320database.
321At least one of these should be defined if at all possible.
322.nr ii 1i
323.ip NDBM
324The ``new DBM'' format,
325available on nearly all systems around today.
326This was the preferred format prior to 4.4BSD.
327It allows such complex things as multiple databases
328and closing a currently open database.
329.ip NEWDB
330The Berkeley DB package.
331If you have this, use it.
332It allows
333long records,
334multiple open databases,
335real in-memory caching,
336and so forth.
337You can define this in conjunction with
338.sm NDBM ;
339if you do,
340old alias databases are read,
341but when a new database is created it will be in NEWDB format.
342As a nasty hack,
343if you have NEWDB, NDBM, and NIS defined,
344and if the alias file name includes the substring
345.q /yp/ ,
346.i sendmail
347will create both new and old versions of the alias file
348during a
349.i newalias
350command.
351This is required because the Sun NIS/YP system
352reads the DBM version of the alias file.
353It's ugly as sin,
354but it works.
355.lp
356If neither of these are defined,
357.i sendmail
358reads the alias file into memory on every invocation.
359This can be slow and should be avoided.
360There are also several methods for remote database access:
361.ip LDAP
362Lightweight Directory Access Protocol.
363.ip NIS
364Sun's Network Information Services (formerly YP).
365.ip NISPLUS
366Sun's NIS+ services.
367.ip NETINFO
368NeXT's NetInfo service.
369.ip HESIOD
370Hesiod service (from Athena).
371.lp
372Other compilation flags are set in
373.i conf.h
374and should be predefined for you
375unless you are porting to a new environment.
376For more options see
377.i sendmail/README .
378.sh 3 "Compilation and installation"
379.pp
380After making the local system configuration described above,
381You should be able to compile and install the system.
382The script
383.q Build
384is the best approach on most systems:
385.(b
386\&./Build
387.)b
388This will use
389.i uname (1)
390to create a custom Makefile for your environment.
391.pp
392If you are installing in the standard places,
393you should be able to install using
394.(b
395\&./Build install
396.)b
397This should install the binary in
398/usr/\*(SD
399and create links from
400/usr/\*(SB/newaliases
401and
402/usr/\*(SB/mailq
403to
404/usr/\*(SD/sendmail.
405On most systems it will also format and install man pages.
406Notice: as of version 8.12
407.i sendmail
408will no longer be installed set-user-ID root by default.
409If you really want to use the old method, you can specify it as target:
410.(b
411\&./Build install-set-user-id
412.)b
413.sh 2 "Configuration Files"
414.pp
415.i Sendmail
416cannot operate without a configuration file.
417The configuration defines the mail delivery mechanisms understood at this site,
418how to access them,
419how to forward email to remote mail systems,
420and a number of tuning parameters.
421This configuration file is detailed
422in the later portion of this document.
423.pp
424The
425.i sendmail
426configuration can be daunting at first.
427The world is complex,
428and the mail configuration reflects that.
429The distribution includes an m4-based configuration package
430that hides a lot of the complexity.
431See
432.i cf/README
433for details.
434.pp
435Our configuration files are processed by
436.i m4
437to facilitate local customization;
438the directory
439.i cf
440of the
441.i sendmail
442distribution directory
443contains the source files.
444This directory contains several subdirectories:
445.nr ii 1i
446.ip cf
447Both site-dependent and site-independent descriptions of hosts.
448These can be literal host names
449(e.g.,
450.q ucbvax.mc )
451when the hosts are gateways
452or more general descriptions
453(such as
454.q "generic-solaris2.mc"
455as a general description of an SMTP-connected host
456running Solaris 2.x.
457Files ending
458.b \&.mc
459(``M4 Configuration'')
460are the input descriptions;
461the output is in the corresponding
462.b \&.cf
463file.
464The general structure of these files is described below.
465.ip domain
466Site-dependent subdomain descriptions.
467These are tied to the way your organization wants to do addressing.
468For example,
469.b domain/CS.Berkeley.EDU.m4
470is our description for hosts in the CS.Berkeley.EDU subdomain.
471These are referenced using the
472.sm DOMAIN
473.b m4
474macro in the
475.b \&.mc
476file.
477.ip feature
478Definitions of specific features that some particular host in your site
479might want.
480These are referenced using the
481.sm FEATURE
482.b m4
483macro.
484An example feature is
485use_cw_file
486(which tells
487.i sendmail
488to read an /etc/mail/local-host-names file on startup
489to find the set of local names).
490.ip hack
491Local hacks, referenced using the
492.sm HACK
493.b m4
494macro.
495Try to avoid these.
496The point of having them here is to make it clear that they smell.
497.ip m4
498Site-independent
499.i m4 (1)
500include files that have information common to all configuration files.
501This can be thought of as a
502.q #include
503directory.
504.ip mailer
505Definitions of mailers,
506referenced using the
507.sm MAILER
508.b m4
509macro.
510The mailer types that are known in this distribution are
511fax,
512local,
513smtp,
514uucp,
515and usenet.
516For example, to include support for the UUCP-based mailers,
517use
518.q MAILER(uucp) .
519.ip ostype
520Definitions describing various operating system environments
521(such as the location of support files).
522These are referenced using the
523.sm OSTYPE
524.b m4
525macro.
526.ip sh
527Shell files used by the
528.b m4
529build process.
530You shouldn't have to mess with these.
531.ip siteconfig
532Local UUCP connectivity information.
533This directory has been supplanted by the mailertable feature;
534any new configurations should use that feature to do UUCP
535(and other) routing.
536The use of this directory is deprecated.
537.pp
538If you are in a new domain
539(e.g., a company),
540you will probably want to create a
541cf/domain
542file for your domain.
543This consists primarily of relay definitions
544and features you want enabled site-wide:
545for example, Berkeley's domain definition
546defines relays for
547BitNET
548and UUCP.
549These are specific to Berkeley,
550and should be fully-qualified internet-style domain names.
551Please check to make certain they are reasonable for your domain.
552.pp
553Subdomains at Berkeley are also represented in the
554cf/domain
555directory.
556For example,
557the domain
558CS.Berkeley.EDU
559is the Computer Science subdomain,
560EECS.Berkeley.EDU
561is the Electrical Engineering and Computer Sciences subdomain,
562and
563S2K.Berkeley.EDU
564is the Sequoia 2000 subdomain.
565You will probably have to add an entry to this directory
566to be appropriate for your domain.
567.pp
568You will have to use or create
569.b \&.mc
570files in the
571.i cf/cf
572subdirectory for your hosts.
573This is detailed in the
574cf/README
575file.
576.sh 2 "Details of Installation Files"
577.pp
578This subsection describes the files that
579comprise the
580.i sendmail
581installation.
582.sh 3 "/usr/\*(SD/sendmail"
583.pp
584The binary for
585.i sendmail
586is located in /usr/\*(SD\**.
587.(f
588\**This is usually
589/usr/sbin
590on 4.4BSD and newer systems;
591many systems install it in
592/usr/lib.
593I understand it is in /usr/ucblib
594on System V Release 4.
595.)f
596It should be set-group-ID smmsp as described in
597sendmail/SECURITY.
598For security reasons,
599/, /usr, and /usr/\*(SD
600should be owned by root, mode 0755\**.
601.(f
602\**Some vendors ship them owned by bin;
603this creates a security hole that is not actually related to
604.i sendmail .
605Other important directories that should have restrictive ownerships
606and permissions are
607/bin, /usr/bin, /etc, /etc/mail, /usr/etc, /lib, and /usr/lib.
608.)f
609.sh 3 "/etc/mail/sendmail.cf"
610.pp
611This is the main configuration file for
612.i sendmail \**.
613.(f
614\**Actually, the pathname varies depending on the operating system;
615/etc/mail is the preferred directory.
616Some older systems install it in
617.b /usr/lib/sendmail.cf ,
618and I've also seen it in
619.b /usr/ucblib .
620If you want to move this file,
621add -D_PATH_SENDMAILCF=\e"/file/name\e"
622to the flags passed to the C compiler.
623Moving this file is not recommended:
624other programs and scripts know of this location.
625.)f
626This is one of the two non-library file names compiled into
627.i sendmail \**,
628the other is /etc/mail/submit.cf.
629.(f
630\**The system libraries can reference other files;
631in particular, system library subroutines that
632.i sendmail
633calls probably reference
634.i /etc/passwd
635and
636.i /etc/resolv.conf .
637.)f
638.pp
639The configuration file is normally created
640using the distribution files described above.
641If you have a particularly unusual system configuration
642you may need to create a special version.
643The format of this file is detailed in later sections
644of this document.
645.sh 3 "/etc/mail/submit.cf"
646.pp
647This is the configuration file for
648.i sendmail
649when it is used for initial mail submission, in which case
650it is also called ``Mail Submission Program'' (MSP)
651in contrast to ``Mail Transfer Agent'' (MTA).
652Starting with version 8.12,
653.i sendmail
654uses one of two different configuration files based on its operation mode
655(or the new
656.b \-A
657option).
658For initial mail submission, i.e., if one of the options
659.b \-bm
660(default),
661.b \-bs ,
662or
663.b \-t
664is specified, submit.cf is used (if available),
665for other operations sendmail.cf is used.
666Details can be found in
667.i sendmail/SECURITY .
668submit.cf is shipped with sendmail (in cf/cf/) and is installed by default.
669If changes to the configuration need to be made, start with
670cf/cf/submit.mc and follow the instruction in cf/README.
671.sh 3 "/usr/\*(SB/newaliases"
672.pp
673The
674.i newaliases
675command should just be a link to
676.i sendmail :
677.(b
678rm \-f /usr/\*(SB/newaliases
679ln \-s /usr/\*(SD/sendmail /usr/\*(SB/newaliases
680.)b
681This can be installed in whatever search path you prefer
682for your system.
683.sh 3 "/usr/\*(SB/hoststat"
684.pp
685The
686.i hoststat
687command should just be a link to
688.i sendmail ,
689in a fashion similar to
690.i newaliases .
691This command lists the status of the last mail transaction
692with all remote hosts. The
693.b \-v
694flag will prevent the status display from being truncated.
695It functions only when the
696.b HostStatusDirectory
697option is set.
698.sh 3 "/usr/\*(SB/purgestat"
699.pp
700This command is also a link to
701.i sendmail .
702It flushes expired (Timeout.hoststatus) information that is stored in the
703.b HostStatusDirectory
704tree.
705.sh 3 "/var/spool/mqueue"
706.pp
707The directory
708.i /var/spool/mqueue
709should be created to hold the mail queue.
710This directory should be mode 0700
711and owned by root.
712.pp
713The actual path of this directory
714is defined by the
715.b QueueDirectory
716option of the
717.i sendmail.cf
718file.
719To use multiple queues,
720supply a value ending with an asterisk.
721For example,
722.i /var/spool/mqueue/qd*
723will use all of the directories or symbolic links to directories
724beginning with `qd' in
725.i /var/spool/mqueue
726as queue directories.
727Do not change the queue directory structure
728while sendmail is running.
729.pp
730If these directories have subdirectories or symbolic links to directories
731named `qf', `df', and `xf', then these will be used for the different
732queue file types.
733That is, the data files are stored in the `df' subdirectory,
734the transcript files are stored in the `xf' subdirectory, and
735all others are stored in the `qf' subdirectory.
736.pp
737If shared memory support is compiled in,
738.i sendmail
739stores the available diskspace in a shared memory segment
740to make the values readily available to all children without
741incurring system overhead.
742In this case, only the daemon updates the data;
743i.e., the sendmail daemon creates the shared memory segment
744and deletes it if it is terminated.
745To use this,
746.i sendmail
747must have been compiled with support for shared memory
748(-DSM_CONF_SHM)
749and the option
750.b SharedMemoryKey
751must be set.
752Notice: do not use the same key for
753.i sendmail
754invocations with different queue directories
755or different queue group declarations.
756Access to shared memory is not controlled by locks,
757i.e., there is a race condition when data in the shared memory is updated.
758However, since operation of
759.i sendmail
760does not rely on the data in the shared memory, this does not negatively
761influence the behavior.
762.sh 3 "/var/spool/clientmqueue"
763.pp
764The directory
765.i /var/spool/clientmqueue
766should be created to hold the mail queue.
767This directory should be mode 0770
768and owned by user smmsp, group smmsp.
769.pp
770The actual path of this directory
771is defined by the
772.b QueueDirectory
773option of the
774.i submit.cf
775file.
776.sh 3 "/var/spool/mqueue/.hoststat"
777.pp
778This is a typical value for the
779.b HostStatusDirectory
780option,
781containing one file per host
782that this sendmail has chatted with recently.
783It is normally a subdirectory of
784.i mqueue .
785.sh 3 "/etc/mail/aliases*"
786.pp
787The system aliases are held in
788.q /etc/mail/aliases .
789A sample is given in
790.q sendmail/aliases
791which includes some aliases which
792.i must
793be defined:
794.(b
795cp sendmail/aliases /etc/mail/aliases
796.i "edit /etc/mail/aliases"
797.)b
798You should extend this file with any aliases that are apropos to your system.
799.pp
800Normally
801.i sendmail
802looks at a database version of the files,
803stored either in
804.q /etc/mail/aliases.dir
805and
806.q /etc/mail/aliases.pag
807or
808.q /etc/mail/aliases.db
809depending on which database package you are using.
810The actual path of this file
811is defined in the
812.b AliasFile
813option of the
814.i sendmail.cf
815file.
816.pp
817The permissions of the alias file and the database versions
818should be 0640 to prevent local denial of service attacks
819as explained in the top level
820.b README
821in the sendmail distribution.
822If the permissions 0640 are used, be sure that only trusted users belong
823to the group assigned to those files. Otherwise, files should not even
824be group readable.
825.sh 3 "/etc/rc or /etc/init.d/sendmail"
826.pp
827It will be necessary to start up the
828.i sendmail
829daemon when your system reboots.
830This daemon performs two functions:
831it listens on the SMTP socket for connections
832(to receive mail from a remote system)
833and it processes the queue periodically
834to insure that mail gets delivered when hosts come up.
835.pp
836If necessary, add the following lines to
837.q /etc/rc
838(or
839.q /etc/rc.local
840as appropriate)
841in the area where it is starting up the daemons
842on a BSD-base system,
843or on a System-V-based system
844in one of the startup files, typically
845.q /etc/init.d/sendmail :
846.(b
847if [ \-f /usr/\*(SD/sendmail \-a \-f /etc/mail/sendmail.cf ]; then
848 (cd /var/spool/mqueue; rm \-f xf*)
849 /usr/\*(SD/sendmail \-bd \-q30m &
850 echo \-n ' sendmail' >/dev/console
851fi
852.)b
853The
854.q cd
855and
856.q rm
857commands insure that all transcript files have been removed;
858extraneous transcript files may be left around
859if the system goes down in the middle of processing a message.
860The line that actually invokes
861.i sendmail
862has two flags:
863.q \-bd
864causes it to listen on the SMTP port,
865and
866.q \-q30m
867causes it to run the queue every half hour.
868.pp
869Some people use a more complex startup script,
870removing zero length qf files and df files for which there is no qf file.
871For example, see Figure 1
872for an example of a complex script which does this clean up.
873.(z
874.hl
875#!/bin/sh
876# remove zero length qf files
877for qffile in qf*
878do
879 if [ \-r $qffile ]
880 then
881 if [ ! \-s $qffile ]
882 then
883 echo \-n " <zero: $qffile>" > /dev/console
884 rm \-f $qffile
885 fi
886 fi
887done
888# rename tf files to be qf if the qf does not exist
889for tffile in tf*
890do
891 qffile=`echo $tffile | sed 's/t/q/'`
892 if [ \-r $tffile \-a ! \-f $qffile ]
893 then
894 echo \-n " <recovering: $tffile>" > /dev/console
895 mv $tffile $qffile
896 else
897 if [ \-f $tffile ]
898 then
899 echo \-n " <extra: $tffile>" > /dev/console
900 rm \-f $tffile
901 fi
902 fi
903done
904# remove df files with no corresponding qf files
905for dffile in df*
906do
907 qffile=`echo $dffile | sed 's/d/q/'`
908 if [ \-r $dffile \-a ! \-f $qffile ]
909 then
910 echo \-n " <incomplete: $dffile>" > /dev/console
911 mv $dffile `echo $dffile | sed 's/d/D/'`
912 fi
913done
914# announce files that have been saved during disaster recovery
915for xffile in [A-Z]f*
916do
917 if [ \-f $xffile ]
918 then
919 echo \-n " <panic: $xffile>" > /dev/console
920 fi
921done
922.sp
923.ce
924Figure 1 \(em A complex startup script
925.hl
926.)z
927.sh 3 "/etc/mail/helpfile"
928.pp
929This is the help file used by the SMTP
930.b HELP
931command.
932It should be copied from
933.q sendmail/helpfile :
934.(b
935cp sendmail/helpfile /etc/mail/helpfile
936.)b
937The actual path of this file
938is defined in the
939.b HelpFile
940option of the
941.i sendmail.cf
942file.
943.sh 3 "/etc/mail/statistics"
944.pp
945If you wish to collect statistics
946about your mail traffic,
947you should create the file
948.q /etc/mail/statistics :
949.(b
950cp /dev/null /etc/mail/statistics
951chmod 0600 /etc/mail/statistics
952.)b
953This file does not grow.
954It is printed with the program
955.q mailstats/mailstats.c.
956The actual path of this file
957is defined in the
958.b S
959option of the
960.i sendmail.cf
961file.
962.sh 3 "/usr/\*(SB/mailq"
963.pp
964If
965.i sendmail
966is invoked as
967.q mailq,
968it will simulate the
969.b \-bp
970flag
971(i.e.,
972.i sendmail
973will print the contents of the mail queue;
974see below).
975This should be a link to /usr/\*(SD/sendmail.
976.sh 3 "sendmail.pid"
977.pp
978.i sendmail
979stores its current pid in the file specifed by the
980.b PidFile
981option (default is _PATH_SENDMAILPID).
982.i sendmail
983uses
984.b TempFileMode
985(which defaults to 0600) as
986the permissions of that file
987to prevent local denial of service attacks
988as explained in the top level
989.b README
990in the sendmail distribution.
991If the file already exists, then it might be necessary to
992change the permissions accordingly, e.g.,
993.(b
994chmod 0600 /var/run/sendmail.pid
995.)b
996.sh 3 "Map Files"
997.pp
998To prevent local denial of service attacks
999as explained in the top level
1000.b README
1001in the sendmail distribution,
1002the permissions of map files created by
1003.i makemap
1004should be 0640.
1005The use of 0640 implies that only trusted users belong to the group
1006assigned to those files.
1007If those files already exist, then it might be necessary to
1008change the permissions accordingly, e.g.,
1009.(b
1010cd /etc/mail
1011chmod 0640 *.db *.pag *.dir
1012.)b
1013.sh 1 "NORMAL OPERATIONS"
1014.sh 2 "The System Log"
1015.pp
1016The system log is supported by the
1017.i syslogd \|(8)
1018program.
1019All messages from
1020.i sendmail
1021are logged under the
1022.sm LOG_MAIL
1023facility\**.
1024.(f
1025\**Except on Ultrix,
1026which does not support facilities in the syslog.
1027.)f
1028.sh 3 "Format"
1029.pp
1030Each line in the system log
1031consists of a timestamp,
1032the name of the machine that generated it
1033(for logging from several machines
1034over the local area network),
1035the word
1036.q sendmail: ,
1037and a message\**.
1038.(f
1039\**This format may vary slightly if your vendor has changed
1040the syntax.
1041.)f
1042Most messages are a sequence of
1043.i name \c
1044=\c
1045.i value
1046pairs.
1047.pp
1048The two most common lines are logged when a message is processed.
1049The first logs the receipt of a message;
1050there will be exactly one of these per message.
1051Some fields may be omitted if they do not contain interesting information.
1052Fields are:
1053.ip from
1054The envelope sender address.
1055.ip size
1056The size of the message in bytes.
1057.ip class
1058The class (i.e., numeric precedence) of the message.
1059.ip pri
1060The initial message priority (used for queue sorting).
1061.ip nrcpts
1062The number of envelope recipients for this message
1063(after aliasing and forwarding).
1064.ip msgid
1065The message id of the message (from the header).
1066.ip proto
1067The protocol used to receive this message (e.g., ESMTP or UUCP)
1068.ip daemon
1069The daemon name from the
1070.b DaemonPortOptions
1071setting.
1072.ip relay
1073The machine from which it was received.
1074.lp
1075There is also one line logged per delivery attempt
1076(so there can be several per message if delivery is deferred
1077or there are multiple recipients).
1078Fields are:
1079.ip to
1080A comma-separated list of the recipients to this mailer.
1081.ip ctladdr
1082The ``controlling user'', that is, the name of the user
1083whose credentials we use for delivery.
1084.ip delay
1085The total delay between the time this message was received
1086and the current delivery attempt.
1087.ip xdelay
1088The amount of time needed in this delivery attempt
1089(normally indicative of the speed of the connection).
1090.ip mailer
1091The name of the mailer used to deliver to this recipient.
1092.ip relay
1093The name of the host that actually accepted (or rejected) this recipient.
1094.ip dsn
1095The enhanced error code (RFC 2034) if available.
1096.ip stat
1097The delivery status.
1098.lp
1099Not all fields are present in all messages;
1100for example, the relay is usually not listed for local deliveries.
1101.sh 3 "Levels"
1102.pp
1103If you have
1104.i syslogd \|(8)
1105or an equivalent installed,
1106you will be able to do logging.
1107There is a large amount of information that can be logged.
1108The log is arranged as a succession of levels.
1109At the lowest level
1110only extremely strange situations are logged.
1111At the highest level,
1112even the most mundane and uninteresting events
1113are recorded for posterity.
1114As a convention,
1115log levels under ten
1116are considered generally
1117.q useful;
1118log levels above 64
1119are reserved for debugging purposes.
1120Levels from 11\-64 are reserved for verbose information
1121that some sites might want.
1122.pp
1123A complete description of the log levels
1124is given in section
1125.\" XREF
11264.6.
1127.sh 2 "Dumping State"
1128.pp
1129You can ask
1130.i sendmail
1131to log a dump of the open files
1132and the connection cache
1133by sending it a
1134.sm SIGUSR1
1135signal.
1136The results are logged at
1137.sm LOG_DEBUG
1138priority.
1139.sh 2 "The Mail Queues"
1140.pp
1141Mail messages may either be delivered immediately or be held for later
1142delivery.
1143Held messages are placed into a holding directory called a mail queue.
1144.pp
1145A mail message may be queued for these reasons:
1146.bu
1147If a mail message is temporarily undeliverable, it is queued
1148and delivery is attempted later.
1149If the message is addressed to multiple recipients, it is queued
1150only for those recipients to whom delivery is not immediately possible.
1151.bu
1152If the SuperSafe option is set to true,
1153all mail messages are queued while delivery is attempted.
1154.bu
1155If the DeliveryMode option is set to queue-only or defer,
1156all mail is queued, and no immediate delivery is attempted.
1157.bu
1158If the load average becomes higher than the value of the QueueLA option
1159and the
1160.b QueueFactor
1161(\c
1162.b q )
1163option divided by the difference in the current load average and the
1164.b QueueLA
1165option plus one
1166is less than the priority of the message,
1167messages are queued rather than immediately delivered.
1168.sh 3 "Queue Groups and Queue Directories"
1169.pp
1170There are one or more mail queues.
1171Each mail queue belongs to a queue group.
1172There is always a default queue group that is called ``mqueue''
1173(which is where messages go by default unless otherwise specified).
1174The directory or directories which comprise the default queue group
1175are specified by the QueueDirectory option.
1176There are zero or more
1177additional named queue groups declared using the
1178.b Q
1179command in the configuration file.
1180.pp
1181By default, a queued message is placed in the queue group
1182associated with the first recipient in the recipient list.
1183A recipient address is mapped to a queue group as follows.
1184First, if there is a ruleset called ``queuegroup'',
1185and if this ruleset maps the address to a queue group name,
1186then that queue group is chosen.
1187That is, the argument for the ruleset is the recipient address
1188and the result should be
1189.b $#
1190followed by the name of a queue group.
1191Otherwise, if the mailer associated with the address specifies
1192a queue group, then that queue group is chosen.
1193Otherwise, the default queue group is chosen.
1194.pp
1195A message with multiple recipients will be split
1196if different queue groups are chosen
1197by the mapping of recipients to queue groups.
1198.pp
1199When a message is placed in a queue group, and the queue group has
1200more than one queue, a queue is selected randomly.
1201.pp
1202If a message with multiple recipients is placed into a queue group
1203with the 'r' option (maximum number of recipients per message)
1204set to a positive value
1205.i N ,
1206and if there are more than
1207.i N
1208recipients
1209in the message, then the message will be split into multiple messages,
1210each of which have at most
1211.i N
1212recipients.
1213.pp
1214Notice: if multiple queue groups are used, do
1215.b not
1216move queue files around, e.g., into a different queue directory.
1217This may have weird effects and can cause mail not to be delivered.
1218Queue files and directories should be treated as opaque
1219and should not be manipulated directly.
1220.sh 3 "Queue Runs"
1221.pp
1222.i sendmail
1223has two different ways to process the queue(s).
1224The first one is to start queue runners after certain intervals
1225(``normal'' queue runners),
1226the second one is to keep queue runner processes around
1227(``persistent'' queue runners).
1228How to select either of these types is discussed in the appendix
1229``COMMAND LINE FLAGS''.
1230Persistent queue runners have the advantage that no new processes
1231need to be spawned at certain intervals; they just sleep for
1232a specified time after they finished a queue run.
1233Another advantage of persistent queue runners is that only one process
1234belonging to a workgroup (a workgroup is a set of queue groups)
1235collects the data for a queue run
1236and then multiple queue runner may go ahead using that data.
1237This can significantly reduce the disk I/O necessary to read the
1238queue files compared to starting multiple queue runners directly.
1239Their disadvantage is that a new queue run is only started
1240after all queue runners belonging to a group finished their tasks.
1241In case one of the queue runners tries delivery to a slow recipient site
1242at the end of a queue run, the next queue run may be substantially delayed.
1243In general this should be smoothed out due to the distribution of
1244those slow jobs, however, for sites with small number of
1245queue entries this might introduce noticable delays.
1246In general, persistent queue runners are only useful for
1247sites with big queues.
1248.sh 3 "Manual Intervention"
1249.pp
1250Under normal conditions the mail queue will be processed transparently.
1251However, you may find that manual intervention is sometimes necessary.
1252For example,
1253if a major host is down for a period of time
1254the queue may become clogged.
1255Although
1256.i sendmail
1257ought to recover gracefully when the host comes up,
1258you may find performance unacceptably bad in the meantime.
1259In that case you want to check the content of the queue
1260and manipulate it as explained in the next two sections.
1261.sh 3 "Printing the queue"
1262.pp
1263The contents of the queue(s) can be printed
1264using the
1265.i mailq
1266command
1267(or by specifying the
1268.b \-bp
1269flag to
1270.i sendmail ):
1271.(b
1272mailq
1273.)b
1274This will produce a listing of the queue id's,
1275the size of the message,
1276the date the message entered the queue,
1277and the sender and recipients.
1278If shared memory support is compiled in,
1279the flag
1280.b \-bP
1281can be used to print the number of entries in the queue(s),
1282provided a process updates the data.
1283However, as explained earlier, the output might be slightly wrong,
1284since access to the shared memory is not locked.
1285For example,
1286``unknown number of entries''
1287might be shown.
1288The internal counters are updated after each queue run
1289to the correct value again.
1290.sh 3 "Forcing the queue"
1291.pp
1292.i Sendmail
1293should run the queue automatically at intervals.
1294When using multiple queues,
1295a separate process will by default be created to
1296run each of the queues
1297unless the queue run is initiated by a user
1298with the verbose flag.
1299The algorithm is to read and sort the queue,
1300and then to attempt to process all jobs in order.
1301When it attempts to run the job,
1302.i sendmail
1303first checks to see if the job is locked.
1304If so, it ignores the job.
1305.pp
1306There is no attempt to insure that only one queue processor
1307exists at any time,
1308since there is no guarantee that a job cannot take forever
1309to process
1310(however,
1311.i sendmail
1312does include heuristics to try to abort jobs
1313that are taking absurd amounts of time;
1314technically, this violates RFC 821, but is blessed by RFC 1123).
1315Due to the locking algorithm,
1316it is impossible for one job to freeze the entire queue.
1317However,
1318an uncooperative recipient host
1319or a program recipient
1320that never returns
1321can accumulate many processes in your system.
1322Unfortunately,
1323there is no completely general way to solve this.
1324.pp
1325In some cases,
1326you may find that a major host going down
1327for a couple of days
1328may create a prohibitively large queue.
1329This will result in
1330.i sendmail
1331spending an inordinate amount of time
1332sorting the queue.
1333This situation can be fixed by moving the queue to a temporary place
1334and creating a new queue.
1335The old queue can be run later when the offending host returns to service.
1336.pp
1337To do this,
1338it is acceptable to move the entire queue directory:
1339.(b
1340cd /var/spool
1341mv mqueue omqueue; mkdir mqueue; chmod 0700 mqueue
1342.)b
1343You should then kill the existing daemon
1344(since it will still be processing in the old queue directory)
1345and create a new daemon.
1346.pp
1347To run the old mail queue, issue the following command:
1348.(b
1349/usr/\*(SD/sendmail \-C /etc/mail/queue.cf \-q
1350.)b
1351The
1352.b \-C
1353flag specifies an alternate configuration file
1354.b queue.cf
1355which should refer to the moved queue directory
1356.(b
1357O QueueDirectory=/var/spool/omqueue
1358.)b
1359and the
1360.b \-q
1361flag says to just run every job in the queue.
1362You can also specify the moved queue directory on the command line
1363.(b
1364/usr/\*(SD/sendmail \-oQ/var/spool/omqueue \-q
1365.)b
1366but this requires that you do not have
1367queue groups in the configuration file,
1368because those are not subdirectories of the moved directory.
1369See the section about "Queue Group Declaration" for details;
1370you most likely need a different configuration file to correctly deal
1371with this problem.
1372However, a proper configuration of queue groups should avoid
1373filling up queue directories, so you shouldn't run into
1374this problem.
1375If you have a tendency toward voyeurism,
1376you can use the
1377.b \-v
1378flag to watch what is going on.
1379.pp
1380When the queue is finally emptied,
1381you can remove the directory:
1382.(b
1383rmdir /var/spool/omqueue
1384.)b
1385.sh 2 "Disk Based Connection Information"
1386.pp
1387.i Sendmail
1388stores a large amount of information about each remote system it
1389has connected to in memory. It is possible to preserve some
1390of this information on disk as well, by using the
1391.b HostStatusDirectory
1392option, so that it may be shared between several invocations of
1393.i sendmail .
1394This allows mail to be queued immediately or skipped during a queue run if
1395there has been a recent failure in connecting to a remote machine.
1396.pp
1397Additionally enabling
1398.b SingleThreadDelivery
1399has the added effect of single-threading mail delivery to a destination.
1400This can be quite helpful
1401if the remote machine is running an SMTP server that is easily overloaded
1402or cannot accept more than a single connection at a time,
1403but can cause some messages to be punted to a future queue run.
1404It also applies to
1405.i all
1406hosts, so setting this because you have one machine on site
1407that runs some software that is easily overrun
1408can cause mail to other hosts to be slowed down.
1409If this option is set,
1410you probably want to set the
1411.b MinQueueAge
1412option as well and run the queue fairly frequently;
1413this way jobs that are skipped because another
1414.i sendmail
1415is talking to the same host will be tried again quickly
1416rather than being delayed for a long time.
1417.pp
1418The disk based host information is stored in a subdirectory of the
1419.b mqueue
1420directory called
1421.b \&.hoststat \**.
1422.(f
1423\**This is the usual value of the
1424.b HostStatusDirectory
1425option;
1426it can, of course, go anywhere you like in your filesystem.
1427.)f
1428Removing this directory and its subdirectories has an effect similar to
1429the
1430.i purgestat
1431command and is completely safe.
1432However,
1433.i purgestat
1434only removes expired (Timeout.hoststatus) data.
1435The information in these directories can
1436be perused with the
1437.i hoststat
1438command, which will indicate the host name, the last access, and the
1439status of that access.
1440An asterisk in the left most column indicates that a
1441.i sendmail
1442process currently has the host locked for mail delivery.
1443.pp
1444The disk based connection information is treated the same way as memory based
1445connection information for the purpose of timeouts.
1446By default, information about host failures is valid for 30 minutes.
1447This can be adjusted with
1448the
1449.b Timeout.hoststatus
1450option.
1451.pp
1452The connection information stored on disk may be expired at any time
1453with the
1454.i purgestat
1455command or by invoking sendmail with the
1456.b \-bH
1457switch.
1458The connection information may be viewed with the
1459.i hoststat
1460command or by invoking sendmail with the
1461.b \-bh
1462switch.
1463.sh 2 "The Service Switch"
1464.pp
1465The implementation of certain system services
1466such as host and user name lookup
1467is controlled by the service switch.
1468If the host operating system supports such a switch,
1469and sendmail knows about it,
1470.i sendmail
1471will use the native version.
1472Ultrix, Solaris, and DEC OSF/1 are examples of such systems\**.
1473.(f
1474\**HP-UX 10 has service switch support,
1475but since the APIs are apparently not available in the libraries
1476.i sendmail
1477does not use the native service switch in this release.
1478.)f
1479.pp
1480If the underlying operating system does not support a service switch
1481(e.g., SunOS 4.X, HP-UX, BSD)
1482then
1483.i sendmail
1484will provide a stub implementation.
1485The
1486.b ServiceSwitchFile
1487option points to the name of a file that has the service definitions.
1488Each line has the name of a service
1489and the possible implementations of that service.
1490For example, the file:
1491.(b
1492hosts dns files nis
1493aliases files nis
1494.)b
1495will ask
1496.i sendmail
1497to look for hosts in the Domain Name System first.
1498If the requested host name is not found, it tries local files,
1499and if that fails it tries NIS.
1500Similarly, when looking for aliases
1501it will try the local files first followed by NIS.
1502.pp
1503Notice: since
1504.i sendmail
1505must access MX records for correct operation, it will use
1506DNS if it is configured in the
1507.b ServiceSwitchFile
1508file.
1509Hence an entry like
1510.(b
1511hosts files dns
1512.)b
1513will not avoid DNS lookups even if a host can be found
1514in /etc/hosts.
1515.pp
1516Service switches are not completely integrated.
1517For example, despite the fact that the host entry listed in the above example
1518specifies to look in NIS,
1519on SunOS this won't happen because the system implementation of
1520.i gethostbyname \|(3)
1521doesn't understand this.
1522.sh 2 "The Alias Database"
1523.pp
1524After recipient addresses are read from the SMTP connection
1525or command line
1526they are parsed by ruleset 0,
1527which must resolve to a
1528{\c
1529.i mailer ,
1530.i host ,
1531.i address }
1532triple.
1533If the flags selected by the
1534.i mailer
1535include the
1536.b A
1537(aliasable) flag,
1538the
1539.i address
1540part of the triple is looked up as the key
1541(i.e., the left hand side)
1542into the alias database.
1543If there is a match, the address is deleted from the send queue
1544and all addresses on the right hand side of the alias
1545are added in place of the alias that was found.
1546This is a recursive operation,
1547so aliases found in the right hand side of the alias
1548are similarly expanded.
1549.pp
1550The alias database exists in two forms.
1551One is a text form,
1552maintained in the file
1553.i /etc/mail/aliases.
1554The aliases are of the form
1555.(b
1556name: name1, name2, ...
1557.)b
1558Only local names may be aliased;
1559e.g.,
1560.(b
1561eric@prep.ai.MIT.EDU: eric@CS.Berkeley.EDU
1562.)b
1563will not have the desired effect
1564(except on prep.ai.MIT.EDU,
1565and they probably don't want me)\**.
1566.(f
1567\**Actually, any mailer that has the `A' mailer flag set
1568will permit aliasing;
1569this is normally limited to the local mailer.
1570.)f
1571Aliases may be continued by starting any continuation lines
1572with a space or a tab or by putting a backslash directly before
1573the newline.
1574Blank lines and lines beginning with a sharp sign
1575(\c
1576.q # )
1577are comments.
1578.pp
1579The second form is processed by the
1580.i ndbm \|(3)\**
1581.(f
1582\**The
1583.i gdbm
1584package does not work.
1585.)f
1586or the Berkeley DB library.
1587This form is in the file
1588.i /etc/mail/aliases.db
1589(if using NEWDB)
1590or
1591.i /etc/mail/aliases.dir
1592and
1593.i /etc/mail/aliases.pag
1594(if using NDBM).
1595This is the form that
1596.i sendmail
1597actually uses to resolve aliases.
1598This technique is used to improve performance.
1599.pp
1600The control of search order is actually set by the service switch.
1601Essentially, the entry
1602.(b
1603O AliasFile=switch:aliases
1604.)b
1605is always added as the first alias entry;
1606also, the first alias file name without a class
1607(e.g., without
1608.q nis:
1609on the front)
1610will be used as the name of the file for a ``files'' entry
1611in the aliases switch.
1612For example, if the configuration file contains
1613.(b
1614O AliasFile=/etc/mail/aliases
1615.)b
1616and the service switch contains
1617.(b
1618aliases nis files nisplus
1619.)b
1620then aliases will first be searched in the NIS database,
1621then in /etc/mail/aliases,
1622then in the NIS+ database.
1623.pp
1624You can also use
1625.sm NIS -based
1626alias files.
1627For example, the specification:
1628.(b
1629O AliasFile=/etc/mail/aliases
1630O AliasFile=nis:mail.aliases@my.nis.domain
1631.)b
1632will first search the /etc/mail/aliases file
1633and then the map named
1634.q mail.aliases
1635in
1636.q my.nis.domain .
1637Warning: if you build your own
1638.sm NIS -based
1639alias files,
1640be sure to provide the
1641.b \-l
1642flag to
1643.i makedbm (8)
1644to map upper case letters in the keys to lower case;
1645otherwise, aliases with upper case letters in their names
1646won't match incoming addresses.
1647.pp
1648Additional flags can be added after the colon
1649exactly like a
1650.b K
1651line \(em for example:
1652.(b
1653O AliasFile=nis:\-N mail.aliases@my.nis.domain
1654.)b
1655will search the appropriate NIS map and always include null bytes in the key.
1656Also:
1657.(b
1658O AliasFile=nis:\-f mail.aliases@my.nis.domain
1659.)b
1660will prevent sendmail from downcasing the key before the alias lookup.
1661.sh 3 "Rebuilding the alias database"
1662.pp
1663The
1664.i hash
1665or
1666.i dbm
1667version of the database
1668may be rebuilt explicitly by executing the command
1669.(b
1670newaliases
1671.)b
1672This is equivalent to giving
1673.i sendmail
1674the
1675.b \-bi
1676flag:
1677.(b
1678/usr/\*(SD/sendmail \-bi
1679.)b
1680.pp
1681If you have multiple aliases databases specified,
1682the
1683.b \-bi
1684flag rebuilds all the database types it understands
1685(for example, it can rebuild NDBM databases but not NIS databases).
1686.sh 3 "Potential problems"
1687.pp
1688There are a number of problems that can occur
1689with the alias database.
1690They all result from a
1691.i sendmail
1692process accessing the DBM version
1693while it is only partially built.
1694This can happen under two circumstances:
1695One process accesses the database
1696while another process is rebuilding it,
1697or the process rebuilding the database dies
1698(due to being killed or a system crash)
1699before completing the rebuild.
1700.pp
1701Sendmail has three techniques to try to relieve these problems.
1702First, it ignores interrupts while rebuilding the database;
1703this avoids the problem of someone aborting the process
1704leaving a partially rebuilt database.
1705Second,
1706it locks the database source file during the rebuild \(em
1707but that may not work over NFS or if the file is unwritable.
1708Third,
1709at the end of the rebuild
1710it adds an alias of the form
1711.(b
1712@: @
1713.)b
1714(which is not normally legal).
1715Before
1716.i sendmail
1717will access the database,
1718it checks to insure that this entry exists\**.
1719.(f
1720\**The
1721.b AliasWait
1722option is required in the configuration
1723for this action to occur.
1724This should normally be specified.
1725.)f
1726.sh 3 "List owners"
1727.pp
1728If an error occurs on sending to a certain address,
1729say
1730.q \fIx\fP ,
1731.i sendmail
1732will look for an alias
1733of the form
1734.q owner-\fIx\fP
1735to receive the errors.
1736This is typically useful
1737for a mailing list
1738where the submitter of the list
1739has no control over the maintenance of the list itself;
1740in this case the list maintainer would be the owner of the list.
1741For example:
1742.(b
1743unix-wizards: eric@ucbarpa, wnj@monet, nosuchuser,
1744 sam@matisse
1745owner-unix-wizards: unix-wizards-request
1746unix-wizards-request: eric@ucbarpa
1747.)b
1748would cause
1749.q eric@ucbarpa
1750to get the error that will occur
1751when someone sends to
1752unix-wizards
1753due to the inclusion of
1754.q nosuchuser
1755on the list.
1756.pp
1757List owners also cause the envelope sender address to be modified.
1758The contents of the owner alias are used if they point to a single user,
1759otherwise the name of the alias itself is used.
1760For this reason, and to obey Internet conventions,
1761the
1762.q owner-
1763address normally points at the
1764.q -request
1765address; this causes messages to go out with the typical Internet convention
1766of using ``\c
1767.i list -request''
1768as the return address.
1769.sh 2 "User Information Database"
1770.pp
1771This option is deprecated, use virtusertable and genericstable instead
1772as explained in
1773.i cf/README .
1774If you have a version of
1775.i sendmail
1776with the user information database
1777compiled in,
1778and you have specified one or more databases using the
1779.b U
1780option,
1781the databases will be searched for a
1782.i user :maildrop
1783entry.
1784If found, the mail will be sent to the specified address.
1785.sh 2 "Per-User Forwarding (.forward Files)"
1786.pp
1787As an alternative to the alias database,
1788any user may put a file with the name
1789.q .forward
1790in his or her home directory.
1791If this file exists,
1792.i sendmail
1793redirects mail for that user
1794to the list of addresses listed in the .forward file.
1795Note that aliases are fully expanded before forward files are referenced.
1796For example, if the home directory for user
1797.q mckusick
1798has a .forward file with contents:
1799.(b
1800mckusick@ernie
1801kirk@calder
1802.)b
1803then any mail arriving for
1804.q mckusick
1805will be redirected to the specified accounts.
1806.pp
1807Actually, the configuration file defines a sequence of filenames to check.
1808By default, this is the user's .forward file,
1809but can be defined to be more generally using the
1810.b ForwardPath
1811option.
1812If you change this,
1813you will have to inform your user base of the change;
1814\&.forward is pretty well incorporated into the collective subconscious.
1815.sh 2 "Special Header Lines"
1816.pp
1817Several header lines have special interpretations
1818defined by the configuration file.
1819Others have interpretations built into
1820.i sendmail
1821that cannot be changed without changing the code.
1822These built-ins are described here.
1823.sh 3 "Errors-To:"
1824.pp
1825If errors occur anywhere during processing,
1826this header will cause error messages to go to
1827the listed addresses.
1828This is intended for mailing lists.
1829.pp
1830The Errors-To: header was created in the bad old days
1831when UUCP didn't understand the distinction between an envelope and a header;
1832this was a hack to provide what should now be passed
1833as the envelope sender address.
1834It should go away.
1835It is only used if the
1836.b UseErrorsTo
1837option is set.
1838.pp
1839The Errors-To: header is officially deprecated
1840and will go away in a future release.
1841.sh 3 "Apparently-To:"
1842.pp
1843RFC 822 requires at least one recipient field
1844(To:, Cc:, or Bcc: line)
1845in every message.
1846If a message comes in with no recipients listed in the message
1847then
1848.i sendmail
1849will adjust the header based on the
1850.q NoRecipientAction
1851option.
1852One of the possible actions is to add an
1853.q "Apparently-To:"
1854header line for any recipients it is aware of.
1855.pp
1856The Apparently-To: header is non-standard
1857and is both deprecated and strongly discouraged.
1858.sh 3 "Precedence"
1859.pp
1860The Precedence: header can be used as a crude control of message priority.
1861It tweaks the sort order in the queue
1862and can be configured to change the message timeout values.
1863The precedence of a message also controls how
1864delivery status notifications (DSNs)
1865are processed for that message.
1866.sh 2 "IDENT Protocol Support"
1867.pp
1868.i Sendmail
1869supports the IDENT protocol as defined in RFC 1413.
1870Note that the RFC states
1871a client should wait at least 30 seconds for a response.
1872The default Timeout.ident is 5 seconds
1873as many sites have adopted the practice of dropping IDENT queries.
1874This has lead to delays processing mail.
1875Although this enhances identification
1876of the author of an email message
1877by doing a ``call back'' to the originating system to include
1878the owner of a particular TCP connection
1879in the audit trail
1880it is in no sense perfect;
1881a determined forger can easily spoof the IDENT protocol.
1882The following description is excerpted from RFC 1413:
1883.ba +5
1884.lp
18856. Security Considerations
1886.lp
1887The information returned by this protocol is at most as trustworthy
1888as the host providing it OR the organization operating the host. For
1889example, a PC in an open lab has few if any controls on it to prevent
1890a user from having this protocol return any identifier the user
1891wants. Likewise, if the host has been compromised the information
1892returned may be completely erroneous and misleading.
1893.lp
1894The Identification Protocol is not intended as an authorization or
1895access control protocol. At best, it provides some additional
1896auditing information with respect to TCP connections. At worst, it
1897can provide misleading, incorrect, or maliciously incorrect
1898information.
1899.lp
1900The use of the information returned by this protocol for other than
1901auditing is strongly discouraged. Specifically, using Identification
1902Protocol information to make access control decisions - either as the
1903primary method (i.e., no other checks) or as an adjunct to other
1904methods may result in a weakening of normal host security.
1905.lp
1906An Identification server may reveal information about users,
1907entities, objects or processes which might normally be considered
1908private. An Identification server provides service which is a rough
1909analog of the CallerID services provided by some phone companies and
1910many of the same privacy considerations and arguments that apply to
1911the CallerID service apply to Identification. If you wouldn't run a
1912"finger" server due to privacy considerations you may not want to run
1913this protocol.
1914.ba
1915.lp
1916In some cases your system may not work properly with IDENT support
1917due to a bug in the TCP/IP implementation.
1918The symptoms will be that for some hosts
1919the SMTP connection will be closed
1920almost immediately.
1921If this is true or if you do not want to use IDENT,
1922you should set the IDENT timeout to zero;
1923this will disable the IDENT protocol.
1924.sh 1 "ARGUMENTS"
1925.pp
1926The complete list of arguments to
1927.i sendmail
1928is described in detail in Appendix A.
1929Some important arguments are described here.
1930.sh 2 "Queue Interval"
1931.pp
1932The amount of time between forking a process
1933to run through the queue is defined by the
1934.b \-q
1935flag.
1936If you run with delivery mode set to
1937.b i
1938or
1939.b b
1940this can be relatively large, since it will only be relevant
1941when a host that was down comes back up.
1942If you run in
1943.b q
1944mode it should be relatively short,
1945since it defines the maximum amount of time that a message
1946may sit in the queue.
1947(See also the MinQueueAge option.)
1948.pp
1949RFC 1123 section 5.3.1.1 says that this value should be at least 30 minutes
1950(although that probably doesn't make sense if you use ``queue-only'' mode).
1951.pp
1952Notice: the meaning of the interval time depends on whether normal
1953queue runners or persistent queue runners are used.
1954For the former, it is the time between subsequent starts of a queue run.
1955For the latter, it is the time sendmail waits after a persistent queue
1956runner has finished its work to start the next one.
1957Hence for persistent queue runners this interval should be very low,
1958typically no more than two minutes.
1959.sh 2 "Daemon Mode"
1960.pp
1961If you allow incoming mail over an IPC connection,
1962you should have a daemon running.
1963This should be set by your
1964.i /etc/rc
1965file using the
1966.b \-bd
1967flag.
1968The
1969.b \-bd
1970flag and the
1971.b \-q
1972flag may be combined in one call:
1973.(b
1974/usr/\*(SD/sendmail \-bd \-q30m
1975.)b
1976.pp
1977An alternative approach is to invoke sendmail from
1978.i inetd (8)
1979(use the
1980.b \-bs \ \-Am
1981flags to ask sendmail to speak SMTP on its standard input and output
1982and to run as MTA).
1983This works and allows you to wrap
1984.i sendmail
1985in a TCP wrapper program,
1986but may be a bit slower since the configuration file
1987has to be re-read on every message that comes in.
1988If you do this, you still need to have a
1989.i sendmail
1990running to flush the queue:
1991.(b
1992/usr/\*(SD/sendmail \-q30m
1993.)b
1994.sh 2 "Forcing the Queue"
1995.pp
1996In some cases you may find that the queue has gotten clogged for some reason.
1997You can force a queue run
1998using the
1999.b \-q
2000flag (with no value).
2001It is entertaining to use the
2002.b \-v
2003flag (verbose)
2004when this is done to watch what happens:
2005.(b
2006/usr/\*(SD/sendmail \-q \-v
2007.)b
2008.pp
2009You can also limit the jobs to those with a particular queue identifier,
2010recipient, sender, or queue group
2011using one of the queue modifiers.
2012For example,
2013.q \-qRberkeley
2014restricts the queue run to jobs that have the string
2015.q berkeley
2016somewhere in one of the recipient addresses.
2017Similarly,
2018.q \-qSstring
2019limits the run to particular senders,
2020.q \-qIstring
2021limits it to particular queue identifiers, and
2022.q \-qGstring
2023limits it to a particular queue group.
2024You may also place an
2025.b !
2026before the
2027.b I
2028or
2029.b R
2030or
2031.b S
2032to indicate that jobs are limited to not including a particular queue
2033identifier, recipient or sender.
2034For example,
2035.q \-q!Rseattle
2036limits the queue run to jobs that do not have the string
2037.q seattle
2038somewhere in one of the recipient addresses.
2039Should you need to terminate the queue jobs currently active then a SIGTERM
2040to the parent of the process (or processes) will cleanly stop the jobs.
2041.sh 2 "Debugging"
2042.pp
2043There are a fairly large number of debug flags
2044built into
2045.i sendmail .
2046Each debug flag has a category and a level.
2047Higher levels increase the level of debugging activity;
2048in most cases, this means to print out more information.
2049The convention is that levels greater than nine are
2050.q absurd,
2051i.e.,
2052they print out so much information that you wouldn't normally
2053want to see them except for debugging that particular piece of code.
2054.pp
2055A debug category is either an integer, like 42,
2056or a name, like ANSI.
2057You can specify a range of numeric debug categories
2058using the syntax 17-42.
2059You can specify a set of named debug categories using
2060a glob pattern like
2061.q sm_trace_* .
2062At present, only
2063.q *
2064and
2065.q ?
2066are supported in these glob patterns.
2067.pp
2068Debug flags are set using the
2069.b \-d
2070option;
2071the syntax is:
2072.(b
2073.ta \w'debug-categories:M 'u
2074debug-flag: \fB\-d\fP debug-list
2075debug-list: debug-option [ , debug-option ]*
2076debug-option: debug-categories [ . debug-level ]
2077debug-categories: integer | integer \- integer | category-pattern
2078category-pattern: [a-zA-Z_*?][a-zA-Z0-9_*?]*
2079debug-level: integer
2080.)b
2081where spaces are for reading ease only.
2082For example,
2083.(b
2084\-d12 Set category 12 to level 1
2085\-d12.3 Set category 12 to level 3
2086\-d3\-17 Set categories 3 through 17 to level 1
2087\-d3\-17.4 Set categories 3 through 17 to level 4
2088\-dANSI Set category ANSI to level 1
2089\-dsm_trace_*.3 Set all named categories matching sm_trace_* to level 3
2090.)b
2091For a complete list of the available debug flags
2092you will have to look at the code
2093and the
2094.i TRACEFLAGS
2095file in the sendmail distribution
2096(they are too dynamic to keep this document up to date).
2097For a list of named debug categories in the sendmail binary, use
2098.(b
2099ident /usr/sbin/sendmail | grep Debug
2100.)b
2101.sh 2 "Changing the Values of Options"
2102.pp
2103Options can be overridden using the
2104.b \-o
2105or
2106.b \-O
2107command line flags.
2108For example,
2109.(b
2110/usr/\*(SD/sendmail \-oT2m
2111.)b
2112sets the
2113.b T
2114(timeout) option to two minutes
2115for this run only;
2116the equivalent line using the long option name is
2117.(b
2118/usr/\*(SD/sendmail -OTimeout.queuereturn=2m
2119.)b
2120.pp
2121Some options have security implications.
2122Sendmail allows you to set these,
2123but relinquishes its set-user-ID or set-group-ID permissions thereafter\**.
2124.(f
2125\**That is, it sets its effective uid to the real uid;
2126thus, if you are executing as root,
2127as from root's crontab file or during system startup
2128the root permissions will still be honored.
2129.)f
2130.sh 2 "Trying a Different Configuration File"
2131.pp
2132An alternative configuration file
2133can be specified using the
2134.b \-C
2135flag; for example,
2136.(b
2137/usr/\*(SD/sendmail \-Ctest.cf \-oQ/tmp/mqueue
2138.)b
2139uses the configuration file
2140.i test.cf
2141instead of the default
2142.i /etc/mail/sendmail.cf.
2143If the
2144.b \-C
2145flag has no value
2146it defaults to
2147.i sendmail.cf
2148in the current directory.
2149.pp
2150.i Sendmail
2151gives up set-user-ID root permissions
2152(if it has been installed set-user-ID root)
2153when you use this flag, so it is common to use a publicly writable directory
2154(such as /tmp)
2155as the queue directory (QueueDirectory or Q option) while testing.
2156.sh 2 "Logging Traffic"
2157.pp
2158Many SMTP implementations do not fully implement the protocol.
2159For example, some personal computer based SMTPs
2160do not understand continuation lines in reply codes.
2161These can be very hard to trace.
2162If you suspect such a problem, you can set traffic logging using the
2163.b \-X
2164flag.
2165For example,
2166.(b
2167/usr/\*(SD/sendmail \-X /tmp/traffic \-bd
2168.)b
2169will log all traffic in the file
2170.i /tmp/traffic .
2171.pp
2172This logs a lot of data very quickly and should
2173.b NEVER
2174be used
2175during normal operations.
2176After starting up such a daemon,
2177force the errant implementation to send a message to your host.
2178All message traffic in and out of
2179.i sendmail ,
2180including the incoming SMTP traffic,
2181will be logged in this file.
2182.sh 2 "Testing Configuration Files"
2183.pp
2184When you build a configuration table,
2185you can do a certain amount of testing
2186using the
2187.q "test mode"
2188of
2189.i sendmail .
2190For example,
2191you could invoke
2192.i sendmail
2193as:
2194.(b
2195sendmail \-bt \-Ctest.cf
2196.)b
2197which would read the configuration file
2198.q test.cf
2199and enter test mode.
2200In this mode,
2201you enter lines of the form:
2202.(b
2203rwset address
2204.)b
2205where
2206.i rwset
2207is the rewriting set you want to use
2208and
2209.i address
2210is an address to apply the set to.
2211Test mode shows you the steps it takes
2212as it proceeds,
2213finally showing you the address it ends up with.
2214You may use a comma separated list of rwsets
2215for sequential application of rules to an input.
2216For example:
2217.(b
22183,1,21,4 monet:bollard
2219.)b
2220first applies ruleset three to the input
2221.q monet:bollard.
2222Ruleset one is then applied to the output of ruleset three,
2223followed similarly by rulesets twenty-one and four.
2224.pp
2225If you need more detail,
2226you can also use the
2227.q \-d21
2228flag to turn on more debugging.
2229For example,
2230.(b
2231sendmail \-bt \-d21.99
2232.)b
2233turns on an incredible amount of information;
2234a single word address
2235is probably going to print out several pages worth of information.
2236.pp
2237You should be warned that internally,
2238.i sendmail
2239applies ruleset 3 to all addresses.
2240In test mode
2241you will have to do that manually.
2242For example, older versions allowed you to use
2243.(b
22440 bruce@broadcast.sony.com
2245.)b
2246This version requires that you use:
2247.(b
22483,0 bruce@broadcast.sony.com
2249.)b
2250.pp
2251As of version 8.7,
2252some other syntaxes are available in test mode:
2253.nr ii 1i
2254.ip \&.D\|x\|value
2255defines macro
2256.i x
2257to have the indicated
2258.i value .
2259This is useful when debugging rules that use the
2260.b $& \c
2261.i x
2262syntax.
2263.ip \&.C\|c\|value
2264adds the indicated
2265.i value
2266to class
2267.i c .
2268.ip \&=S\|ruleset
2269dumps the contents of the indicated ruleset.
2270.ip \-d\|debug-spec
2271is equivalent to the command-line flag.
2272.lp
2273Version 8.9 introduced more features:
2274.nr ii 1i
2275.ip ?
2276shows a help message.
2277.ip =M
2278display the known mailers.
2279.ip $m
2280print the value of macro m.
2281.ip $=c
2282print the contents of class c.
2283.ip /mx\ host
2284returns the MX records for `host'.
2285.ip /parse\ address
2286parse address, returning the value of
2287.i crackaddr ,
2288and the parsed address.
2289.ip /try\ mailer\ addr
2290rewrite address into the form it will have when
2291presented to the indicated mailer.
2292.ip /tryflags\ flags
2293set flags used by parsing. The flags can be `H' for
2294Header or `E' for Envelope, and `S' for Sender or `R'
2295for Recipient. These can be combined, `HR' sets
2296flags for header recipients.
2297.ip /canon\ hostname
2298try to canonify hostname.
2299.ip /map\ mapname\ key
2300look up `key' in the indicated `mapname'.
2301.ip /quit
2302quit address test mode.
2303.lp
2304.sh 2 "Persistent Host Status Information"
2305.pp
2306When
2307.b HostStatusDirectory
2308is enabled,
2309information about the status of hosts is maintained on disk
2310and can thus be shared between different instantiations of
2311.i sendmail .
2312The status of the last connection with each remote host
2313may be viewed with the command:
2314.(b
2315sendmail \-bh
2316.)b
2317This information may be flushed with the command:
2318.(b
2319sendmail \-bH
2320.)b
2321Flushing the information prevents new
2322.i sendmail
2323processes from loading it,
2324but does not prevent existing processes from using the status information
2325that they already have.
2326.sh 1 "TUNING"
2327.pp
2328There are a number of configuration parameters
2329you may want to change,
2330depending on the requirements of your site.
2331Most of these are set
2332using an option in the configuration file.
2333For example,
2334the line
2335.q "O Timeout.queuereturn=5d"
2336sets option
2337.q Timeout.queuereturn
2338to the value
2339.q 5d
2340(five days).
2341.pp
2342Most of these options have appropriate defaults for most sites.
2343However,
2344sites having very high mail loads may find they need to tune them
2345as appropriate for their mail load.
2346In particular,
2347sites experiencing a large number of small messages,
2348many of which are delivered to many recipients,
2349may find that they need to adjust the parameters
2350dealing with queue priorities.
2351.pp
2352All versions of
2353.i sendmail
2354prior to 8.7
2355had single character option names.
2356As of 8.7,
2357options have long (multi-character names).
2358Although old short names are still accepted,
2359most new options do not have short equivalents.
2360.pp
2361This section only describes the options you are most likely
2362to want to tweak;
2363read section
2364.\"XREF
23655
2366for more details.
2367.sh 2 "Timeouts"
2368.pp
2369All time intervals are set
2370using a scaled syntax.
2371For example,
2372.q 10m
2373represents ten minutes, whereas
2374.q 2h30m
2375represents two and a half hours.
2376The full set of scales is:
2377.(b
2378.ta 4n
2379s seconds
2380m minutes
2381h hours
2382d days
2383w weeks
2384.)b
2385.sh 3 "Queue interval"
2386.pp
2387The argument to the
2388.b \-q
2389flag specifies how often a sub-daemon will run the queue.
2390This is typically set to between fifteen minutes and one hour.
2391If not set, or set to zero,
2392the queue will not be run automatically.
2393RFC 1123 section 5.3.1.1 recommends that this be at least 30 minutes.
2394Should you need to terminate the queue jobs currently active then a SIGTERM
2395to the parent of the process (or processes) will cleanly stop the jobs.
2396.sh 3 "Read timeouts"
2397.pp
2398Timeouts all have option names
2399.q Timeout.\fIsuboption\fP .
2400Most of these control SMTP operations.
2401The recognized
2402.i suboption s,
2403their default values, and the minimum values
2404allowed by RFC 2821 section 4.5.3.2 (or RFC 1123 section 5.3.2) are:
2405.nr ii 1i
2406.ip connect
2407The time to wait for an SMTP connection to open
2408(the
2409.i connect (2)
2410system call)
2411[0, unspecified].
2412If zero, uses the kernel default.
2413In no case can this option extend the timeout
2414longer than the kernel provides, but it can shorten it.
2415This is to get around kernels that provide an absurdly long connection timeout
2416(90 minutes in one case).
2417.ip iconnect
2418The same as
2419.i connect,
2420except it applies only to the initial attempt to connect to a host
2421for a given message
2422[0, unspecified].
2423The concept is that this should be very short (a few seconds);
2424hosts that are well connected and responsive will thus be serviced immediately.
2425Hosts that are slow will not hold up other deliveries in the initial
2426delivery attempt.
2427.ip aconnect
2428[0, unspecified]
2429The overall timeout waiting for all connection for a single delivery
2430attempt to succeed.
2431If 0, no overall limit is applied.
2432This can be used to restrict the total amount of time trying to connect to
2433a long list of host that could accept an e-mail for the recipient.
2434This timeout does not apply to
2435.b FallbackMXhost ,
2436i.e., if the time is exhausted, the
2437.b FallbackMXhost
2438is tried next.
2439.ip initial
2440The wait for the initial 220 greeting message
2441[5m, 5m].
2442.ip helo
2443The wait for a reply from a HELO or EHLO command
2444[5m, unspecified].
2445This may require a host name lookup, so
2446five minutes is probably a reasonable minimum.
2447.ip mail\(dg
2448The wait for a reply from a MAIL command
2449[10m, 5m].
2450.ip rcpt\(dg
2451The wait for a reply from a RCPT command
2452[1h, 5m].
2453This should be long
2454because it could be pointing at a list
2455that takes a long time to expand
2456(see below).
2457.ip datainit\(dg
2458The wait for a reply from a DATA command
2459[5m, 2m].
2460.ip datablock\(dg\(dd
2461The wait for reading a data block
2462(that is, the body of the message).
2463[1h, 3m].
2464This should be long because it also applies to programs
2465piping input to
2466.i sendmail
2467which have no guarantee of promptness.
2468.ip datafinal\(dg
2469The wait for a reply from the dot terminating a message.
2470[1h, 10m].
2471If this is shorter than the time actually needed
2472for the receiver to deliver the message,
2473duplicates will be generated.
2474This is discussed in RFC 1047.
2475.ip rset
2476The wait for a reply from a RSET command
2477[5m, unspecified].
2478.ip quit
2479The wait for a reply from a QUIT command
2480[2m, unspecified].
2481.ip misc
2482The wait for a reply from miscellaneous (but short) commands
2483such as NOOP (no-operation) and VERB (go into verbose mode).
2484[2m, unspecified].
2485.ip command\(dg\(dd
2486In server SMTP,
2487the time to wait for another command.
2488[1h, 5m].
2489.ip ident\(dd
2490The timeout waiting for a reply to an IDENT query
2491[5s\**, unspecified].
2492.(f
2493\**On some systems the default is zero to turn the protocol off entirely.
2494.)f
2495.ip lhlo
2496The wait for a reply to an LMTP LHLO command
2497[2m, unspecified].
2498.ip auth
2499The timeout for a reply in an SMTP AUTH dialogue
2500[10m, unspecified].
2501.ip starttls
2502The timeout for a reply to an SMTP STARTTLS command and the TLS handshake
2503[1h, unspecified].
2504.ip fileopen\(dd
2505The timeout for opening .forward and :include: files [60s, none].
2506.ip control\(dd
2507The timeout for a complete control socket transaction to complete [2m, none].
2508.ip hoststatus\(dd
2509How long status information about a host
2510(e.g., host down)
2511will be cached before it is considered stale
2512[30m, unspecified].
2513.ip resolver.retrans\(dd
2514The resolver's
2515retransmission time interval
2516(in seconds)
2517[varies].
2518Sets both
2519.i Timeout.resolver.retrans.first
2520and
2521.i Timeout.resolver.retrans.normal .
2522.ip resolver.retrans.first\(dd
2523The resolver's
2524retransmission time interval
2525(in seconds)
2526for the first attempt to
2527deliver a message
2528[varies].
2529.ip resolver.retrans.normal\(dd
2530The resolver's
2531retransmission time interval
2532(in seconds)
2533for all resolver lookups
2534except the first delivery attempt
2535[varies].
2536.ip resolver.retry\(dd
2537The number of times
2538to retransmit a resolver query.
2539Sets both
2540.i Timeout.resolver.retry.first
2541and
2542.i Timeout.resolver.retry.normal
2543[varies].
2544.ip resolver.retry.first\(dd
2545The number of times
2546to retransmit a resolver query
2547for the first attempt
2548to deliver a message
2549[varies].
2550.ip resolver.retry.normal\(dd
2551The number of times
2552to retransmit a resolver query
2553for all resolver lookups
2554 except the first delivery attempt
2555[varies].
2556.lp
2557For compatibility with old configuration files,
2558if no
2559.i suboption
2560is specified,
2561all the timeouts marked with
2562.DG
2563(\(dg) are set to the indicated value.
2564All but those marked with
2565.DD
2566(\(dd) apply to client SMTP.
2567.pp
2568For example, the lines:
2569.(b
2570O Timeout.command=25m
2571O Timeout.datablock=3h
2572.)b
2573sets the server SMTP command timeout to 25 minutes
2574and the input data block timeout to three hours.
2575.sh 3 "Message timeouts"
2576.pp
2577After sitting in the queue for a few days,
2578an undeliverable message will time out.
2579This is to insure that at least the sender is aware
2580of the inability to send a message.
2581The timeout is typically set to five days.
2582It is sometimes considered convenient to also send a warning message
2583if the message is in the queue longer than a few hours
2584(assuming you normally have good connectivity;
2585if your messages normally took several hours to send
2586you wouldn't want to do this because it wouldn't be an unusual event).
2587These timeouts are set using the
2588.b Timeout.queuereturn
2589and
2590.b Timeout.queuewarn
2591options in the configuration file
2592(previously both were set using the
2593.b T
2594option).
2595.pp
2596If the message is submitted using the
2597.sm NOTIFY
2598.sm SMTP
2599extension,
2600warning messages will only be sent if
2601.sm NOTIFY=DELAY
2602is specified.
2603The queuereturn and queuewarn timeouts
2604can be further qualified with a tag based on the Precedence: field
2605in the message;
2606they must be one of
2607.q urgent
2608(indicating a positive non-zero precedence)
2609.q normal
2610(indicating a zero precedence), or
2611.q non-urgent
2612(indicating negative precedences).
2613For example, setting
2614.q Timeout.queuewarn.urgent=1h
2615sets the warning timeout for urgent messages only
2616to one hour.
2617The default if no precedence is indicated
2618is to set the timeout for all precedences.
2619The value "now" can be used for
2620-O Timeout.queuereturn
2621to return entries immediately during a queue run,
2622e.g., to bounce messages independent of their time in the queue.
2623.pp
2624Since these options are global,
2625and since you cannot know
2626.i "a priori"
2627how long another host outside your domain will be down,
2628a five day timeout is recommended.
2629This allows a recipient to fix the problem even if it occurs
2630at the beginning of a long weekend.
2631RFC 1123 section 5.3.1.1 says that this parameter
2632should be ``at least 4\-5 days''.
2633.pp
2634The
2635.b Timeout.queuewarn
2636value can be piggybacked on the
2637.b T
2638option by indicating a time after which
2639a warning message should be sent;
2640the two timeouts are separated by a slash.
2641For example, the line
2642.(b
2643OT5d/4h
2644.)b
2645causes email to fail after five days,
2646but a warning message will be sent after four hours.
2647This should be large enough that the message will have been tried
2648several times.
2649.sh 2 "Forking During Queue Runs"
2650.pp
2651By setting the
2652.b ForkEachJob
2653(\c
2654.b Y )
2655option,
2656.i sendmail
2657will fork before each individual message
2658while running the queue.
2659This option was used with earlier releases to prevent
2660.i sendmail
2661from consuming large amounts of memory.
2662It should no longer be necessary with
2663.i sendmail
26648.12.
2665If the
2666.b ForkEachJob
2667option is not set,
2668.i sendmail
2669will keep track of hosts that are down during a queue run,
2670which can improve performance dramatically.
2671.pp
2672If the
2673.b ForkEachJob
2674option is set,
2675.i sendmail
2676cannot use connection caching.
2677.sh 2 "Queue Priorities"
2678.pp
2679Every message is assigned a priority when it is first instantiated,
2680consisting of the message size (in bytes)
2681offset by the message class
2682(which is determined from the Precedence: header)
2683times the
2684.q "work class factor"
2685and the number of recipients times the
2686.q "work recipient factor."
2687The priority is used to order the queue.
2688Higher numbers for the priority mean that the message will be processed later
2689when running the queue.
2690.pp
2691The message size is included so that large messages are penalized
2692relative to small messages.
2693The message class allows users to send
2694.q "high priority"
2695messages by including a
2696.q Precedence:
2697field in their message;
2698the value of this field is looked up in the
2699.b P
2700lines of the configuration file.
2701Since the number of recipients affects the amount of load a message presents
2702to the system,
2703this is also included into the priority.
2704.pp
2705The recipient and class factors
2706can be set in the configuration file using the
2707.b RecipientFactor
2708(\c
2709.b y )
2710and
2711.b ClassFactor
2712(\c
2713.b z )
2714options respectively.
2715They default to 30000 (for the recipient factor)
2716and 1800
2717(for the class factor).
2718The initial priority is:
2719.EQ
2720pri = msgsize - (class times bold ClassFactor) + (nrcpt times bold RecipientFactor)
2721.EN
2722(Remember, higher values for this parameter actually mean
2723that the job will be treated with lower priority.)
2724.pp
2725The priority of a job can also be adjusted each time it is processed
2726(that is, each time an attempt is made to deliver it)
2727using the
2728.q "work time factor,"
2729set by the
2730.b RetryFactor
2731(\c
2732.b Z )
2733option.
2734This is added to the priority,
2735so it normally decreases the precedence of the job,
2736on the grounds that jobs that have failed many times
2737will tend to fail again in the future.
2738The
2739.b RetryFactor
2740option defaults to 90000.
2741.sh 2 "Load Limiting"
2742.pp
2743.i Sendmail
2744can be asked to queue (but not deliver) mail
2745if the system load average gets too high using the
2746.b QueueLA
2747(\c
2748.b x )
2749option.
2750When the load average exceeds the value of the
2751.b QueueLA
2752option, the delivery mode is set to
2753.b q
2754(queue only) if the
2755.b QueueFactor
2756(\c
2757.b q )
2758option divided by the difference in the current load average and the
2759.b QueueLA
2760option plus one
2761is less than the priority of the message \(em
2762that is, the message is queued iff:
2763.EQ
2764pri > { bold QueueFactor } over { LA - { bold QueueLA } + 1 }
2765.EN
2766The
2767.b QueueFactor
2768option defaults to 600000,
2769so each point of load average is worth 600000 priority points
2770(as described above).
2771.pp
2772For drastic cases, the
2773.b RefuseLA
2774(\c
2775.b X )
2776option defines a load average at which
2777.i sendmail
2778will refuse to accept network connections.
2779Locally generated mail, i.e., mail which is not submitted via SMTP
2780(including incoming UUCP mail),
2781is still accepted.
2782Notice that the MSP submits mail to the MTA via SMTP, and hence
2783mail will be queued in the client queue in such a case.
2784Therefore it is necessary to run the client mail queue periodically.
2785.sh 2 "Resource Limits"
2786.pp
2787.i Sendmail
2788has several parameters to control resource usage.
2789Besides those mentionted in the previous section, there are at least
2790.b MaxDaemonChildren ,
2791.b ConnectionRateThrottle ,
2792.b MaxQueueChildren ,
2793and
2794.b MaxRunnersPerQueue .
2795The latter two limit the number of
2796.i sendmail
2797processes that operate on the queue.
2798These are discussed in the section
2799``Queue Group Declaration''.
2800The former two can be used to limit the number of incoming connections.
2801Their appropriate values depend on the host operating system and
2802the hardware, e.g., amount of memory.
2803In many situations it might be useful to set limits to prevent
2804to have too many
2805.i sendmail
2806processes, however, these limits can be abused to mount a
2807denial of service attack.
2808For example, if
2809.b MaxDaemonChildren=10
2810then an attacker needs to open only 10 SMTP sessions to the server,
2811leave them idle for most of the time,
2812and no more connections will be accepted.
2813.sh 2 "Delivery Mode"
2814.pp
2815There are a number of delivery modes that
2816.i sendmail
2817can operate in,
2818set by the
2819.b DeliveryMode
2820(\c
2821.b d )
2822configuration option.
2823These modes
2824specify how quickly mail will be delivered.
2825Legal modes are:
2826.(b
2827.ta 4n
2828i deliver interactively (synchronously)
2829b deliver in background (asynchronously)
2830q queue only (don't deliver)
2831d defer delivery attempts (don't deliver)
2832.)b
2833There are tradeoffs.
2834Mode
2835.q i
2836gives the sender the quickest feedback,
2837but may slow down some mailers and
2838is hardly ever necessary.
2839Mode
2840.q b
2841delivers promptly but
2842can cause large numbers of processes
2843if you have a mailer that takes a long time to deliver a message.
2844Mode
2845.q q
2846minimizes the load on your machine,
2847but means that delivery may be delayed for up to the queue interval.
2848Mode
2849.q d
2850is identical to mode
2851.q q
2852except that it also prevents lookups in maps including the
2853.b -D
2854flag from working during the initial queue phase;
2855it is intended for ``dial on demand'' sites where DNS lookups
2856might cost real money.
2857Some simple error messages
2858(e.g., host unknown during the SMTP protocol)
2859will be delayed using this mode.
2860Mode
2861.q b
2862is the usual default.
2863.pp
2864If you run in mode
2865.q q
2866(queue only),
2867.q d
2868(defer),
2869or
2870.q b
2871(deliver in background)
2872.i sendmail
2873will not expand aliases and follow .forward files
2874upon initial receipt of the mail.
2875This speeds up the response to RCPT commands.
2876Mode
2877.q i
2878should not be used by the SMTP server.
2879.sh 2 "Log Level"
2880.pp
2881The level of logging can be set for
2882.i sendmail .
2883The default using a standard configuration table is level 9.
2884The levels are as follows:
2885.nr ii 0.5i
2886.ip 0
2887Minimal logging.
2888.ip 1
2889Serious system failures and potential security problems.
2890.ip 2
2891Lost communications (network problems) and protocol failures.
2892.ip 3
2893Other serious failures, malformed addresses, transient forward/include
2894errors, connection timeouts.
2895.ip 4
2896Minor failures, out of date alias databases, connection rejections
2897via check_ rulesets.
2898.ip 5
2899Message collection statistics.
2900.ip 6
2901Creation of error messages,
2902VRFY and EXPN commands.
2903.ip 7
2904Delivery failures (host or user unknown, etc.).
2905.ip 8
2906Successful deliveries and alias database rebuilds.
2907.ip 9
2908Messages being deferred
2909(due to a host being down, etc.).
2910.ip 10
2911Database expansion (alias, forward, and userdb lookups)
2912and authentication information.
2913.ip 11
2914NIS errors and end of job processing.
2915.ip 12
2916Logs all SMTP connections.
2917.ip 13
2918Log bad user shells, files with improper permissions, and other
2919questionable situations.
2920.ip 14
2921Logs refused connections.
2922.ip 15
2923Log all incoming and outgoing SMTP commands.
2924.ip 20
2925Logs attempts to run locked queue files.
2926These are not errors,
2927but can be useful to note if your queue appears to be clogged.
2928.ip 30
2929Lost locks (only if using lockf instead of flock).
2930.lp
2931Additionally,
2932values above 64 are reserved for extremely verbose debugging output.
2933No normal site would ever set these.
2934.sh 2 "File Modes"
2935.pp
2936The modes used for files depend on what functionality you want
2937and the level of security you require.
2938In many cases
2939.i sendmail
2940does careful checking of the modes
2941of files and directories
2942to avoid accidental compromise;
2943if you want to make it possible to have group-writable support files
2944you may need to use the
2945.b DontBlameSendmail
2946option to turn off some of these checks.
2947.sh 3 "To suid or not to suid?"
2948.pp
2949.i Sendmail
2950is no longer installed
2951set-user-ID to root.
2952sendmail/SECURITY
2953explains how to configure and install
2954.i sendmail
2955without set-user-ID to root but set-group-ID
2956which is the default configuration starting with 8.12.
2957.pp
2958The daemon usually runs as root, unless other measures are taken.
2959At the point where
2960.i sendmail
2961is about to
2962.i exec \|(2)
2963a mailer,
2964it checks to see if the userid is zero (root);
2965if so,
2966it resets the userid and groupid to a default
2967(set by the
2968.b U=
2969equate in the mailer line;
2970if that is not set, the
2971.b DefaultUser
2972option is used).
2973This can be overridden
2974by setting the
2975.b S
2976flag to the mailer
2977for mailers that are trusted
2978and must be called as root.
2979However,
2980this will cause mail processing
2981to be accounted
2982(using
2983.i sa \|(8))
2984to root
2985rather than to the user sending the mail.
2986.pp
2987A middle ground is to set the
2988.b RunAsUser
2989option.
2990This causes
2991.i sendmail
2992to become the indicated user as soon as it has done the startup
2993that requires root privileges
2994(primarily, opening the
2995.sm SMTP
2996socket).
2997If you use
2998.b RunAsUser ,
2999the queue directory
3000(normally
3001.i /var/spool/mqueue )
3002should be owned by that user,
3003and all files and databases
3004(including user
3005.i \&.forward
3006files,
3007alias files,
3008:include: files,
3009and external databases)
3010must be readable by that user.
3011Also, since sendmail will not be able to change it's uid,
3012delivery to programs or files will be marked as unsafe,
3013e.g., undeliverable,
3014in
3015.i \&.forward ,
3016aliases,
3017and :include: files.
3018Administrators can override this by setting the
3019.b DontBlameSendmail
3020option to the setting
3021.b NonRootSafeAddr .
3022.b RunAsUser
3023is probably best suited for firewall configurations
3024that don't have regular user logins.
3025.sh 3 "Turning off security checks"
3026.pp
3027.i Sendmail
3028is very particular about the modes of files that it reads or writes.
3029For example, by default it will refuse to read most files
3030that are group writable
3031on the grounds that they might have been tampered with
3032by someone other than the owner;
3033it will even refuse to read files in group writable directories.
3034Also, sendmail will refuse to create a new aliases database in an
3035unsafe directory. You can get around this by manually creating the
3036database file as a trusted user ahead of time and then rebuilding the
3037aliases database with
3038.b newaliases .
3039.pp
3040If you are
3041.i quite
3042sure that your configuration is safe and you want
3043.i sendmail
3044to avoid these security checks,
3045you can turn off certain checks using the
3046.b DontBlameSendmail
3047option.
3048This option takes one or more names that disable checks.
3049In the descriptions that follow,
3050.q "unsafe directory"
3051means a directory that is writable by anyone other than the owner.
3052The values are:
3053.nr ii 0.5i
3054.ip Safe
3055No special handling.
3056.ip AssumeSafeChown
3057Assume that the
3058.i chown
3059system call is restricted to root.
3060Since some versions of UNIX permit regular users
3061to give away their files to other users on some filesystems,
3062.i sendmail
3063often cannot assume that a given file was created by the owner,
3064particularly when it is in a writable directory.
3065You can set this flag if you know that file giveaway is restricted
3066on your system.
3067.ip ClassFileInUnsafeDirPath
3068When reading class files (using the
3069.b F
3070line in the configuration file),
3071allow files that are in unsafe directories.
3072.ip DontWarnForwardFileInUnsafeDirPath
3073Prevent logging of
3074unsafe directory path warnings
3075for non-existent forward files.
3076.ip ErrorHeaderInUnsafeDirPath
3077Allow the file named in the
3078.b ErrorHeader
3079option to be in an unsafe directory.
3080.ip FileDeliveryToHardLink
3081Allow delivery to files that are hard links.
3082.ip FileDeliveryToSymLink
3083Allow delivery to files that are symbolic links.
3084.ip ForwardFileInGroupWritableDirPath
3085Allow
3086.i \&.forward
3087files in group writable directories.
3088.ip ForwardFileInUnsafeDirPath
3089Allow
3090.i \&.forward
3091files in unsafe directories.
3092.ip ForwardFileInUnsafeDirPathSafe
3093Allow a
3094.i \&.forward
3095file that is in an unsafe directory to include references
3096to program and files.
3097.ip GroupReadableKeyFile
3098Accept a group-readable key file for STARTTLS.
3099.ip GroupReadableSASLDBFile
3100Accept a group-readable Cyrus SASL password file.
3101.ip GroupWritableAliasFile
3102Allow group-writable alias files.
3103.ip GroupWritableDirPathSafe
3104Change the definition of
3105.q "unsafe directory"
3106to consider group-writable directories to be safe.
3107World-writable directories are always unsafe.
3108.ip GroupWritableForwardFile
3109Allow group writable
3110.i \&.forward
3111files.
3112.ip GroupWritableForwardFileSafe
3113Accept group-writable
3114.i \&.forward
3115files as safe for program and file delivery.
3116.ip GroupWritableIncludeFile
3117Allow group wriable
3118.i :include:
3119files.
3120.ip GroupWritableIncludeFileSafe
3121Accept group-writable
3122.i :include:
3123files as safe for program and file delivery.
3124.ip GroupWritableSASLDBFile
3125Accept a group-writable Cyrus SASL password file.
3126.ip HelpFileInUnsafeDirPath
3127Allow the file named in the
3128.b HelpFile
3129option to be in an unsafe directory.
3130.ip IncludeFileInGroupWritableDirPath
3131Allow
3132.i :include:
3133files in group writable directories.
3134.ip IncludeFileInUnsafeDirPath
3135Allow
3136.i :include:
3137files in unsafe directories.
3138.ip IncludeFileInUnsafeDirPathSafe
3139Allow a
3140.i :include:
3141file that is in an unsafe directory to include references
3142to program and files.
3143.ip InsufficientEntropy
3144Try to use STARTTLS even if the PRNG for OpenSSL is not properly seeded
3145despite the security problems.
3146.ip LinkedAliasFileInWritableDir
3147Allow an alias file that is a link in a writable directory.
3148.ip LinkedClassFileInWritableDir
3149Allow class files that are links in writable directories.
3150.ip LinkedForwardFileInWritableDir
3151Allow
3152.i \&.forward
3153files that are links in writable directories.
3154.ip LinkedIncludeFileInWritableDir
3155Allow
3156.i :include:
3157files that are links in writable directories.
3158.ip LinkedMapInWritableDir
3159Allow map files that are links in writable directories.
3160This includes alias database files.
3161.ip LinkedServiceSwitchFileInWritableDir
3162Allow the service switch file to be a link
3163even if the directory is writable.
3164.ip MapInUnsafeDirPath
3165Allow maps (e.g.,
3166.i hash ,
3167.i btree ,
3168and
3169.i dbm
3170files)
3171in unsafe directories.
3172This includes alias database files.
3173.ip NonRootSafeAddr
3174Do not mark file and program deliveries as unsafe
3175if sendmail is not running with root privileges.
3176.ip RunProgramInUnsafeDirPath
3177Run programs that are in writable directories without logging a warning.
3178.ip RunWritableProgram
3179Run programs that are group- or world-writable without logging a warning.
3180.ip TrustStickyBit
3181Allow group or world writable directories
3182if the sticky bit is set on the directory.
3183Do not set this on systems which do not honor
3184the sticky bit on directories.
3185.ip WorldWritableAliasFile
3186Accept world-writable alias files.
3187.ip WorldWritableForwardfile
3188Allow world writable
3189.i \&.forward
3190files.
3191.ip WorldWritableIncludefile
3192Allow world wriable
3193.i :include:
3194files.
3195.ip WriteMapToHardLink
3196Allow writes to maps that are hard links.
3197.ip WriteMapToSymLink
3198Allow writes to maps that are symbolic links.
3199.ip WriteStatsToHardLink
3200Allow the status file to be a hard link.
3201.ip WriteStatsToSymLink
3202Allow the status file to be a symbolic link.
3203.sh 2 "Connection Caching"
3204.pp
3205When processing the queue,
3206.i sendmail
3207will try to keep the last few open connections open
3208to avoid startup and shutdown costs.
3209This only applies to IPC connections.
3210.pp
3211When trying to open a connection
3212the cache is first searched.
3213If an open connection is found, it is probed to see if it is still active
3214by sending a
3215.sm RSET
3216command.
3217It is not an error if this fails;
3218instead, the connection is closed and reopened.
3219.pp
3220Two parameters control the connection cache.
3221The
3222.b ConnectionCacheSize
3223(\c
3224.b k )
3225option defines the number of simultaneous open connections
3226that will be permitted.
3227If it is set to zero,
3228connections will be closed as quickly as possible.
3229The default is one.
3230This should be set as appropriate for your system size;
3231it will limit the amount of system resources that
3232.i sendmail
3233will use during queue runs.
3234Never set this higher than 4.
3235.pp
3236The
3237.b ConnectionCacheTimeout
3238(\c
3239.b K )
3240option specifies the maximum time that any cached connection
3241will be permitted to idle.
3242When the idle time exceeds this value
3243the connection is closed.
3244This number should be small
3245(under ten minutes)
3246to prevent you from grabbing too many resources
3247from other hosts.
3248The default is five minutes.
3249.sh 2 "Name Server Access"
3250.pp
3251Control of host address lookups is set by the
3252.b hosts
3253service entry in your service switch file.
3254If you are on a system that has built-in service switch support
3255(e.g., Ultrix, Solaris, or DEC OSF/1)
3256then your system is probably configured properly already.
3257Otherwise,
3258.i sendmail
3259will consult the file
3260.b /etc/mail/service.switch ,
3261which should be created.
3262.i Sendmail
3263only uses two entries:
3264.b hosts
3265and
3266.b aliases ,
3267although system routines may use other services
3268(notably the
3269.b passwd
3270service for user name lookups by
3271.i getpwname ).
3272.pp
3273However, some systems (such as SunOS 4.X)
3274will do DNS lookups
3275regardless of the setting of the service switch entry.
3276In particular, the system routine
3277.i gethostbyname (3)
3278is used to look up host names,
3279and many vendor versions try some combination of DNS, NIS,
3280and file lookup in /etc/hosts
3281without consulting a service switch.
3282.i Sendmail
3283makes no attempt to work around this problem,
3284and the DNS lookup will be done anyway.
3285If you do not have a nameserver configured at all,
3286such as at a UUCP-only site,
3287.i sendmail
3288will get a
3289.q "connection refused"
3290message when it tries to connect to the name server.
3291If the
3292.b hosts
3293switch entry has the service
3294.q dns
3295listed somewhere in the list,
3296.i sendmail
3297will interpret this to mean a temporary failure
3298and will queue the mail for later processing;
3299otherwise, it ignores the name server data.
3300.pp
3301The same technique is used to decide whether to do MX lookups.
3302If you want MX support, you
3303.i must
3304have
3305.q dns
3306listed as a service in the
3307.b hosts
3308switch entry.
3309.pp
3310The
3311.b ResolverOptions
3312(\c
3313.b I )
3314option allows you to tweak name server options.
3315The command line takes a series of flags as documented in
3316.i resolver (3)
3317(with the leading
3318.q RES_
3319deleted).
3320Each can be preceded by an optional `+' or `\(mi'.
3321For example, the line
3322.(b
3323O ResolverOptions=+AAONLY \(miDNSRCH
3324.)b
3325turns on the AAONLY (accept authoritative answers only)
3326and turns off the DNSRCH (search the domain path) options.
3327Most resolver libraries default DNSRCH, DEFNAMES, and RECURSE
3328flags on and all others off.
3329If NETINET6 is enabled, most libraries default to USE_INET6 as well.
3330You can also include
3331.q HasWildcardMX
3332to specify that there is a wildcard MX record matching your domain;
3333this turns off MX matching when canonifying names,
3334which can lead to inappropriate canonifications.
3335Use
3336.q WorkAroundBrokenAAAA
3337when faced with a a broken nameservers that returns SERVFAIL
3338(a temporary failure)
3339on T_AAAA (IPv6) lookups
3340during hostname canonification.
3341Notice: it might be necessary to apply the same (or similar) options to
3342.i submit.cf
3343too.
3344.pp
3345Version level 1 configurations (see the section about
3346Configuration Version Level)
3347turn DNSRCH and DEFNAMES off when doing delivery lookups,
3348but leave them on everywhere else.
3349Version 8 of
3350.i sendmail
3351ignores them when doing canonification lookups
3352(that is, when using $[ ... $]),
3353and always does the search.
3354If you don't want to do automatic name extension,
3355don't call $[ ... $].
3356.pp
3357The search rules for $[ ... $] are somewhat different than usual.
3358If the name being looked up
3359has at least one dot, it always tries the unmodified name first.
3360If that fails, it tries the reduced search path,
3361and lastly tries the unmodified name
3362(but only for names without a dot,
3363since names with a dot have already been tried).
3364This allows names such as
3365``utc.CS''
3366to match the site in Czechoslovakia
3367rather than the site in your local Computer Science department.
3368It also prefers A and CNAME records over MX records \*-
3369that is, if it finds an MX record it makes note of it,
3370but keeps looking.
3371This way, if you have a wildcard MX record matching your domain,
3372it will not assume that all names match.
3373.pp
3374To completely turn off all name server access
3375on systems without service switch support
3376(such as SunOS 4.X)
3377you will have to recompile with
3378\-DNAMED_BIND=0
3379and remove \-lresolv from the list of libraries to be searched
3380when linking.
3381.sh 2 "Moving the Per-User Forward Files"
3382.pp
3383Some sites mount each user's home directory
3384from a local disk on their workstation,
3385so that local access is fast.
3386However, the result is that .forward file lookups
3387from a central mail server are slow.
3388In some cases,
3389mail can even be delivered on machines inappropriately
3390because of a file server being down.
3391The performance can be especially bad if you run the automounter.
3392.pp
3393The
3394.b ForwardPath
3395(\c
3396.b J )
3397option allows you to set a path of forward files.
3398For example, the config file line
3399.(b
3400O ForwardPath=/var/forward/$u:$z/.forward.$w
3401.)b
3402would first look for a file with the same name as the user's login
3403in /var/forward;
3404if that is not found (or is inaccessible)
3405the file
3406``.forward.\c
3407.i machinename ''
3408in the user's home directory is searched.
3409A truly perverse site could also search by sender
3410by using $r, $s, or $f.
3411.pp
3412If you create a directory such as /var/forward,
3413it should be mode 1777
3414(that is, the sticky bit should be set).
3415Users should create the files mode 0644.
3416Note that you must use the
3417ForwardFileInUnsafeDirPath and
3418ForwardFileInUnsafeDirPathSafe
3419flags with the
3420.b DontBlameSendmail
3421option to allow forward files in a world writable directory.
3422This might also be used as a denial of service attack
3423(users could create forward files for other users);
3424a better approach might be to create
3425/var/forward
3426mode 0755
3427and create empty files for each user,
3428owned by that user,
3429mode 0644.
3430If you do this, you don't have to set the DontBlameSendmail options
3431indicated above.
3432.sh 2 "Free Space"
3433.pp
3434On systems that have one of the system calls in the
3435.i statfs (2)
3436family
3437(including
3438.i statvfs
3439and
3440.i ustat ),
3441you can specify a minimum number of free blocks on the queue filesystem
3442using the
3443.b MinFreeBlocks
3444(\c
3445.b b )
3446option.
3447If there are fewer than the indicated number of blocks free
3448on the filesystem on which the queue is mounted
3449the SMTP server will reject mail
3450with the
3451452 error code.
3452This invites the SMTP client to try again later.
3453.pp
3454Beware of setting this option too high;
3455it can cause rejection of email
3456when that mail would be processed without difficulty.
3457.sh 2 "Maximum Message Size"
3458.pp
3459To avoid overflowing your system with a large message,
3460the
3461.b MaxMessageSize
3462option can be set to set an absolute limit
3463on the size of any one message.
3464This will be advertised in the ESMTP dialogue
3465and checked during message collection.
3466.sh 2 "Privacy Flags"
3467.pp
3468The
3469.b PrivacyOptions
3470(\c
3471.b p )
3472option allows you to set certain
3473``privacy''
3474flags.
3475Actually, many of them don't give you any extra privacy,
3476rather just insisting that client SMTP servers
3477use the HELO command
3478before using certain commands
3479or adding extra headers to indicate possible spoof attempts.
3480.pp
3481The option takes a series of flag names;
3482the final privacy is the inclusive or of those flags.
3483For example:
3484.(b
3485O PrivacyOptions=needmailhelo, noexpn
3486.)b
3487insists that the HELO or EHLO command be used before a MAIL command is accepted
3488and disables the EXPN command.
3489.pp
3490The flags are detailed in section
3491.\"XREF
34925.6.
3493.sh 2 "Send to Me Too"
3494.pp
3495Beginning with version 8.10,
3496.i sendmail
3497includes by default the (envelope) sender in any list expansions.
3498For example, if
3499.q matt
3500sends to a list that contains
3501.q matt
3502as one of the members he will get a copy of the message.
3503If the
3504.b MeToo
3505option is set to
3506.sm FALSE
3507(in the configuration file or via the command line),
3508this behavior is changed, i.e.,
3509the (envelope) sender is excluded in list expansions.
3510.sh 1 "THE WHOLE SCOOP ON THE CONFIGURATION FILE"
3511.pp
3512This section describes the configuration file
3513in detail.
3514.pp
3515There is one point that should be made clear immediately:
3516the syntax of the configuration file
3517is designed to be reasonably easy to parse,
3518since this is done every time
3519.i sendmail
3520starts up,
3521rather than easy for a human to read or write.
3522The configuration file should be generated via the method described in
3523.b cf/README ,
3524it should not be edited directly unless someone is familiar
3525with the internals of the syntax described here and it is
3526not possible to achieve the desired result via the default method.
3527.pp
3528The configuration file is organized as a series of lines,
3529each of which begins with a single character
3530defining the semantics for the rest of the line.
3531Lines beginning with a space or a tab
3532are continuation lines
3533(although the semantics are not well defined in many places).
3534Blank lines and lines beginning with a sharp symbol
3535(`#')
3536are comments.
3537.sh 2 "R and S \*- Rewriting Rules"
3538.pp
3539The core of address parsing
3540are the rewriting rules.
3541These are an ordered production system.
3542.i Sendmail
3543scans through the set of rewriting rules
3544looking for a match on the left hand side
3545(LHS)
3546of the rule.
3547When a rule matches,
3548the address is replaced by the right hand side
3549(RHS)
3550of the rule.
3551.pp
3552There are several sets of rewriting rules.
3553Some of the rewriting sets are used internally
3554and must have specific semantics.
3555Other rewriting sets
3556do not have specifically assigned semantics,
3557and may be referenced by the mailer definitions
3558or by other rewriting sets.
3559.pp
3560The syntax of these two commands are:
3561.(b F
3562.b S \c
3563.i n
3564.)b
3565Sets the current ruleset being collected to
3566.i n .
3567If you begin a ruleset more than once
3568it appends to the old definition.
3569.(b F
3570.b R \c
3571.i lhs
3572.i rhs
3573.i comments
3574.)b
3575The
3576fields must be separated
3577by at least one tab character;
3578there may be embedded spaces
3579in the fields.
3580The
3581.i lhs
3582is a pattern that is applied to the input.
3583If it matches,
3584the input is rewritten to the
3585.i rhs .
3586The
3587.i comments
3588are ignored.
3589.pp
3590Macro expansions of the form
3591.b $ \c
3592.i x
3593are performed when the configuration file is read.
3594A literal
3595.b $
3596can be included using
3597.b $$ .
3598Expansions of the form
3599.b $& \c
3600.i x
3601are performed at run time using a somewhat less general algorithm.
3602This is intended only for referencing internally defined macros
3603such as
3604.b $h
3605that are changed at runtime.
3606.sh 3 "The left hand side"
3607.pp
3608The left hand side of rewriting rules contains a pattern.
3609Normal words are simply matched directly.
3610Metasyntax is introduced using a dollar sign.
3611The metasymbols are:
3612.(b
3613.ta \w'\fB$=\fP\fIx\fP 'u
3614\fB$*\fP Match zero or more tokens
3615\fB$+\fP Match one or more tokens
3616\fB$\-\fP Match exactly one token
3617\fB$=\fP\fIx\fP Match any phrase in class \fIx\fP
3618\fB$~\fP\fIx\fP Match any word not in class \fIx\fP
3619.)b
3620If any of these match,
3621they are assigned to the symbol
3622.b $ \c
3623.i n
3624for replacement on the right hand side,
3625where
3626.i n
3627is the index in the LHS.
3628For example,
3629if the LHS:
3630.(b
3631$\-:$+
3632.)b
3633is applied to the input:
3634.(b
3635UCBARPA:eric
3636.)b
3637the rule will match, and the values passed to the RHS will be:
3638.(b
3639.ta 4n
3640$1 UCBARPA
3641$2 eric
3642.)b
3643.pp
3644Additionally, the LHS can include
3645.b $@
3646to match zero tokens.
3647This is
3648.i not
3649bound to a
3650.b $ \c
3651.i n
3652on the RHS, and is normally only used when it stands alone
3653in order to match the null input.
3654.sh 3 "The right hand side"
3655.pp
3656When the left hand side of a rewriting rule matches,
3657the input is deleted and replaced by the right hand side.
3658Tokens are copied directly from the RHS
3659unless they begin with a dollar sign.
3660Metasymbols are:
3661.(b
3662.ta \w'$#mailer\0\0\0'u
3663\fB$\fP\fIn\fP Substitute indefinite token \fIn\fP from LHS
3664\fB$[\fP\fIname\fP\fB$]\fP Canonicalize \fIname\fP
3665\fB$(\fP\fImap key\fP \fB$@\fP\fIarguments\fP \fB$:\fP\fIdefault\fP \fB$)\fP
3666 Generalized keyed mapping function
3667\fB$>\fP\fIn\fP \*(lqCall\*(rq ruleset \fIn\fP
3668\fB$#\fP\fImailer\fP Resolve to \fImailer\fP
3669\fB$@\fP\fIhost\fP Specify \fIhost\fP
3670\fB$:\fP\fIuser\fP Specify \fIuser\fP
3671.)b
3672.pp
3673The
3674.b $ \c
3675.i n
3676syntax substitutes the corresponding value from a
3677.b $+ ,
3678.b $\- ,
3679.b $* ,
3680.b $= ,
3681or
3682.b $~
3683match on the LHS.
3684It may be used anywhere.
3685.pp
3686A host name enclosed between
3687.b $[
3688and
3689.b $]
3690is looked up in the host database(s)
3691and replaced by the canonical name\**.
3692.(f
3693\**This is actually
3694completely equivalent
3695to $(host \fIhostname\fP$).
3696In particular, a
3697.b $:
3698default can be used.
3699.)f
3700For example,
3701.q $[ftp$]
3702might become
3703.q ftp.CS.Berkeley.EDU
3704and
3705.q $[[128.32.130.2]$]
3706would become
3707.q vangogh.CS.Berkeley.EDU.
3708.i Sendmail
3709recognizes its numeric IP address
3710without calling the name server
3711and replaces it with its canonical name.
3712.pp
3713The
3714.b $(
3715\&...
3716.b $)
3717syntax is a more general form of lookup;
3718it uses a named map instead of an implicit map.
3719If no lookup is found, the indicated
3720.i default
3721is inserted;
3722if no default is specified and no lookup matches,
3723the value is left unchanged.
3724The
3725.i arguments
3726are passed to the map for possible use.
3727.pp
3728The
3729.b $> \c
3730.i n
3731syntax
3732causes the remainder of the line to be substituted as usual
3733and then passed as the argument to ruleset
3734.i n .
3735The final value of ruleset
3736.i n
3737then becomes
3738the substitution for this rule.
3739The
3740.b $>
3741syntax expands everything after the ruleset name
3742to the end of the replacement string
3743and then passes that as the initial input to the ruleset.
3744Recursive calls are allowed.
3745For example,
3746.(b
3747$>0 $>3 $1
3748.)b
3749expands $1, passes that to ruleset 3, and then passes the result
3750of ruleset 3 to ruleset 0.
3751.pp
3752The
3753.b $#
3754syntax should
3755.i only
3756be used in ruleset zero,
3757a subroutine of ruleset zero,
3758or rulesets that return decisions (e.g., check_rcpt).
3759It causes evaluation of the ruleset to terminate immediately,
3760and signals to
3761.i sendmail
3762that the address has completely resolved.
3763The complete syntax for ruleset 0 is:
3764.(b
3765\fB$#\fP\fImailer\fP \fB$@\fP\fIhost\fP \fB$:\fP\fIuser\fP
3766.)b
3767This specifies the
3768{mailer, host, user}
37693-tuple necessary to direct the mailer.
3770If the mailer is local
3771the host part may be omitted\**.
3772.(f
3773\**You may want to use it for special
3774.q "per user"
3775extensions.
3776For example, in the address
3777.q jgm+foo@CMU.EDU ;
3778the
3779.q +foo
3780part is not part of the user name,
3781and is passed to the local mailer for local use.
3782.)f
3783The
3784.i mailer
3785must be a single word,
3786but the
3787.i host
3788and
3789.i user
3790may be multi-part.
3791If the
3792.i mailer
3793is the built-in IPC mailer,
3794the
3795.i host
3796may be a colon-separated list of hosts
3797that are searched in order for the first working address
3798(exactly like MX records).
3799The
3800.i user
3801is later rewritten by the mailer-specific envelope rewriting set
3802and assigned to the
3803.b $u
3804macro.
3805As a special case, if the mailer specified has the
3806.b F=@
3807flag specified
3808and the first character of the
3809.b $:
3810value is
3811.q @ ,
3812the
3813.q @
3814is stripped off, and a flag is set in the address descriptor
3815that causes sendmail to not do ruleset 5 processing.
3816.pp
3817Normally, a rule that matches is retried,
3818that is,
3819the rule loops until it fails.
3820A RHS may also be preceded by a
3821.b $@
3822or a
3823.b $:
3824to change this behavior.
3825A
3826.b $@
3827prefix causes the ruleset to return with the remainder of the RHS
3828as the value.
3829A
3830.b $:
3831prefix causes the rule to terminate immediately,
3832but the ruleset to continue;
3833this can be used to avoid continued application of a rule.
3834The prefix is stripped before continuing.
3835.pp
3836The
3837.b $@
3838and
3839.b $:
3840prefixes may precede a
3841.b $>
3842spec;
3843for example:
3844.(b
3845.ta 8n
3846R$+ $: $>7 $1
3847.)b
3848matches anything,
3849passes that to ruleset seven,
3850and continues;
3851the
3852.b $:
3853is necessary to avoid an infinite loop.
3854.pp
3855Substitution occurs in the order described,
3856that is,
3857parameters from the LHS are substituted,
3858hostnames are canonicalized,
3859.q subroutines
3860are called,
3861and finally
3862.b $# ,
3863.b $@ ,
3864and
3865.b $:
3866are processed.
3867.sh 3 "Semantics of rewriting rule sets"
3868.pp
3869There are six rewriting sets
3870that have specific semantics.
3871Five of these are related as depicted by figure 1.
3872.(z
3873.hl
3874.ie n \{\
3875.(c
3876 +---+
3877 -->| 0 |-->resolved address
3878 / +---+
3879 / +---+ +---+
3880 / ---->| 1 |-->| S |--
3881 +---+ / +---+ / +---+ +---+ \e +---+
3882addr-->| 3 |-->| D |-- --->| 4 |-->msg
3883 +---+ +---+ \e +---+ +---+ / +---+
3884 --->| 2 |-->| R |--
3885 +---+ +---+
3886.)c
3887
3888.\}
3889.el \{\
3890.ie !"\*(.T"" \{\
3891.PS
3892boxwid = 0.3i
3893boxht = 0.3i
3894movewid = 0.3i
3895moveht = 0.3i
3896linewid = 0.3i
3897lineht = 0.3i
3898
3899 box invis "addr"; arrow
3900Box3: box "3"
3901A1: arrow
3902BoxD: box "D"; line; L1: Here
3903C: [
3904 C1: arrow; box "1"; arrow; box "S"; line; E1: Here
3905 move to C1 down 0.5; right
3906 C2: arrow; box "2"; arrow; box "R"; line; E2: Here
3907 ] with .w at L1 + (0.5, 0)
3908 move to C.e right 0.5
3909L4: arrow; box "4"; arrow; box invis "msg"
3910 line from L1 to C.C1
3911 line from L1 to C.C2
3912 line from C.E1 to L4
3913 line from C.E2 to L4
3914 move to BoxD.n up 0.6; right
3915Box0: arrow; box "0"
3916 arrow; box invis "resolved address" width 1.3
3917 line from 1/3 of the way between A1 and BoxD.w to Box0
3918.PE
3919.\}
3920.el .sp 2i
3921.\}
3922.ce
3923Figure 1 \*- Rewriting set semantics
3924.(c
3925D \*- sender domain addition
3926S \*- mailer-specific sender rewriting
3927R \*- mailer-specific recipient rewriting
3928.)c
3929.hl
3930.)z
3931.pp
3932Ruleset three
3933should turn the address into
3934.q "canonical form."
3935This form should have the basic syntax:
3936.(b
3937local-part@host-domain-spec
3938.)b
3939Ruleset three
3940is applied by
3941.i sendmail
3942before doing anything with any address.
3943.pp
3944If no
3945.q @
3946sign is specified,
3947then the
3948host-domain-spec
3949.i may
3950be appended (box
3951.q D
3952in Figure 1)
3953from the
3954sender address
3955(if the
3956.b C
3957flag is set in the mailer definition
3958corresponding to the
3959.i sending
3960mailer).
3961.pp
3962Ruleset zero
3963is applied after ruleset three
3964to addresses that are going to actually specify recipients.
3965It must resolve to a
3966.i "{mailer, host, address}"
3967triple.
3968The
3969.i mailer
3970must be defined in the mailer definitions
3971from the configuration file.
3972The
3973.i host
3974is defined into the
3975.b $h
3976macro
3977for use in the argv expansion of the specified mailer.
3978.pp
3979Rulesets one and two
3980are applied to all sender and recipient addresses respectively.
3981They are applied before any specification
3982in the mailer definition.
3983They must never resolve.
3984.pp
3985Ruleset four is applied to all addresses
3986in the message.
3987It is typically used
3988to translate internal to external form.
3989.pp
3990In addition,
3991ruleset 5 is applied to all local addresses
3992(specifically, those that resolve to a mailer with the `F=5'
3993flag set)
3994that do not have aliases.
3995This allows a last minute hook for local names.
3996.sh 3 "Ruleset hooks"
3997.pp
3998A few extra rulesets are defined as
3999.q hooks
4000that can be defined to get special features.
4001They are all named rulesets.
4002The
4003.q check_*
4004forms all give accept/reject status;
4005falling off the end or returning normally is an accept,
4006and resolving to
4007.b $#error
4008is a reject.
4009Many of these can also resolve to the special mailer name
4010.b $#discard ;
4011this accepts the message as though it were successful
4012but then discards it without delivery.
4013Note,
4014this mailer cannot be chosen as a mailer in ruleset 0.
4015Note also that all
4016.q check_*
4017rulesets have to deal with temporary failures, especially for map lookups,
4018themselves, i.e., they should return a temporary error code
4019or at least they should make a proper decision in those cases.
4020.sh 4 "check_relay"
4021.pp
4022The
4023.i check_relay
4024ruleset is called after a connection is accepted by the daemon.
4025It is not called when sendmail is started using the
4026.b \-bs
4027option.
4028It is passed
4029.(b
4030client.host.name $| client.host.address
4031.)b
4032where
4033.b $|
4034is a metacharacter separating the two parts.
4035This ruleset can reject connections from various locations.
4036.sh 4 "check_mail"
4037.pp
4038The
4039.i check_mail
4040ruleset is passed the user name parameter of the
4041.sm "SMTP MAIL"
4042command.
4043It can accept or reject the address.
4044.sh 4 "check_rcpt"
4045.pp
4046The
4047.i check_rcpt
4048ruleset is passed the user name parameter of the
4049.sm "SMTP RCPT"
4050command.
4051It can accept or reject the address.
4052.sh 4 "check_data"
4053.pp
4054The
4055.i check_data
4056ruleset is called after the
4057.sm "SMTP DATA"
4058command, its parameter is the number of recipients.
4059It can accept or reject the command.
4060.sh 4 "check_compat"
4061.pp
4062The
4063.i check_compat
4064ruleset is passed
4065.(b
4066sender-address $| recipient-address
4067.)b
4068where
4069.b $|
4070is a metacharacter separating the addresses.
4071It can accept or reject mail transfer between these two addresses
4072much like the
4073.i checkcompat()
4074function.
4075.sh 4 "check_eoh"
4076.pp
4077The
4078.i check_eoh
4079ruleset is passed
4080.(b
4081number-of-headers $| size-of-headers
4082.)b
4083where
4084.b $|
4085is a metacharacter separating the numbers.
4086These numbers can be used for size comparisons with the
4087.b arith
4088map.
4089The ruleset is triggered after
4090all of the headers have been read.
4091It can be used to correlate information gathered
4092from those headers using the
4093.b macro
4094storage map.
4095One possible use is to check for a missing header.
4096For example:
4097.(b
4098.ta 1.5i
4099Kstorage macro
4100HMessage-Id: $>CheckMessageId
4101
4102SCheckMessageId
4103# Record the presence of the header
4104R$* $: $(storage {MessageIdCheck} $@ OK $) $1
4105R< $+ @ $+ > $@ OK
4106R$* $#error $: 553 Header Error
4107
4108Scheck_eoh
4109# Check the macro
4110R$* $: < $&{MessageIdCheck} >
4111# Clear the macro for the next message
4112R$* $: $(storage {MessageIdCheck} $) $1
4113# Has a Message-Id: header
4114R< $+ > $@ OK
4115# Allow missing Message-Id: from local mail
4116R$* $: < $&{client_name} >
4117R< > $@ OK
4118R< $=w > $@ OK
4119# Otherwise, reject the mail
4120R$* $#error $: 553 Header Error
4121.)b
4122Keep in mind the Message-Id: header is not a required header and
4123is not a guaranteed spam indicator.
4124This ruleset is an example and
4125should probably not be used in production.
4126.sh 4 "check_etrn"
4127.pp
4128The
4129.i check_etrn
4130ruleset is passed the parameter of the
4131.sm "SMTP ETRN"
4132command.
4133It can accept or reject the command.
4134.sh 4 "check_expn"
4135.pp
4136The
4137.i check_expn
4138ruleset is passed the user name parameter of the
4139.sm "SMTP EXPN"
4140command.
4141It can accept or reject the address.
4142.sh 4 "check_vrfy"
4143.pp
4144The
4145.i check_vrfy
4146ruleset is passed the user name parameter of the
4147.sm "SMTP VRFY"
4148command.
4149It can accept or reject the command.
4150.sh 4 "trust_auth"
4151.pp
4152The
4153.i trust_auth
4154ruleset is passed the AUTH= parameter of the
4155.sm "SMTP MAIL"
4156command.
4157It is used to determine whether this value should be
4158trusted. In order to make this decision, the ruleset
4159may make use of the various
4160.b ${auth_*}
4161macros.
4162If the ruleset does resolve to the
4163.q error
4164mailer the AUTH= parameter is not trusted and hence
4165not passed on to the next relay.
4166.sh 4 "tls_client"
4167.pp
4168The
4169.i tls_client
4170ruleset is called when sendmail acts as server, after a STARTTLS command
4171has been issued, and from
4172.i check_mail.
4173The parameter is the value of
4174.b ${verify}
4175and STARTTLS or MAIL, respectively.
4176If the ruleset does resolve to the
4177.q error
4178mailer, the appropriate error code is returned to the client.
4179.sh 4 "tls_server"
4180.pp
4181The
4182.i tls_server
4183ruleset is called when sendmail acts as client after a STARTTLS command
4184(should) have been issued.
4185The parameter is the value of
4186.b ${verify} .
4187If the ruleset does resolve to the
4188.q error
4189mailer, the connection is aborted
4190(treated as non-deliverable with a permanent or temporary error).
4191.sh 4 "tls_rcpt"
4192.pp
4193The
4194.i tls_rcpt
4195ruleset is called each time before a RCPT TO command is sent.
4196The parameter is the current recipient.
4197If the ruleset does resolve to the
4198.q error
4199mailer, the RCPT TO command is suppressed
4200(treated as non-deliverable with a permanent or temporary error).
4201This ruleset allows to require encryption or verification of
4202the recipient's MTA even if the mail is somehow redirected
4203to another host.
4204For example, sending mail to
4205.i luke@endmail.org
4206may get redirected to a host named
4207.i death.star
4208and hence the tls_server ruleset won't apply.
4209By introducing per recipient restrictions such attacks
4210(e.g., via DNS spoofing) can be made impossible.
4211See
4212.i cf/README
4213how this ruleset can be used.
4214.sh 4 "srv_features"
4215.pp
4216The
4217.i srv_features
4218ruleset is called when a client connects to sendmail.
4219This ruleset should return
4220.b $#
4221followed by a list of options (single characters
4222delimited by white space).
4223If the return value starts with anything else it is silently ignored.
4224Generally upper case characters turn off a feature
4225while lower case characters turn it on.
4226The option `S' causes the server not to offer STARTTLS.
4227This is useful to interact with MTAs/MUAs that have broken
4228STARTTLS implementations by simply not offering it.
4229`V' turns off the request for a client certificate
4230during the TLS handshake.
4231Option `A' and `P' suppress SMTP AUTH and PIPELINING, respectively.
4232The ruleset may return `$#temp' to indicate that there is a temporary
4233problem determining the correct features, e.g., if a map is unavailable.
4234In that case, the SMTP server issues a temporary failure and does not
4235accept email.
4236.sh 4 "try_tls"
4237.pp
4238The
4239.i try_tls
4240ruleset is called when sendmail connects to another MTA.
4241If the ruleset does resolve to the
4242.q error
4243mailer, sendmail does not try STARTTLS even if it is offered.
4244This is useful to interact with MTAs that have broken
4245STARTTLS implementations by simply not using it.
4246.sh 4 "authinfo"
4247.pp
4248The
4249.i authinfo
4250ruleset is called when sendmail tries to authenticate to another MTA.
4251It should return
4252.b $#
4253followed by a list of tokens that are used for SMTP AUTH.
4254If the return value starts with anything else it is silently ignored.
4255Each token is a tagged string of the form:
4256"TDstring"
4257(including the quotes), where
4258.(b
4259.ta 9n
4260T Tag which describes the item
4261D Delimiter: ':' simple text follows
4262 '=' string is base64 encoded
4263string Value of the item
4264.)b
4265Valid values for the tag are:
4266.(b
4267.ta 9n
4268U user (authorization) id
4269I authentication id
4270P password
4271R realm
4272M list of mechanisms delimited by spaces
4273.)b
4274If this ruleset is defined, the option
4275.b DefaultAuthInfo
4276is ignored (even if the ruleset does not return a ``useful'' result).
4277.sh 4 "queuegroup"
4278.pp
4279The
4280.i queuegroup
4281ruleset is used to map an address to a queue group name.
4282It should return
4283.b $#
4284followed by the name of a queue group.
4285If the return value starts with anything else it is silently ignored.
4286See the section about Queue Groups and Queue Directories
4287for further information.
4288.sh 3 "IPC mailers"
4289.pp
4290Some special processing occurs
4291if the ruleset zero resolves to an IPC mailer
4292(that is, a mailer that has
4293.q [IPC]
4294listed as the Path in the
4295.b M
4296configuration line.
4297The host name passed after
4298.q $@
4299has MX expansion performed if not delivering via a named socket;
4300this looks the name up in DNS to find alternate delivery sites.
4301.pp
4302The host name can also be provided as a dotted quad
4303or an IPv6 address in square brackets;
4304for example:
4305.(b
4306[128.32.149.78]
4307.)b
4308or
4309.(b
4310[IPv6:2002:c0a8:51d2::23f4]
4311.)b
4312This causes direct conversion of the numeric value
4313to an IP host address.
4314.pp
4315The host name passed in after the
4316.q $@
4317may also be a colon-separated list of hosts.
4318Each is separately MX expanded and the results are concatenated
4319to make (essentially) one long MX list.
4320The intent here is to create
4321.q fake
4322MX records that are not published in DNS
4323for private internal networks.
4324.pp
4325As a final special case, the host name can be passed in
4326as a text string
4327in square brackets:
4328.(b
4329[ucbvax.berkeley.edu]
4330.)b
4331This form avoids the MX mapping.
4332.b N.B.:
4333.i
4334This is intended only for situations where you have a network firewall
4335or other host that will do special processing for all your mail,
4336so that your MX record points to a gateway machine;
4337this machine could then do direct delivery to machines
4338within your local domain.
4339Use of this feature directly violates RFC 1123 section 5.3.5:
4340it should not be used lightly.
4341.r
4342.sh 2 "D \*- Define Macro"
4343.pp
4344Macros are named with a single character
4345or with a word in {braces}.
4346The names ``x'' and ``{x}'' denote the same macro
4347for every single character ``x''.
4348Single character names may be selected from the entire ASCII set,
4349but user-defined macros
4350should be selected from the set of upper case letters only.
4351Lower case letters
4352and special symbols
4353are used internally.
4354Long names beginning with a lower case letter or a punctuation character
4355are reserved for use by sendmail,
4356so user-defined long macro names should begin with an upper case letter.
4357.pp
4358The syntax for macro definitions is:
4359.(b F
4360.b D \c
4361.i x\|val
4362.)b
4363where
4364.i x
4365is the name of the macro
4366(which may be a single character
4367or a word in braces)
4368and
4369.i val
4370is the value it should have.
4371There should be no spaces given
4372that do not actually belong in the macro value.
4373.pp
4374Macros are interpolated
4375using the construct
4376.b $ \c
4377.i x ,
4378where
4379.i x
4380is the name of the macro to be interpolated.
4381This interpolation is done when the configuration file is read,
4382except in
4383.b M
4384lines.
4385The special construct
4386.b $& \c
4387.i x
4388can be used in
4389.b R
4390lines to get deferred interpolation.
4391.pp
4392Conditionals can be specified using the syntax:
4393.(b
4394$?x text1 $| text2 $.
4395.)b
4396This interpolates
4397.i text1
4398if the macro
4399.b $x
4400is set and non-null,
4401and
4402.i text2
4403otherwise.
4404The
4405.q else
4406(\c
4407.b $| )
4408clause may be omitted.
4409.pp
4410The following macros are defined and/or used internally by
4411.i sendmail
4412for interpolation into argv's for mailers
4413or for other contexts.
4414The ones marked \(dg are information passed into sendmail\**,
4415.(f
4416\**As of version 8.6,
4417all of these macros have reasonable defaults.
4418Previous versions required that they be defined.
4419.)f
4420the ones marked \(dd are information passed both in and out of sendmail,
4421and the unmarked macros are passed out of sendmail
4422but are not otherwise used internally.
4423These macros are:
4424.nr ii 5n
4425.ip $a
4426The origination date in RFC 822 format.
4427This is extracted from the Date: line.
4428.ip $b
4429The current date in RFC 822 format.
4430.ip $c
4431The hop count.
4432This is a count of the number of Received: lines
4433plus the value of the
4434.b \-h
4435command line flag.
4436.ip $d
4437The current date in UNIX (ctime) format.
4438.ip $e\(dg
4439(Obsolete; use SmtpGreetingMessage option instead.)
4440The SMTP entry message.
4441This is printed out when SMTP starts up.
4442The first word must be the
4443.b $j
4444macro as specified by RFC 821.
4445Defaults to
4446.q "$j Sendmail $v ready at $b" .
4447Commonly redefined to include the configuration version number, e.g.,
4448.q "$j Sendmail $v/$Z ready at $b"
4449.ip $f
4450The envelope sender (from) address.
4451.ip $g
4452The sender address relative to the recipient.
4453For example, if
4454.b $f
4455is
4456.q foo ,
4457.b $g
4458will be
4459.q host!foo ,
4460.q foo@host.domain ,
4461or whatever is appropriate for the receiving mailer.
4462.ip $h
4463The recipient host.
4464This is set in ruleset 0 from the $@ field of a parsed address.
4465.ip $i
4466The queue id,
4467e.g.,
4468.q f344MXxp018717 .
4469.ip $j\(dd
4470The \*(lqofficial\*(rq domain name for this site.
4471This is fully qualified if the full qualification can be found.
4472It
4473.i must
4474be redefined to be the fully qualified domain name
4475if your system is not configured so that information can find
4476it automatically.
4477.ip $k
4478The UUCP node name (from the uname system call).
4479.ip $l\(dg
4480(Obsolete; use UnixFromLine option instead.)
4481The format of the UNIX from line.
4482Unless you have changed the UNIX mailbox format,
4483you should not change the default,
4484which is
4485.q "From $g $d" .
4486.ip $m
4487The domain part of the \fIgethostname\fP return value.
4488Under normal circumstances,
4489.b $j
4490is equivalent to
4491.b $w.$m .
4492.ip $n\(dg
4493The name of the daemon (for error messages).
4494Defaults to
4495.q MAILER-DAEMON .
4496.ip $o\(dg
4497(Obsolete: use OperatorChars option instead.)
4498The set of \*(lqoperators\*(rq in addresses.
4499A list of characters
4500which will be considered tokens
4501and which will separate tokens
4502when doing parsing.
4503For example, if
4504.q @
4505were in the
4506.b $o
4507macro, then the input
4508.q a@b
4509would be scanned as three tokens:
4510.q a,
4511.q @,
4512and
4513.q b.
4514Defaults to
4515.q ".:@[]" ,
4516which is the minimum set necessary to do RFC 822 parsing;
4517a richer set of operators is
4518.q ".:%@!/[]" ,
4519which adds support for UUCP, the %-hack, and X.400 addresses.
4520.ip $p
4521Sendmail's process id.
4522.ip $q\(dg
4523Default format of sender address.
4524The
4525.b $q
4526macro specifies how an address should appear in a message
4527when it is defaulted.
4528Defaults to
4529.q "<$g>" .
4530It is commonly redefined to be
4531.q "$?x$x <$g>$|$g$."
4532or
4533.q "$g$?x ($x)$." ,
4534corresponding to the following two formats:
4535.(b
4536Eric Allman <eric@CS.Berkeley.EDU>
4537eric@CS.Berkeley.EDU (Eric Allman)
4538.)b
4539.i Sendmail
4540properly quotes names that have special characters
4541if the first form is used.
4542.ip $r
4543Protocol used to receive the message.
4544Set from the
4545.b \-p
4546command line flag or by the SMTP server code.
4547.ip $s
4548Sender's host name.
4549Set from the
4550.b \-p
4551command line flag or by the SMTP server code.
4552.ip $t
4553A numeric representation of the current time.
4554.ip $u
4555The recipient user.
4556.ip $v
4557The version number of the
4558.i sendmail
4559binary.
4560.ip $w\(dd
4561The hostname of this site.
4562This is the root name of this host (but see below for caveats).
4563.ip $x
4564The full name of the sender.
4565.ip $z
4566The home directory of the recipient.
4567.ip $_
4568The validated sender address.
4569See also
4570.b ${client_resolve} .
4571.ip ${addr_type}
4572The type of the address which is currently being rewritten.
4573This macro contains up to three characters, the first
4574is either `e' or `h' for envelope/header address,
4575the second is a space,
4576and the third is either `s' or `r' for sender/recipient address.
4577Notice: for header addresses no distinction is currently made
4578between sender and recipient addresses, i.e., the macro contains
4579only `h'.
| 92.rm Ve
93.sp
94For Sendmail Version 8.12
95.)l
96.(f
97Sendmail is a trademark of Sendmail, Inc.
98.)f
99.sp 2
100.pp
101.i Sendmail \u\s-2TM\s0\d
102implements a general purpose internetwork mail routing facility
103under the UNIX\(rg
104operating system.
105It is not tied to any one transport protocol \*-
106its function may be likened to a crossbar switch,
107relaying messages from one domain into another.
108In the process,
109it can do a limited amount of message header editing
110to put the message into a format that is appropriate
111for the receiving domain.
112All of this is done under the control of a configuration file.
113.pp
114Due to the requirements of flexibility
115for
116.i sendmail ,
117the configuration file can seem somewhat unapproachable.
118However, there are only a few basic configurations
119for most sites,
120for which standard configuration files have been supplied.
121Most other configurations
122can be built by adjusting an existing configuration file
123incrementally.
124.pp
125.i Sendmail
126is based on
127RFC 821 (Simple Mail Transport Protocol),
128RFC 822 (Internet Mail Headers Format),
129RFC 974 (MX routing),
130RFC 1123 (Internet Host Requirements),
131RFC 1413 (Identification server),
132RFC 1652 (SMTP 8BITMIME Extension),
133RFC 1869 (SMTP Service Extensions),
134RFC 1870 (SMTP SIZE Extension),
135RFC 1891 (SMTP Delivery Status Notifications),
136RFC 1892 (Multipart/Report),
137RFC 1893 (Enhanced Mail System Status Codes),
138RFC 1894 (Delivery Status Notifications),
139RFC 1985 (SMTP Service Extension for Remote Message Queue Starting),
140RFC 2033 (Local Message Transmission Protocol),
141RFC 2034 (SMTP Service Extension for Returning Enhanced Error Codes),
142RFC 2045 (MIME),
143RFC 2476 (Message Submission),
144RFC 2487 (SMTP Service Extension for Secure SMTP over TLS),
145RFC 2554 (SMTP Service Extension for Authentication),
146RFC 2821 (Simple Mail Transfer Protocol),
147RFC 2822 (Internet Message Format),
148RFC 2852 (Deliver By SMTP Service Extension),
149and
150RFC 2920 (SMTP Service Extension for Command Pipelining).
151However, since
152.i sendmail
153is designed to work in a wider world,
154in many cases it can be configured to exceed these protocols.
155These cases are described herein.
156.pp
157Although
158.i sendmail
159is intended to run
160without the need for monitoring,
161it has a number of features
162that may be used to monitor or adjust the operation
163under unusual circumstances.
164These features are described.
165.pp
166Section one describes how to do a basic
167.i sendmail
168installation.
169Section two
170explains the day-to-day information you should know
171to maintain your mail system.
172If you have a relatively normal site,
173these two sections should contain sufficient information
174for you to install
175.i sendmail
176and keep it happy.
177Section three
178has information regarding the command line arguments.
179Section four
180describes some parameters that may be safely tweaked.
181Section five
182contains the nitty-gritty information about the configuration
183file.
184This section is for masochists
185and people who must write their own configuration file.
186Section six
187describes configuration that can be done at compile time.
188The appendixes give a brief
189but detailed explanation of a number of features
190not described in the rest of the paper.
191.bp 7
192.sh 1 "BASIC INSTALLATION"
193.pp
194There are two basic steps to installing
195.i sendmail .
196First, you have to compile and install the binary.
197If
198.i sendmail
199has already been ported to your operating system
200that should be simple.
201Second, you must build a run-time configuration file.
202This is a file that
203.i sendmail
204reads when it starts up
205that describes the mailers it knows about,
206how to parse addresses,
207how to rewrite the message header,
208and the settings of various options.
209Although the configuration file can be quite complex,
210a configuration can usually be built
211using an M4-based configuration language.
212Assuming you have the standard
213.i sendmail
214distribution, see
215.i cf/README
216for further information.
217.pp
218The remainder of this section will describe the installation of
219.i sendmail
220assuming you can use one of the existing configurations
221and that the standard installation parameters are acceptable.
222All pathnames and examples
223are given from the root of the
224.i sendmail
225subtree,
226normally
227.i /usr/src/usr.\*(SD/sendmail
228on 4.4BSD-based systems.
229.pp
230Continue with the next section if you need/want to compile
231.i sendmail
232yourself.
233If you have a running binary already on your system,
234you should probably skip to section 1.2.
235.sh 2 "Compiling Sendmail"
236.pp
237All
238.i sendmail
239source is in the
240.i sendmail
241subdirectory.
242To compile sendmail,
243.q cd
244into the
245.i sendmail
246directory and type
247.(b
248\&./Build
249.)b
250This will leave the binary in an appropriately named subdirectory,
251e.g.,
252obj.BSD-OS.2.1.i386.
253It works for multiple object versions
254compiled out of the same directory.
255.sh 3 "Tweaking the Build Invocation"
256.pp
257You can give parameters on the
258.i Build
259command.
260In most cases these are only used when the
261.i obj.*
262directory is first created.
263To restart from scratch, use
264.i -c .
265These commands include:
266.nr ii 0.5i
267.ip "\-L \fIlibdirs\fP"
268A list of directories to search for libraries.
269.ip "\-I \fIincdirs\fP"
270A list of directories to search for include files.
271.ip "\-E \fIenvar\fP=\fIvalue\fP"
272Set an environment variable to an indicated
273.i value
274before compiling.
275.ip "\-c"
276Create a new
277.i obj.*
278tree before running.
279.ip "\-f \fIsiteconfig\fP"
280Read the indicated site configuration file.
281If this parameter is not specified,
282.i Build
283includes
284.i all
285of the files
286.i $BUILDTOOLS/Site/site.$oscf.m4
287and
288.i $BUILDTOOLS/Site/site.config.m4 ,
289where $BUILDTOOLS is normally
290.i \&../devtools
291and $oscf is the same name as used on the
292.i obj.*
293directory.
294See below for a description of the site configuration file.
295.ip "\-S"
296Skip auto-configuration.
297.i Build
298will avoid auto-detecting libraries if this is set.
299All libraries and map definitions must be specified
300in the site configuration file.
301.lp
302Most other parameters are passed to the
303.i make
304program; for details see
305.i $BUILDTOOLS/README .
306.sh 3 "Creating a Site Configuration File"
307.\"XXX
308.pp
309(This section is not yet complete.
310For now, see the file devtools/README for details.)
311See sendmail/README for various compilation flags that can be set.
312.sh 3 "Tweaking the Makefile"
313.pp
314.\" .b "XXX This should all be in the Site Configuration File section."
315.i Sendmail
316supports two different formats
317for the local (on disk) version of databases,
318notably the
319.i aliases
320database.
321At least one of these should be defined if at all possible.
322.nr ii 1i
323.ip NDBM
324The ``new DBM'' format,
325available on nearly all systems around today.
326This was the preferred format prior to 4.4BSD.
327It allows such complex things as multiple databases
328and closing a currently open database.
329.ip NEWDB
330The Berkeley DB package.
331If you have this, use it.
332It allows
333long records,
334multiple open databases,
335real in-memory caching,
336and so forth.
337You can define this in conjunction with
338.sm NDBM ;
339if you do,
340old alias databases are read,
341but when a new database is created it will be in NEWDB format.
342As a nasty hack,
343if you have NEWDB, NDBM, and NIS defined,
344and if the alias file name includes the substring
345.q /yp/ ,
346.i sendmail
347will create both new and old versions of the alias file
348during a
349.i newalias
350command.
351This is required because the Sun NIS/YP system
352reads the DBM version of the alias file.
353It's ugly as sin,
354but it works.
355.lp
356If neither of these are defined,
357.i sendmail
358reads the alias file into memory on every invocation.
359This can be slow and should be avoided.
360There are also several methods for remote database access:
361.ip LDAP
362Lightweight Directory Access Protocol.
363.ip NIS
364Sun's Network Information Services (formerly YP).
365.ip NISPLUS
366Sun's NIS+ services.
367.ip NETINFO
368NeXT's NetInfo service.
369.ip HESIOD
370Hesiod service (from Athena).
371.lp
372Other compilation flags are set in
373.i conf.h
374and should be predefined for you
375unless you are porting to a new environment.
376For more options see
377.i sendmail/README .
378.sh 3 "Compilation and installation"
379.pp
380After making the local system configuration described above,
381You should be able to compile and install the system.
382The script
383.q Build
384is the best approach on most systems:
385.(b
386\&./Build
387.)b
388This will use
389.i uname (1)
390to create a custom Makefile for your environment.
391.pp
392If you are installing in the standard places,
393you should be able to install using
394.(b
395\&./Build install
396.)b
397This should install the binary in
398/usr/\*(SD
399and create links from
400/usr/\*(SB/newaliases
401and
402/usr/\*(SB/mailq
403to
404/usr/\*(SD/sendmail.
405On most systems it will also format and install man pages.
406Notice: as of version 8.12
407.i sendmail
408will no longer be installed set-user-ID root by default.
409If you really want to use the old method, you can specify it as target:
410.(b
411\&./Build install-set-user-id
412.)b
413.sh 2 "Configuration Files"
414.pp
415.i Sendmail
416cannot operate without a configuration file.
417The configuration defines the mail delivery mechanisms understood at this site,
418how to access them,
419how to forward email to remote mail systems,
420and a number of tuning parameters.
421This configuration file is detailed
422in the later portion of this document.
423.pp
424The
425.i sendmail
426configuration can be daunting at first.
427The world is complex,
428and the mail configuration reflects that.
429The distribution includes an m4-based configuration package
430that hides a lot of the complexity.
431See
432.i cf/README
433for details.
434.pp
435Our configuration files are processed by
436.i m4
437to facilitate local customization;
438the directory
439.i cf
440of the
441.i sendmail
442distribution directory
443contains the source files.
444This directory contains several subdirectories:
445.nr ii 1i
446.ip cf
447Both site-dependent and site-independent descriptions of hosts.
448These can be literal host names
449(e.g.,
450.q ucbvax.mc )
451when the hosts are gateways
452or more general descriptions
453(such as
454.q "generic-solaris2.mc"
455as a general description of an SMTP-connected host
456running Solaris 2.x.
457Files ending
458.b \&.mc
459(``M4 Configuration'')
460are the input descriptions;
461the output is in the corresponding
462.b \&.cf
463file.
464The general structure of these files is described below.
465.ip domain
466Site-dependent subdomain descriptions.
467These are tied to the way your organization wants to do addressing.
468For example,
469.b domain/CS.Berkeley.EDU.m4
470is our description for hosts in the CS.Berkeley.EDU subdomain.
471These are referenced using the
472.sm DOMAIN
473.b m4
474macro in the
475.b \&.mc
476file.
477.ip feature
478Definitions of specific features that some particular host in your site
479might want.
480These are referenced using the
481.sm FEATURE
482.b m4
483macro.
484An example feature is
485use_cw_file
486(which tells
487.i sendmail
488to read an /etc/mail/local-host-names file on startup
489to find the set of local names).
490.ip hack
491Local hacks, referenced using the
492.sm HACK
493.b m4
494macro.
495Try to avoid these.
496The point of having them here is to make it clear that they smell.
497.ip m4
498Site-independent
499.i m4 (1)
500include files that have information common to all configuration files.
501This can be thought of as a
502.q #include
503directory.
504.ip mailer
505Definitions of mailers,
506referenced using the
507.sm MAILER
508.b m4
509macro.
510The mailer types that are known in this distribution are
511fax,
512local,
513smtp,
514uucp,
515and usenet.
516For example, to include support for the UUCP-based mailers,
517use
518.q MAILER(uucp) .
519.ip ostype
520Definitions describing various operating system environments
521(such as the location of support files).
522These are referenced using the
523.sm OSTYPE
524.b m4
525macro.
526.ip sh
527Shell files used by the
528.b m4
529build process.
530You shouldn't have to mess with these.
531.ip siteconfig
532Local UUCP connectivity information.
533This directory has been supplanted by the mailertable feature;
534any new configurations should use that feature to do UUCP
535(and other) routing.
536The use of this directory is deprecated.
537.pp
538If you are in a new domain
539(e.g., a company),
540you will probably want to create a
541cf/domain
542file for your domain.
543This consists primarily of relay definitions
544and features you want enabled site-wide:
545for example, Berkeley's domain definition
546defines relays for
547BitNET
548and UUCP.
549These are specific to Berkeley,
550and should be fully-qualified internet-style domain names.
551Please check to make certain they are reasonable for your domain.
552.pp
553Subdomains at Berkeley are also represented in the
554cf/domain
555directory.
556For example,
557the domain
558CS.Berkeley.EDU
559is the Computer Science subdomain,
560EECS.Berkeley.EDU
561is the Electrical Engineering and Computer Sciences subdomain,
562and
563S2K.Berkeley.EDU
564is the Sequoia 2000 subdomain.
565You will probably have to add an entry to this directory
566to be appropriate for your domain.
567.pp
568You will have to use or create
569.b \&.mc
570files in the
571.i cf/cf
572subdirectory for your hosts.
573This is detailed in the
574cf/README
575file.
576.sh 2 "Details of Installation Files"
577.pp
578This subsection describes the files that
579comprise the
580.i sendmail
581installation.
582.sh 3 "/usr/\*(SD/sendmail"
583.pp
584The binary for
585.i sendmail
586is located in /usr/\*(SD\**.
587.(f
588\**This is usually
589/usr/sbin
590on 4.4BSD and newer systems;
591many systems install it in
592/usr/lib.
593I understand it is in /usr/ucblib
594on System V Release 4.
595.)f
596It should be set-group-ID smmsp as described in
597sendmail/SECURITY.
598For security reasons,
599/, /usr, and /usr/\*(SD
600should be owned by root, mode 0755\**.
601.(f
602\**Some vendors ship them owned by bin;
603this creates a security hole that is not actually related to
604.i sendmail .
605Other important directories that should have restrictive ownerships
606and permissions are
607/bin, /usr/bin, /etc, /etc/mail, /usr/etc, /lib, and /usr/lib.
608.)f
609.sh 3 "/etc/mail/sendmail.cf"
610.pp
611This is the main configuration file for
612.i sendmail \**.
613.(f
614\**Actually, the pathname varies depending on the operating system;
615/etc/mail is the preferred directory.
616Some older systems install it in
617.b /usr/lib/sendmail.cf ,
618and I've also seen it in
619.b /usr/ucblib .
620If you want to move this file,
621add -D_PATH_SENDMAILCF=\e"/file/name\e"
622to the flags passed to the C compiler.
623Moving this file is not recommended:
624other programs and scripts know of this location.
625.)f
626This is one of the two non-library file names compiled into
627.i sendmail \**,
628the other is /etc/mail/submit.cf.
629.(f
630\**The system libraries can reference other files;
631in particular, system library subroutines that
632.i sendmail
633calls probably reference
634.i /etc/passwd
635and
636.i /etc/resolv.conf .
637.)f
638.pp
639The configuration file is normally created
640using the distribution files described above.
641If you have a particularly unusual system configuration
642you may need to create a special version.
643The format of this file is detailed in later sections
644of this document.
645.sh 3 "/etc/mail/submit.cf"
646.pp
647This is the configuration file for
648.i sendmail
649when it is used for initial mail submission, in which case
650it is also called ``Mail Submission Program'' (MSP)
651in contrast to ``Mail Transfer Agent'' (MTA).
652Starting with version 8.12,
653.i sendmail
654uses one of two different configuration files based on its operation mode
655(or the new
656.b \-A
657option).
658For initial mail submission, i.e., if one of the options
659.b \-bm
660(default),
661.b \-bs ,
662or
663.b \-t
664is specified, submit.cf is used (if available),
665for other operations sendmail.cf is used.
666Details can be found in
667.i sendmail/SECURITY .
668submit.cf is shipped with sendmail (in cf/cf/) and is installed by default.
669If changes to the configuration need to be made, start with
670cf/cf/submit.mc and follow the instruction in cf/README.
671.sh 3 "/usr/\*(SB/newaliases"
672.pp
673The
674.i newaliases
675command should just be a link to
676.i sendmail :
677.(b
678rm \-f /usr/\*(SB/newaliases
679ln \-s /usr/\*(SD/sendmail /usr/\*(SB/newaliases
680.)b
681This can be installed in whatever search path you prefer
682for your system.
683.sh 3 "/usr/\*(SB/hoststat"
684.pp
685The
686.i hoststat
687command should just be a link to
688.i sendmail ,
689in a fashion similar to
690.i newaliases .
691This command lists the status of the last mail transaction
692with all remote hosts. The
693.b \-v
694flag will prevent the status display from being truncated.
695It functions only when the
696.b HostStatusDirectory
697option is set.
698.sh 3 "/usr/\*(SB/purgestat"
699.pp
700This command is also a link to
701.i sendmail .
702It flushes expired (Timeout.hoststatus) information that is stored in the
703.b HostStatusDirectory
704tree.
705.sh 3 "/var/spool/mqueue"
706.pp
707The directory
708.i /var/spool/mqueue
709should be created to hold the mail queue.
710This directory should be mode 0700
711and owned by root.
712.pp
713The actual path of this directory
714is defined by the
715.b QueueDirectory
716option of the
717.i sendmail.cf
718file.
719To use multiple queues,
720supply a value ending with an asterisk.
721For example,
722.i /var/spool/mqueue/qd*
723will use all of the directories or symbolic links to directories
724beginning with `qd' in
725.i /var/spool/mqueue
726as queue directories.
727Do not change the queue directory structure
728while sendmail is running.
729.pp
730If these directories have subdirectories or symbolic links to directories
731named `qf', `df', and `xf', then these will be used for the different
732queue file types.
733That is, the data files are stored in the `df' subdirectory,
734the transcript files are stored in the `xf' subdirectory, and
735all others are stored in the `qf' subdirectory.
736.pp
737If shared memory support is compiled in,
738.i sendmail
739stores the available diskspace in a shared memory segment
740to make the values readily available to all children without
741incurring system overhead.
742In this case, only the daemon updates the data;
743i.e., the sendmail daemon creates the shared memory segment
744and deletes it if it is terminated.
745To use this,
746.i sendmail
747must have been compiled with support for shared memory
748(-DSM_CONF_SHM)
749and the option
750.b SharedMemoryKey
751must be set.
752Notice: do not use the same key for
753.i sendmail
754invocations with different queue directories
755or different queue group declarations.
756Access to shared memory is not controlled by locks,
757i.e., there is a race condition when data in the shared memory is updated.
758However, since operation of
759.i sendmail
760does not rely on the data in the shared memory, this does not negatively
761influence the behavior.
762.sh 3 "/var/spool/clientmqueue"
763.pp
764The directory
765.i /var/spool/clientmqueue
766should be created to hold the mail queue.
767This directory should be mode 0770
768and owned by user smmsp, group smmsp.
769.pp
770The actual path of this directory
771is defined by the
772.b QueueDirectory
773option of the
774.i submit.cf
775file.
776.sh 3 "/var/spool/mqueue/.hoststat"
777.pp
778This is a typical value for the
779.b HostStatusDirectory
780option,
781containing one file per host
782that this sendmail has chatted with recently.
783It is normally a subdirectory of
784.i mqueue .
785.sh 3 "/etc/mail/aliases*"
786.pp
787The system aliases are held in
788.q /etc/mail/aliases .
789A sample is given in
790.q sendmail/aliases
791which includes some aliases which
792.i must
793be defined:
794.(b
795cp sendmail/aliases /etc/mail/aliases
796.i "edit /etc/mail/aliases"
797.)b
798You should extend this file with any aliases that are apropos to your system.
799.pp
800Normally
801.i sendmail
802looks at a database version of the files,
803stored either in
804.q /etc/mail/aliases.dir
805and
806.q /etc/mail/aliases.pag
807or
808.q /etc/mail/aliases.db
809depending on which database package you are using.
810The actual path of this file
811is defined in the
812.b AliasFile
813option of the
814.i sendmail.cf
815file.
816.pp
817The permissions of the alias file and the database versions
818should be 0640 to prevent local denial of service attacks
819as explained in the top level
820.b README
821in the sendmail distribution.
822If the permissions 0640 are used, be sure that only trusted users belong
823to the group assigned to those files. Otherwise, files should not even
824be group readable.
825.sh 3 "/etc/rc or /etc/init.d/sendmail"
826.pp
827It will be necessary to start up the
828.i sendmail
829daemon when your system reboots.
830This daemon performs two functions:
831it listens on the SMTP socket for connections
832(to receive mail from a remote system)
833and it processes the queue periodically
834to insure that mail gets delivered when hosts come up.
835.pp
836If necessary, add the following lines to
837.q /etc/rc
838(or
839.q /etc/rc.local
840as appropriate)
841in the area where it is starting up the daemons
842on a BSD-base system,
843or on a System-V-based system
844in one of the startup files, typically
845.q /etc/init.d/sendmail :
846.(b
847if [ \-f /usr/\*(SD/sendmail \-a \-f /etc/mail/sendmail.cf ]; then
848 (cd /var/spool/mqueue; rm \-f xf*)
849 /usr/\*(SD/sendmail \-bd \-q30m &
850 echo \-n ' sendmail' >/dev/console
851fi
852.)b
853The
854.q cd
855and
856.q rm
857commands insure that all transcript files have been removed;
858extraneous transcript files may be left around
859if the system goes down in the middle of processing a message.
860The line that actually invokes
861.i sendmail
862has two flags:
863.q \-bd
864causes it to listen on the SMTP port,
865and
866.q \-q30m
867causes it to run the queue every half hour.
868.pp
869Some people use a more complex startup script,
870removing zero length qf files and df files for which there is no qf file.
871For example, see Figure 1
872for an example of a complex script which does this clean up.
873.(z
874.hl
875#!/bin/sh
876# remove zero length qf files
877for qffile in qf*
878do
879 if [ \-r $qffile ]
880 then
881 if [ ! \-s $qffile ]
882 then
883 echo \-n " <zero: $qffile>" > /dev/console
884 rm \-f $qffile
885 fi
886 fi
887done
888# rename tf files to be qf if the qf does not exist
889for tffile in tf*
890do
891 qffile=`echo $tffile | sed 's/t/q/'`
892 if [ \-r $tffile \-a ! \-f $qffile ]
893 then
894 echo \-n " <recovering: $tffile>" > /dev/console
895 mv $tffile $qffile
896 else
897 if [ \-f $tffile ]
898 then
899 echo \-n " <extra: $tffile>" > /dev/console
900 rm \-f $tffile
901 fi
902 fi
903done
904# remove df files with no corresponding qf files
905for dffile in df*
906do
907 qffile=`echo $dffile | sed 's/d/q/'`
908 if [ \-r $dffile \-a ! \-f $qffile ]
909 then
910 echo \-n " <incomplete: $dffile>" > /dev/console
911 mv $dffile `echo $dffile | sed 's/d/D/'`
912 fi
913done
914# announce files that have been saved during disaster recovery
915for xffile in [A-Z]f*
916do
917 if [ \-f $xffile ]
918 then
919 echo \-n " <panic: $xffile>" > /dev/console
920 fi
921done
922.sp
923.ce
924Figure 1 \(em A complex startup script
925.hl
926.)z
927.sh 3 "/etc/mail/helpfile"
928.pp
929This is the help file used by the SMTP
930.b HELP
931command.
932It should be copied from
933.q sendmail/helpfile :
934.(b
935cp sendmail/helpfile /etc/mail/helpfile
936.)b
937The actual path of this file
938is defined in the
939.b HelpFile
940option of the
941.i sendmail.cf
942file.
943.sh 3 "/etc/mail/statistics"
944.pp
945If you wish to collect statistics
946about your mail traffic,
947you should create the file
948.q /etc/mail/statistics :
949.(b
950cp /dev/null /etc/mail/statistics
951chmod 0600 /etc/mail/statistics
952.)b
953This file does not grow.
954It is printed with the program
955.q mailstats/mailstats.c.
956The actual path of this file
957is defined in the
958.b S
959option of the
960.i sendmail.cf
961file.
962.sh 3 "/usr/\*(SB/mailq"
963.pp
964If
965.i sendmail
966is invoked as
967.q mailq,
968it will simulate the
969.b \-bp
970flag
971(i.e.,
972.i sendmail
973will print the contents of the mail queue;
974see below).
975This should be a link to /usr/\*(SD/sendmail.
976.sh 3 "sendmail.pid"
977.pp
978.i sendmail
979stores its current pid in the file specifed by the
980.b PidFile
981option (default is _PATH_SENDMAILPID).
982.i sendmail
983uses
984.b TempFileMode
985(which defaults to 0600) as
986the permissions of that file
987to prevent local denial of service attacks
988as explained in the top level
989.b README
990in the sendmail distribution.
991If the file already exists, then it might be necessary to
992change the permissions accordingly, e.g.,
993.(b
994chmod 0600 /var/run/sendmail.pid
995.)b
996.sh 3 "Map Files"
997.pp
998To prevent local denial of service attacks
999as explained in the top level
1000.b README
1001in the sendmail distribution,
1002the permissions of map files created by
1003.i makemap
1004should be 0640.
1005The use of 0640 implies that only trusted users belong to the group
1006assigned to those files.
1007If those files already exist, then it might be necessary to
1008change the permissions accordingly, e.g.,
1009.(b
1010cd /etc/mail
1011chmod 0640 *.db *.pag *.dir
1012.)b
1013.sh 1 "NORMAL OPERATIONS"
1014.sh 2 "The System Log"
1015.pp
1016The system log is supported by the
1017.i syslogd \|(8)
1018program.
1019All messages from
1020.i sendmail
1021are logged under the
1022.sm LOG_MAIL
1023facility\**.
1024.(f
1025\**Except on Ultrix,
1026which does not support facilities in the syslog.
1027.)f
1028.sh 3 "Format"
1029.pp
1030Each line in the system log
1031consists of a timestamp,
1032the name of the machine that generated it
1033(for logging from several machines
1034over the local area network),
1035the word
1036.q sendmail: ,
1037and a message\**.
1038.(f
1039\**This format may vary slightly if your vendor has changed
1040the syntax.
1041.)f
1042Most messages are a sequence of
1043.i name \c
1044=\c
1045.i value
1046pairs.
1047.pp
1048The two most common lines are logged when a message is processed.
1049The first logs the receipt of a message;
1050there will be exactly one of these per message.
1051Some fields may be omitted if they do not contain interesting information.
1052Fields are:
1053.ip from
1054The envelope sender address.
1055.ip size
1056The size of the message in bytes.
1057.ip class
1058The class (i.e., numeric precedence) of the message.
1059.ip pri
1060The initial message priority (used for queue sorting).
1061.ip nrcpts
1062The number of envelope recipients for this message
1063(after aliasing and forwarding).
1064.ip msgid
1065The message id of the message (from the header).
1066.ip proto
1067The protocol used to receive this message (e.g., ESMTP or UUCP)
1068.ip daemon
1069The daemon name from the
1070.b DaemonPortOptions
1071setting.
1072.ip relay
1073The machine from which it was received.
1074.lp
1075There is also one line logged per delivery attempt
1076(so there can be several per message if delivery is deferred
1077or there are multiple recipients).
1078Fields are:
1079.ip to
1080A comma-separated list of the recipients to this mailer.
1081.ip ctladdr
1082The ``controlling user'', that is, the name of the user
1083whose credentials we use for delivery.
1084.ip delay
1085The total delay between the time this message was received
1086and the current delivery attempt.
1087.ip xdelay
1088The amount of time needed in this delivery attempt
1089(normally indicative of the speed of the connection).
1090.ip mailer
1091The name of the mailer used to deliver to this recipient.
1092.ip relay
1093The name of the host that actually accepted (or rejected) this recipient.
1094.ip dsn
1095The enhanced error code (RFC 2034) if available.
1096.ip stat
1097The delivery status.
1098.lp
1099Not all fields are present in all messages;
1100for example, the relay is usually not listed for local deliveries.
1101.sh 3 "Levels"
1102.pp
1103If you have
1104.i syslogd \|(8)
1105or an equivalent installed,
1106you will be able to do logging.
1107There is a large amount of information that can be logged.
1108The log is arranged as a succession of levels.
1109At the lowest level
1110only extremely strange situations are logged.
1111At the highest level,
1112even the most mundane and uninteresting events
1113are recorded for posterity.
1114As a convention,
1115log levels under ten
1116are considered generally
1117.q useful;
1118log levels above 64
1119are reserved for debugging purposes.
1120Levels from 11\-64 are reserved for verbose information
1121that some sites might want.
1122.pp
1123A complete description of the log levels
1124is given in section
1125.\" XREF
11264.6.
1127.sh 2 "Dumping State"
1128.pp
1129You can ask
1130.i sendmail
1131to log a dump of the open files
1132and the connection cache
1133by sending it a
1134.sm SIGUSR1
1135signal.
1136The results are logged at
1137.sm LOG_DEBUG
1138priority.
1139.sh 2 "The Mail Queues"
1140.pp
1141Mail messages may either be delivered immediately or be held for later
1142delivery.
1143Held messages are placed into a holding directory called a mail queue.
1144.pp
1145A mail message may be queued for these reasons:
1146.bu
1147If a mail message is temporarily undeliverable, it is queued
1148and delivery is attempted later.
1149If the message is addressed to multiple recipients, it is queued
1150only for those recipients to whom delivery is not immediately possible.
1151.bu
1152If the SuperSafe option is set to true,
1153all mail messages are queued while delivery is attempted.
1154.bu
1155If the DeliveryMode option is set to queue-only or defer,
1156all mail is queued, and no immediate delivery is attempted.
1157.bu
1158If the load average becomes higher than the value of the QueueLA option
1159and the
1160.b QueueFactor
1161(\c
1162.b q )
1163option divided by the difference in the current load average and the
1164.b QueueLA
1165option plus one
1166is less than the priority of the message,
1167messages are queued rather than immediately delivered.
1168.sh 3 "Queue Groups and Queue Directories"
1169.pp
1170There are one or more mail queues.
1171Each mail queue belongs to a queue group.
1172There is always a default queue group that is called ``mqueue''
1173(which is where messages go by default unless otherwise specified).
1174The directory or directories which comprise the default queue group
1175are specified by the QueueDirectory option.
1176There are zero or more
1177additional named queue groups declared using the
1178.b Q
1179command in the configuration file.
1180.pp
1181By default, a queued message is placed in the queue group
1182associated with the first recipient in the recipient list.
1183A recipient address is mapped to a queue group as follows.
1184First, if there is a ruleset called ``queuegroup'',
1185and if this ruleset maps the address to a queue group name,
1186then that queue group is chosen.
1187That is, the argument for the ruleset is the recipient address
1188and the result should be
1189.b $#
1190followed by the name of a queue group.
1191Otherwise, if the mailer associated with the address specifies
1192a queue group, then that queue group is chosen.
1193Otherwise, the default queue group is chosen.
1194.pp
1195A message with multiple recipients will be split
1196if different queue groups are chosen
1197by the mapping of recipients to queue groups.
1198.pp
1199When a message is placed in a queue group, and the queue group has
1200more than one queue, a queue is selected randomly.
1201.pp
1202If a message with multiple recipients is placed into a queue group
1203with the 'r' option (maximum number of recipients per message)
1204set to a positive value
1205.i N ,
1206and if there are more than
1207.i N
1208recipients
1209in the message, then the message will be split into multiple messages,
1210each of which have at most
1211.i N
1212recipients.
1213.pp
1214Notice: if multiple queue groups are used, do
1215.b not
1216move queue files around, e.g., into a different queue directory.
1217This may have weird effects and can cause mail not to be delivered.
1218Queue files and directories should be treated as opaque
1219and should not be manipulated directly.
1220.sh 3 "Queue Runs"
1221.pp
1222.i sendmail
1223has two different ways to process the queue(s).
1224The first one is to start queue runners after certain intervals
1225(``normal'' queue runners),
1226the second one is to keep queue runner processes around
1227(``persistent'' queue runners).
1228How to select either of these types is discussed in the appendix
1229``COMMAND LINE FLAGS''.
1230Persistent queue runners have the advantage that no new processes
1231need to be spawned at certain intervals; they just sleep for
1232a specified time after they finished a queue run.
1233Another advantage of persistent queue runners is that only one process
1234belonging to a workgroup (a workgroup is a set of queue groups)
1235collects the data for a queue run
1236and then multiple queue runner may go ahead using that data.
1237This can significantly reduce the disk I/O necessary to read the
1238queue files compared to starting multiple queue runners directly.
1239Their disadvantage is that a new queue run is only started
1240after all queue runners belonging to a group finished their tasks.
1241In case one of the queue runners tries delivery to a slow recipient site
1242at the end of a queue run, the next queue run may be substantially delayed.
1243In general this should be smoothed out due to the distribution of
1244those slow jobs, however, for sites with small number of
1245queue entries this might introduce noticable delays.
1246In general, persistent queue runners are only useful for
1247sites with big queues.
1248.sh 3 "Manual Intervention"
1249.pp
1250Under normal conditions the mail queue will be processed transparently.
1251However, you may find that manual intervention is sometimes necessary.
1252For example,
1253if a major host is down for a period of time
1254the queue may become clogged.
1255Although
1256.i sendmail
1257ought to recover gracefully when the host comes up,
1258you may find performance unacceptably bad in the meantime.
1259In that case you want to check the content of the queue
1260and manipulate it as explained in the next two sections.
1261.sh 3 "Printing the queue"
1262.pp
1263The contents of the queue(s) can be printed
1264using the
1265.i mailq
1266command
1267(or by specifying the
1268.b \-bp
1269flag to
1270.i sendmail ):
1271.(b
1272mailq
1273.)b
1274This will produce a listing of the queue id's,
1275the size of the message,
1276the date the message entered the queue,
1277and the sender and recipients.
1278If shared memory support is compiled in,
1279the flag
1280.b \-bP
1281can be used to print the number of entries in the queue(s),
1282provided a process updates the data.
1283However, as explained earlier, the output might be slightly wrong,
1284since access to the shared memory is not locked.
1285For example,
1286``unknown number of entries''
1287might be shown.
1288The internal counters are updated after each queue run
1289to the correct value again.
1290.sh 3 "Forcing the queue"
1291.pp
1292.i Sendmail
1293should run the queue automatically at intervals.
1294When using multiple queues,
1295a separate process will by default be created to
1296run each of the queues
1297unless the queue run is initiated by a user
1298with the verbose flag.
1299The algorithm is to read and sort the queue,
1300and then to attempt to process all jobs in order.
1301When it attempts to run the job,
1302.i sendmail
1303first checks to see if the job is locked.
1304If so, it ignores the job.
1305.pp
1306There is no attempt to insure that only one queue processor
1307exists at any time,
1308since there is no guarantee that a job cannot take forever
1309to process
1310(however,
1311.i sendmail
1312does include heuristics to try to abort jobs
1313that are taking absurd amounts of time;
1314technically, this violates RFC 821, but is blessed by RFC 1123).
1315Due to the locking algorithm,
1316it is impossible for one job to freeze the entire queue.
1317However,
1318an uncooperative recipient host
1319or a program recipient
1320that never returns
1321can accumulate many processes in your system.
1322Unfortunately,
1323there is no completely general way to solve this.
1324.pp
1325In some cases,
1326you may find that a major host going down
1327for a couple of days
1328may create a prohibitively large queue.
1329This will result in
1330.i sendmail
1331spending an inordinate amount of time
1332sorting the queue.
1333This situation can be fixed by moving the queue to a temporary place
1334and creating a new queue.
1335The old queue can be run later when the offending host returns to service.
1336.pp
1337To do this,
1338it is acceptable to move the entire queue directory:
1339.(b
1340cd /var/spool
1341mv mqueue omqueue; mkdir mqueue; chmod 0700 mqueue
1342.)b
1343You should then kill the existing daemon
1344(since it will still be processing in the old queue directory)
1345and create a new daemon.
1346.pp
1347To run the old mail queue, issue the following command:
1348.(b
1349/usr/\*(SD/sendmail \-C /etc/mail/queue.cf \-q
1350.)b
1351The
1352.b \-C
1353flag specifies an alternate configuration file
1354.b queue.cf
1355which should refer to the moved queue directory
1356.(b
1357O QueueDirectory=/var/spool/omqueue
1358.)b
1359and the
1360.b \-q
1361flag says to just run every job in the queue.
1362You can also specify the moved queue directory on the command line
1363.(b
1364/usr/\*(SD/sendmail \-oQ/var/spool/omqueue \-q
1365.)b
1366but this requires that you do not have
1367queue groups in the configuration file,
1368because those are not subdirectories of the moved directory.
1369See the section about "Queue Group Declaration" for details;
1370you most likely need a different configuration file to correctly deal
1371with this problem.
1372However, a proper configuration of queue groups should avoid
1373filling up queue directories, so you shouldn't run into
1374this problem.
1375If you have a tendency toward voyeurism,
1376you can use the
1377.b \-v
1378flag to watch what is going on.
1379.pp
1380When the queue is finally emptied,
1381you can remove the directory:
1382.(b
1383rmdir /var/spool/omqueue
1384.)b
1385.sh 2 "Disk Based Connection Information"
1386.pp
1387.i Sendmail
1388stores a large amount of information about each remote system it
1389has connected to in memory. It is possible to preserve some
1390of this information on disk as well, by using the
1391.b HostStatusDirectory
1392option, so that it may be shared between several invocations of
1393.i sendmail .
1394This allows mail to be queued immediately or skipped during a queue run if
1395there has been a recent failure in connecting to a remote machine.
1396.pp
1397Additionally enabling
1398.b SingleThreadDelivery
1399has the added effect of single-threading mail delivery to a destination.
1400This can be quite helpful
1401if the remote machine is running an SMTP server that is easily overloaded
1402or cannot accept more than a single connection at a time,
1403but can cause some messages to be punted to a future queue run.
1404It also applies to
1405.i all
1406hosts, so setting this because you have one machine on site
1407that runs some software that is easily overrun
1408can cause mail to other hosts to be slowed down.
1409If this option is set,
1410you probably want to set the
1411.b MinQueueAge
1412option as well and run the queue fairly frequently;
1413this way jobs that are skipped because another
1414.i sendmail
1415is talking to the same host will be tried again quickly
1416rather than being delayed for a long time.
1417.pp
1418The disk based host information is stored in a subdirectory of the
1419.b mqueue
1420directory called
1421.b \&.hoststat \**.
1422.(f
1423\**This is the usual value of the
1424.b HostStatusDirectory
1425option;
1426it can, of course, go anywhere you like in your filesystem.
1427.)f
1428Removing this directory and its subdirectories has an effect similar to
1429the
1430.i purgestat
1431command and is completely safe.
1432However,
1433.i purgestat
1434only removes expired (Timeout.hoststatus) data.
1435The information in these directories can
1436be perused with the
1437.i hoststat
1438command, which will indicate the host name, the last access, and the
1439status of that access.
1440An asterisk in the left most column indicates that a
1441.i sendmail
1442process currently has the host locked for mail delivery.
1443.pp
1444The disk based connection information is treated the same way as memory based
1445connection information for the purpose of timeouts.
1446By default, information about host failures is valid for 30 minutes.
1447This can be adjusted with
1448the
1449.b Timeout.hoststatus
1450option.
1451.pp
1452The connection information stored on disk may be expired at any time
1453with the
1454.i purgestat
1455command or by invoking sendmail with the
1456.b \-bH
1457switch.
1458The connection information may be viewed with the
1459.i hoststat
1460command or by invoking sendmail with the
1461.b \-bh
1462switch.
1463.sh 2 "The Service Switch"
1464.pp
1465The implementation of certain system services
1466such as host and user name lookup
1467is controlled by the service switch.
1468If the host operating system supports such a switch,
1469and sendmail knows about it,
1470.i sendmail
1471will use the native version.
1472Ultrix, Solaris, and DEC OSF/1 are examples of such systems\**.
1473.(f
1474\**HP-UX 10 has service switch support,
1475but since the APIs are apparently not available in the libraries
1476.i sendmail
1477does not use the native service switch in this release.
1478.)f
1479.pp
1480If the underlying operating system does not support a service switch
1481(e.g., SunOS 4.X, HP-UX, BSD)
1482then
1483.i sendmail
1484will provide a stub implementation.
1485The
1486.b ServiceSwitchFile
1487option points to the name of a file that has the service definitions.
1488Each line has the name of a service
1489and the possible implementations of that service.
1490For example, the file:
1491.(b
1492hosts dns files nis
1493aliases files nis
1494.)b
1495will ask
1496.i sendmail
1497to look for hosts in the Domain Name System first.
1498If the requested host name is not found, it tries local files,
1499and if that fails it tries NIS.
1500Similarly, when looking for aliases
1501it will try the local files first followed by NIS.
1502.pp
1503Notice: since
1504.i sendmail
1505must access MX records for correct operation, it will use
1506DNS if it is configured in the
1507.b ServiceSwitchFile
1508file.
1509Hence an entry like
1510.(b
1511hosts files dns
1512.)b
1513will not avoid DNS lookups even if a host can be found
1514in /etc/hosts.
1515.pp
1516Service switches are not completely integrated.
1517For example, despite the fact that the host entry listed in the above example
1518specifies to look in NIS,
1519on SunOS this won't happen because the system implementation of
1520.i gethostbyname \|(3)
1521doesn't understand this.
1522.sh 2 "The Alias Database"
1523.pp
1524After recipient addresses are read from the SMTP connection
1525or command line
1526they are parsed by ruleset 0,
1527which must resolve to a
1528{\c
1529.i mailer ,
1530.i host ,
1531.i address }
1532triple.
1533If the flags selected by the
1534.i mailer
1535include the
1536.b A
1537(aliasable) flag,
1538the
1539.i address
1540part of the triple is looked up as the key
1541(i.e., the left hand side)
1542into the alias database.
1543If there is a match, the address is deleted from the send queue
1544and all addresses on the right hand side of the alias
1545are added in place of the alias that was found.
1546This is a recursive operation,
1547so aliases found in the right hand side of the alias
1548are similarly expanded.
1549.pp
1550The alias database exists in two forms.
1551One is a text form,
1552maintained in the file
1553.i /etc/mail/aliases.
1554The aliases are of the form
1555.(b
1556name: name1, name2, ...
1557.)b
1558Only local names may be aliased;
1559e.g.,
1560.(b
1561eric@prep.ai.MIT.EDU: eric@CS.Berkeley.EDU
1562.)b
1563will not have the desired effect
1564(except on prep.ai.MIT.EDU,
1565and they probably don't want me)\**.
1566.(f
1567\**Actually, any mailer that has the `A' mailer flag set
1568will permit aliasing;
1569this is normally limited to the local mailer.
1570.)f
1571Aliases may be continued by starting any continuation lines
1572with a space or a tab or by putting a backslash directly before
1573the newline.
1574Blank lines and lines beginning with a sharp sign
1575(\c
1576.q # )
1577are comments.
1578.pp
1579The second form is processed by the
1580.i ndbm \|(3)\**
1581.(f
1582\**The
1583.i gdbm
1584package does not work.
1585.)f
1586or the Berkeley DB library.
1587This form is in the file
1588.i /etc/mail/aliases.db
1589(if using NEWDB)
1590or
1591.i /etc/mail/aliases.dir
1592and
1593.i /etc/mail/aliases.pag
1594(if using NDBM).
1595This is the form that
1596.i sendmail
1597actually uses to resolve aliases.
1598This technique is used to improve performance.
1599.pp
1600The control of search order is actually set by the service switch.
1601Essentially, the entry
1602.(b
1603O AliasFile=switch:aliases
1604.)b
1605is always added as the first alias entry;
1606also, the first alias file name without a class
1607(e.g., without
1608.q nis:
1609on the front)
1610will be used as the name of the file for a ``files'' entry
1611in the aliases switch.
1612For example, if the configuration file contains
1613.(b
1614O AliasFile=/etc/mail/aliases
1615.)b
1616and the service switch contains
1617.(b
1618aliases nis files nisplus
1619.)b
1620then aliases will first be searched in the NIS database,
1621then in /etc/mail/aliases,
1622then in the NIS+ database.
1623.pp
1624You can also use
1625.sm NIS -based
1626alias files.
1627For example, the specification:
1628.(b
1629O AliasFile=/etc/mail/aliases
1630O AliasFile=nis:mail.aliases@my.nis.domain
1631.)b
1632will first search the /etc/mail/aliases file
1633and then the map named
1634.q mail.aliases
1635in
1636.q my.nis.domain .
1637Warning: if you build your own
1638.sm NIS -based
1639alias files,
1640be sure to provide the
1641.b \-l
1642flag to
1643.i makedbm (8)
1644to map upper case letters in the keys to lower case;
1645otherwise, aliases with upper case letters in their names
1646won't match incoming addresses.
1647.pp
1648Additional flags can be added after the colon
1649exactly like a
1650.b K
1651line \(em for example:
1652.(b
1653O AliasFile=nis:\-N mail.aliases@my.nis.domain
1654.)b
1655will search the appropriate NIS map and always include null bytes in the key.
1656Also:
1657.(b
1658O AliasFile=nis:\-f mail.aliases@my.nis.domain
1659.)b
1660will prevent sendmail from downcasing the key before the alias lookup.
1661.sh 3 "Rebuilding the alias database"
1662.pp
1663The
1664.i hash
1665or
1666.i dbm
1667version of the database
1668may be rebuilt explicitly by executing the command
1669.(b
1670newaliases
1671.)b
1672This is equivalent to giving
1673.i sendmail
1674the
1675.b \-bi
1676flag:
1677.(b
1678/usr/\*(SD/sendmail \-bi
1679.)b
1680.pp
1681If you have multiple aliases databases specified,
1682the
1683.b \-bi
1684flag rebuilds all the database types it understands
1685(for example, it can rebuild NDBM databases but not NIS databases).
1686.sh 3 "Potential problems"
1687.pp
1688There are a number of problems that can occur
1689with the alias database.
1690They all result from a
1691.i sendmail
1692process accessing the DBM version
1693while it is only partially built.
1694This can happen under two circumstances:
1695One process accesses the database
1696while another process is rebuilding it,
1697or the process rebuilding the database dies
1698(due to being killed or a system crash)
1699before completing the rebuild.
1700.pp
1701Sendmail has three techniques to try to relieve these problems.
1702First, it ignores interrupts while rebuilding the database;
1703this avoids the problem of someone aborting the process
1704leaving a partially rebuilt database.
1705Second,
1706it locks the database source file during the rebuild \(em
1707but that may not work over NFS or if the file is unwritable.
1708Third,
1709at the end of the rebuild
1710it adds an alias of the form
1711.(b
1712@: @
1713.)b
1714(which is not normally legal).
1715Before
1716.i sendmail
1717will access the database,
1718it checks to insure that this entry exists\**.
1719.(f
1720\**The
1721.b AliasWait
1722option is required in the configuration
1723for this action to occur.
1724This should normally be specified.
1725.)f
1726.sh 3 "List owners"
1727.pp
1728If an error occurs on sending to a certain address,
1729say
1730.q \fIx\fP ,
1731.i sendmail
1732will look for an alias
1733of the form
1734.q owner-\fIx\fP
1735to receive the errors.
1736This is typically useful
1737for a mailing list
1738where the submitter of the list
1739has no control over the maintenance of the list itself;
1740in this case the list maintainer would be the owner of the list.
1741For example:
1742.(b
1743unix-wizards: eric@ucbarpa, wnj@monet, nosuchuser,
1744 sam@matisse
1745owner-unix-wizards: unix-wizards-request
1746unix-wizards-request: eric@ucbarpa
1747.)b
1748would cause
1749.q eric@ucbarpa
1750to get the error that will occur
1751when someone sends to
1752unix-wizards
1753due to the inclusion of
1754.q nosuchuser
1755on the list.
1756.pp
1757List owners also cause the envelope sender address to be modified.
1758The contents of the owner alias are used if they point to a single user,
1759otherwise the name of the alias itself is used.
1760For this reason, and to obey Internet conventions,
1761the
1762.q owner-
1763address normally points at the
1764.q -request
1765address; this causes messages to go out with the typical Internet convention
1766of using ``\c
1767.i list -request''
1768as the return address.
1769.sh 2 "User Information Database"
1770.pp
1771This option is deprecated, use virtusertable and genericstable instead
1772as explained in
1773.i cf/README .
1774If you have a version of
1775.i sendmail
1776with the user information database
1777compiled in,
1778and you have specified one or more databases using the
1779.b U
1780option,
1781the databases will be searched for a
1782.i user :maildrop
1783entry.
1784If found, the mail will be sent to the specified address.
1785.sh 2 "Per-User Forwarding (.forward Files)"
1786.pp
1787As an alternative to the alias database,
1788any user may put a file with the name
1789.q .forward
1790in his or her home directory.
1791If this file exists,
1792.i sendmail
1793redirects mail for that user
1794to the list of addresses listed in the .forward file.
1795Note that aliases are fully expanded before forward files are referenced.
1796For example, if the home directory for user
1797.q mckusick
1798has a .forward file with contents:
1799.(b
1800mckusick@ernie
1801kirk@calder
1802.)b
1803then any mail arriving for
1804.q mckusick
1805will be redirected to the specified accounts.
1806.pp
1807Actually, the configuration file defines a sequence of filenames to check.
1808By default, this is the user's .forward file,
1809but can be defined to be more generally using the
1810.b ForwardPath
1811option.
1812If you change this,
1813you will have to inform your user base of the change;
1814\&.forward is pretty well incorporated into the collective subconscious.
1815.sh 2 "Special Header Lines"
1816.pp
1817Several header lines have special interpretations
1818defined by the configuration file.
1819Others have interpretations built into
1820.i sendmail
1821that cannot be changed without changing the code.
1822These built-ins are described here.
1823.sh 3 "Errors-To:"
1824.pp
1825If errors occur anywhere during processing,
1826this header will cause error messages to go to
1827the listed addresses.
1828This is intended for mailing lists.
1829.pp
1830The Errors-To: header was created in the bad old days
1831when UUCP didn't understand the distinction between an envelope and a header;
1832this was a hack to provide what should now be passed
1833as the envelope sender address.
1834It should go away.
1835It is only used if the
1836.b UseErrorsTo
1837option is set.
1838.pp
1839The Errors-To: header is officially deprecated
1840and will go away in a future release.
1841.sh 3 "Apparently-To:"
1842.pp
1843RFC 822 requires at least one recipient field
1844(To:, Cc:, or Bcc: line)
1845in every message.
1846If a message comes in with no recipients listed in the message
1847then
1848.i sendmail
1849will adjust the header based on the
1850.q NoRecipientAction
1851option.
1852One of the possible actions is to add an
1853.q "Apparently-To:"
1854header line for any recipients it is aware of.
1855.pp
1856The Apparently-To: header is non-standard
1857and is both deprecated and strongly discouraged.
1858.sh 3 "Precedence"
1859.pp
1860The Precedence: header can be used as a crude control of message priority.
1861It tweaks the sort order in the queue
1862and can be configured to change the message timeout values.
1863The precedence of a message also controls how
1864delivery status notifications (DSNs)
1865are processed for that message.
1866.sh 2 "IDENT Protocol Support"
1867.pp
1868.i Sendmail
1869supports the IDENT protocol as defined in RFC 1413.
1870Note that the RFC states
1871a client should wait at least 30 seconds for a response.
1872The default Timeout.ident is 5 seconds
1873as many sites have adopted the practice of dropping IDENT queries.
1874This has lead to delays processing mail.
1875Although this enhances identification
1876of the author of an email message
1877by doing a ``call back'' to the originating system to include
1878the owner of a particular TCP connection
1879in the audit trail
1880it is in no sense perfect;
1881a determined forger can easily spoof the IDENT protocol.
1882The following description is excerpted from RFC 1413:
1883.ba +5
1884.lp
18856. Security Considerations
1886.lp
1887The information returned by this protocol is at most as trustworthy
1888as the host providing it OR the organization operating the host. For
1889example, a PC in an open lab has few if any controls on it to prevent
1890a user from having this protocol return any identifier the user
1891wants. Likewise, if the host has been compromised the information
1892returned may be completely erroneous and misleading.
1893.lp
1894The Identification Protocol is not intended as an authorization or
1895access control protocol. At best, it provides some additional
1896auditing information with respect to TCP connections. At worst, it
1897can provide misleading, incorrect, or maliciously incorrect
1898information.
1899.lp
1900The use of the information returned by this protocol for other than
1901auditing is strongly discouraged. Specifically, using Identification
1902Protocol information to make access control decisions - either as the
1903primary method (i.e., no other checks) or as an adjunct to other
1904methods may result in a weakening of normal host security.
1905.lp
1906An Identification server may reveal information about users,
1907entities, objects or processes which might normally be considered
1908private. An Identification server provides service which is a rough
1909analog of the CallerID services provided by some phone companies and
1910many of the same privacy considerations and arguments that apply to
1911the CallerID service apply to Identification. If you wouldn't run a
1912"finger" server due to privacy considerations you may not want to run
1913this protocol.
1914.ba
1915.lp
1916In some cases your system may not work properly with IDENT support
1917due to a bug in the TCP/IP implementation.
1918The symptoms will be that for some hosts
1919the SMTP connection will be closed
1920almost immediately.
1921If this is true or if you do not want to use IDENT,
1922you should set the IDENT timeout to zero;
1923this will disable the IDENT protocol.
1924.sh 1 "ARGUMENTS"
1925.pp
1926The complete list of arguments to
1927.i sendmail
1928is described in detail in Appendix A.
1929Some important arguments are described here.
1930.sh 2 "Queue Interval"
1931.pp
1932The amount of time between forking a process
1933to run through the queue is defined by the
1934.b \-q
1935flag.
1936If you run with delivery mode set to
1937.b i
1938or
1939.b b
1940this can be relatively large, since it will only be relevant
1941when a host that was down comes back up.
1942If you run in
1943.b q
1944mode it should be relatively short,
1945since it defines the maximum amount of time that a message
1946may sit in the queue.
1947(See also the MinQueueAge option.)
1948.pp
1949RFC 1123 section 5.3.1.1 says that this value should be at least 30 minutes
1950(although that probably doesn't make sense if you use ``queue-only'' mode).
1951.pp
1952Notice: the meaning of the interval time depends on whether normal
1953queue runners or persistent queue runners are used.
1954For the former, it is the time between subsequent starts of a queue run.
1955For the latter, it is the time sendmail waits after a persistent queue
1956runner has finished its work to start the next one.
1957Hence for persistent queue runners this interval should be very low,
1958typically no more than two minutes.
1959.sh 2 "Daemon Mode"
1960.pp
1961If you allow incoming mail over an IPC connection,
1962you should have a daemon running.
1963This should be set by your
1964.i /etc/rc
1965file using the
1966.b \-bd
1967flag.
1968The
1969.b \-bd
1970flag and the
1971.b \-q
1972flag may be combined in one call:
1973.(b
1974/usr/\*(SD/sendmail \-bd \-q30m
1975.)b
1976.pp
1977An alternative approach is to invoke sendmail from
1978.i inetd (8)
1979(use the
1980.b \-bs \ \-Am
1981flags to ask sendmail to speak SMTP on its standard input and output
1982and to run as MTA).
1983This works and allows you to wrap
1984.i sendmail
1985in a TCP wrapper program,
1986but may be a bit slower since the configuration file
1987has to be re-read on every message that comes in.
1988If you do this, you still need to have a
1989.i sendmail
1990running to flush the queue:
1991.(b
1992/usr/\*(SD/sendmail \-q30m
1993.)b
1994.sh 2 "Forcing the Queue"
1995.pp
1996In some cases you may find that the queue has gotten clogged for some reason.
1997You can force a queue run
1998using the
1999.b \-q
2000flag (with no value).
2001It is entertaining to use the
2002.b \-v
2003flag (verbose)
2004when this is done to watch what happens:
2005.(b
2006/usr/\*(SD/sendmail \-q \-v
2007.)b
2008.pp
2009You can also limit the jobs to those with a particular queue identifier,
2010recipient, sender, or queue group
2011using one of the queue modifiers.
2012For example,
2013.q \-qRberkeley
2014restricts the queue run to jobs that have the string
2015.q berkeley
2016somewhere in one of the recipient addresses.
2017Similarly,
2018.q \-qSstring
2019limits the run to particular senders,
2020.q \-qIstring
2021limits it to particular queue identifiers, and
2022.q \-qGstring
2023limits it to a particular queue group.
2024You may also place an
2025.b !
2026before the
2027.b I
2028or
2029.b R
2030or
2031.b S
2032to indicate that jobs are limited to not including a particular queue
2033identifier, recipient or sender.
2034For example,
2035.q \-q!Rseattle
2036limits the queue run to jobs that do not have the string
2037.q seattle
2038somewhere in one of the recipient addresses.
2039Should you need to terminate the queue jobs currently active then a SIGTERM
2040to the parent of the process (or processes) will cleanly stop the jobs.
2041.sh 2 "Debugging"
2042.pp
2043There are a fairly large number of debug flags
2044built into
2045.i sendmail .
2046Each debug flag has a category and a level.
2047Higher levels increase the level of debugging activity;
2048in most cases, this means to print out more information.
2049The convention is that levels greater than nine are
2050.q absurd,
2051i.e.,
2052they print out so much information that you wouldn't normally
2053want to see them except for debugging that particular piece of code.
2054.pp
2055A debug category is either an integer, like 42,
2056or a name, like ANSI.
2057You can specify a range of numeric debug categories
2058using the syntax 17-42.
2059You can specify a set of named debug categories using
2060a glob pattern like
2061.q sm_trace_* .
2062At present, only
2063.q *
2064and
2065.q ?
2066are supported in these glob patterns.
2067.pp
2068Debug flags are set using the
2069.b \-d
2070option;
2071the syntax is:
2072.(b
2073.ta \w'debug-categories:M 'u
2074debug-flag: \fB\-d\fP debug-list
2075debug-list: debug-option [ , debug-option ]*
2076debug-option: debug-categories [ . debug-level ]
2077debug-categories: integer | integer \- integer | category-pattern
2078category-pattern: [a-zA-Z_*?][a-zA-Z0-9_*?]*
2079debug-level: integer
2080.)b
2081where spaces are for reading ease only.
2082For example,
2083.(b
2084\-d12 Set category 12 to level 1
2085\-d12.3 Set category 12 to level 3
2086\-d3\-17 Set categories 3 through 17 to level 1
2087\-d3\-17.4 Set categories 3 through 17 to level 4
2088\-dANSI Set category ANSI to level 1
2089\-dsm_trace_*.3 Set all named categories matching sm_trace_* to level 3
2090.)b
2091For a complete list of the available debug flags
2092you will have to look at the code
2093and the
2094.i TRACEFLAGS
2095file in the sendmail distribution
2096(they are too dynamic to keep this document up to date).
2097For a list of named debug categories in the sendmail binary, use
2098.(b
2099ident /usr/sbin/sendmail | grep Debug
2100.)b
2101.sh 2 "Changing the Values of Options"
2102.pp
2103Options can be overridden using the
2104.b \-o
2105or
2106.b \-O
2107command line flags.
2108For example,
2109.(b
2110/usr/\*(SD/sendmail \-oT2m
2111.)b
2112sets the
2113.b T
2114(timeout) option to two minutes
2115for this run only;
2116the equivalent line using the long option name is
2117.(b
2118/usr/\*(SD/sendmail -OTimeout.queuereturn=2m
2119.)b
2120.pp
2121Some options have security implications.
2122Sendmail allows you to set these,
2123but relinquishes its set-user-ID or set-group-ID permissions thereafter\**.
2124.(f
2125\**That is, it sets its effective uid to the real uid;
2126thus, if you are executing as root,
2127as from root's crontab file or during system startup
2128the root permissions will still be honored.
2129.)f
2130.sh 2 "Trying a Different Configuration File"
2131.pp
2132An alternative configuration file
2133can be specified using the
2134.b \-C
2135flag; for example,
2136.(b
2137/usr/\*(SD/sendmail \-Ctest.cf \-oQ/tmp/mqueue
2138.)b
2139uses the configuration file
2140.i test.cf
2141instead of the default
2142.i /etc/mail/sendmail.cf.
2143If the
2144.b \-C
2145flag has no value
2146it defaults to
2147.i sendmail.cf
2148in the current directory.
2149.pp
2150.i Sendmail
2151gives up set-user-ID root permissions
2152(if it has been installed set-user-ID root)
2153when you use this flag, so it is common to use a publicly writable directory
2154(such as /tmp)
2155as the queue directory (QueueDirectory or Q option) while testing.
2156.sh 2 "Logging Traffic"
2157.pp
2158Many SMTP implementations do not fully implement the protocol.
2159For example, some personal computer based SMTPs
2160do not understand continuation lines in reply codes.
2161These can be very hard to trace.
2162If you suspect such a problem, you can set traffic logging using the
2163.b \-X
2164flag.
2165For example,
2166.(b
2167/usr/\*(SD/sendmail \-X /tmp/traffic \-bd
2168.)b
2169will log all traffic in the file
2170.i /tmp/traffic .
2171.pp
2172This logs a lot of data very quickly and should
2173.b NEVER
2174be used
2175during normal operations.
2176After starting up such a daemon,
2177force the errant implementation to send a message to your host.
2178All message traffic in and out of
2179.i sendmail ,
2180including the incoming SMTP traffic,
2181will be logged in this file.
2182.sh 2 "Testing Configuration Files"
2183.pp
2184When you build a configuration table,
2185you can do a certain amount of testing
2186using the
2187.q "test mode"
2188of
2189.i sendmail .
2190For example,
2191you could invoke
2192.i sendmail
2193as:
2194.(b
2195sendmail \-bt \-Ctest.cf
2196.)b
2197which would read the configuration file
2198.q test.cf
2199and enter test mode.
2200In this mode,
2201you enter lines of the form:
2202.(b
2203rwset address
2204.)b
2205where
2206.i rwset
2207is the rewriting set you want to use
2208and
2209.i address
2210is an address to apply the set to.
2211Test mode shows you the steps it takes
2212as it proceeds,
2213finally showing you the address it ends up with.
2214You may use a comma separated list of rwsets
2215for sequential application of rules to an input.
2216For example:
2217.(b
22183,1,21,4 monet:bollard
2219.)b
2220first applies ruleset three to the input
2221.q monet:bollard.
2222Ruleset one is then applied to the output of ruleset three,
2223followed similarly by rulesets twenty-one and four.
2224.pp
2225If you need more detail,
2226you can also use the
2227.q \-d21
2228flag to turn on more debugging.
2229For example,
2230.(b
2231sendmail \-bt \-d21.99
2232.)b
2233turns on an incredible amount of information;
2234a single word address
2235is probably going to print out several pages worth of information.
2236.pp
2237You should be warned that internally,
2238.i sendmail
2239applies ruleset 3 to all addresses.
2240In test mode
2241you will have to do that manually.
2242For example, older versions allowed you to use
2243.(b
22440 bruce@broadcast.sony.com
2245.)b
2246This version requires that you use:
2247.(b
22483,0 bruce@broadcast.sony.com
2249.)b
2250.pp
2251As of version 8.7,
2252some other syntaxes are available in test mode:
2253.nr ii 1i
2254.ip \&.D\|x\|value
2255defines macro
2256.i x
2257to have the indicated
2258.i value .
2259This is useful when debugging rules that use the
2260.b $& \c
2261.i x
2262syntax.
2263.ip \&.C\|c\|value
2264adds the indicated
2265.i value
2266to class
2267.i c .
2268.ip \&=S\|ruleset
2269dumps the contents of the indicated ruleset.
2270.ip \-d\|debug-spec
2271is equivalent to the command-line flag.
2272.lp
2273Version 8.9 introduced more features:
2274.nr ii 1i
2275.ip ?
2276shows a help message.
2277.ip =M
2278display the known mailers.
2279.ip $m
2280print the value of macro m.
2281.ip $=c
2282print the contents of class c.
2283.ip /mx\ host
2284returns the MX records for `host'.
2285.ip /parse\ address
2286parse address, returning the value of
2287.i crackaddr ,
2288and the parsed address.
2289.ip /try\ mailer\ addr
2290rewrite address into the form it will have when
2291presented to the indicated mailer.
2292.ip /tryflags\ flags
2293set flags used by parsing. The flags can be `H' for
2294Header or `E' for Envelope, and `S' for Sender or `R'
2295for Recipient. These can be combined, `HR' sets
2296flags for header recipients.
2297.ip /canon\ hostname
2298try to canonify hostname.
2299.ip /map\ mapname\ key
2300look up `key' in the indicated `mapname'.
2301.ip /quit
2302quit address test mode.
2303.lp
2304.sh 2 "Persistent Host Status Information"
2305.pp
2306When
2307.b HostStatusDirectory
2308is enabled,
2309information about the status of hosts is maintained on disk
2310and can thus be shared between different instantiations of
2311.i sendmail .
2312The status of the last connection with each remote host
2313may be viewed with the command:
2314.(b
2315sendmail \-bh
2316.)b
2317This information may be flushed with the command:
2318.(b
2319sendmail \-bH
2320.)b
2321Flushing the information prevents new
2322.i sendmail
2323processes from loading it,
2324but does not prevent existing processes from using the status information
2325that they already have.
2326.sh 1 "TUNING"
2327.pp
2328There are a number of configuration parameters
2329you may want to change,
2330depending on the requirements of your site.
2331Most of these are set
2332using an option in the configuration file.
2333For example,
2334the line
2335.q "O Timeout.queuereturn=5d"
2336sets option
2337.q Timeout.queuereturn
2338to the value
2339.q 5d
2340(five days).
2341.pp
2342Most of these options have appropriate defaults for most sites.
2343However,
2344sites having very high mail loads may find they need to tune them
2345as appropriate for their mail load.
2346In particular,
2347sites experiencing a large number of small messages,
2348many of which are delivered to many recipients,
2349may find that they need to adjust the parameters
2350dealing with queue priorities.
2351.pp
2352All versions of
2353.i sendmail
2354prior to 8.7
2355had single character option names.
2356As of 8.7,
2357options have long (multi-character names).
2358Although old short names are still accepted,
2359most new options do not have short equivalents.
2360.pp
2361This section only describes the options you are most likely
2362to want to tweak;
2363read section
2364.\"XREF
23655
2366for more details.
2367.sh 2 "Timeouts"
2368.pp
2369All time intervals are set
2370using a scaled syntax.
2371For example,
2372.q 10m
2373represents ten minutes, whereas
2374.q 2h30m
2375represents two and a half hours.
2376The full set of scales is:
2377.(b
2378.ta 4n
2379s seconds
2380m minutes
2381h hours
2382d days
2383w weeks
2384.)b
2385.sh 3 "Queue interval"
2386.pp
2387The argument to the
2388.b \-q
2389flag specifies how often a sub-daemon will run the queue.
2390This is typically set to between fifteen minutes and one hour.
2391If not set, or set to zero,
2392the queue will not be run automatically.
2393RFC 1123 section 5.3.1.1 recommends that this be at least 30 minutes.
2394Should you need to terminate the queue jobs currently active then a SIGTERM
2395to the parent of the process (or processes) will cleanly stop the jobs.
2396.sh 3 "Read timeouts"
2397.pp
2398Timeouts all have option names
2399.q Timeout.\fIsuboption\fP .
2400Most of these control SMTP operations.
2401The recognized
2402.i suboption s,
2403their default values, and the minimum values
2404allowed by RFC 2821 section 4.5.3.2 (or RFC 1123 section 5.3.2) are:
2405.nr ii 1i
2406.ip connect
2407The time to wait for an SMTP connection to open
2408(the
2409.i connect (2)
2410system call)
2411[0, unspecified].
2412If zero, uses the kernel default.
2413In no case can this option extend the timeout
2414longer than the kernel provides, but it can shorten it.
2415This is to get around kernels that provide an absurdly long connection timeout
2416(90 minutes in one case).
2417.ip iconnect
2418The same as
2419.i connect,
2420except it applies only to the initial attempt to connect to a host
2421for a given message
2422[0, unspecified].
2423The concept is that this should be very short (a few seconds);
2424hosts that are well connected and responsive will thus be serviced immediately.
2425Hosts that are slow will not hold up other deliveries in the initial
2426delivery attempt.
2427.ip aconnect
2428[0, unspecified]
2429The overall timeout waiting for all connection for a single delivery
2430attempt to succeed.
2431If 0, no overall limit is applied.
2432This can be used to restrict the total amount of time trying to connect to
2433a long list of host that could accept an e-mail for the recipient.
2434This timeout does not apply to
2435.b FallbackMXhost ,
2436i.e., if the time is exhausted, the
2437.b FallbackMXhost
2438is tried next.
2439.ip initial
2440The wait for the initial 220 greeting message
2441[5m, 5m].
2442.ip helo
2443The wait for a reply from a HELO or EHLO command
2444[5m, unspecified].
2445This may require a host name lookup, so
2446five minutes is probably a reasonable minimum.
2447.ip mail\(dg
2448The wait for a reply from a MAIL command
2449[10m, 5m].
2450.ip rcpt\(dg
2451The wait for a reply from a RCPT command
2452[1h, 5m].
2453This should be long
2454because it could be pointing at a list
2455that takes a long time to expand
2456(see below).
2457.ip datainit\(dg
2458The wait for a reply from a DATA command
2459[5m, 2m].
2460.ip datablock\(dg\(dd
2461The wait for reading a data block
2462(that is, the body of the message).
2463[1h, 3m].
2464This should be long because it also applies to programs
2465piping input to
2466.i sendmail
2467which have no guarantee of promptness.
2468.ip datafinal\(dg
2469The wait for a reply from the dot terminating a message.
2470[1h, 10m].
2471If this is shorter than the time actually needed
2472for the receiver to deliver the message,
2473duplicates will be generated.
2474This is discussed in RFC 1047.
2475.ip rset
2476The wait for a reply from a RSET command
2477[5m, unspecified].
2478.ip quit
2479The wait for a reply from a QUIT command
2480[2m, unspecified].
2481.ip misc
2482The wait for a reply from miscellaneous (but short) commands
2483such as NOOP (no-operation) and VERB (go into verbose mode).
2484[2m, unspecified].
2485.ip command\(dg\(dd
2486In server SMTP,
2487the time to wait for another command.
2488[1h, 5m].
2489.ip ident\(dd
2490The timeout waiting for a reply to an IDENT query
2491[5s\**, unspecified].
2492.(f
2493\**On some systems the default is zero to turn the protocol off entirely.
2494.)f
2495.ip lhlo
2496The wait for a reply to an LMTP LHLO command
2497[2m, unspecified].
2498.ip auth
2499The timeout for a reply in an SMTP AUTH dialogue
2500[10m, unspecified].
2501.ip starttls
2502The timeout for a reply to an SMTP STARTTLS command and the TLS handshake
2503[1h, unspecified].
2504.ip fileopen\(dd
2505The timeout for opening .forward and :include: files [60s, none].
2506.ip control\(dd
2507The timeout for a complete control socket transaction to complete [2m, none].
2508.ip hoststatus\(dd
2509How long status information about a host
2510(e.g., host down)
2511will be cached before it is considered stale
2512[30m, unspecified].
2513.ip resolver.retrans\(dd
2514The resolver's
2515retransmission time interval
2516(in seconds)
2517[varies].
2518Sets both
2519.i Timeout.resolver.retrans.first
2520and
2521.i Timeout.resolver.retrans.normal .
2522.ip resolver.retrans.first\(dd
2523The resolver's
2524retransmission time interval
2525(in seconds)
2526for the first attempt to
2527deliver a message
2528[varies].
2529.ip resolver.retrans.normal\(dd
2530The resolver's
2531retransmission time interval
2532(in seconds)
2533for all resolver lookups
2534except the first delivery attempt
2535[varies].
2536.ip resolver.retry\(dd
2537The number of times
2538to retransmit a resolver query.
2539Sets both
2540.i Timeout.resolver.retry.first
2541and
2542.i Timeout.resolver.retry.normal
2543[varies].
2544.ip resolver.retry.first\(dd
2545The number of times
2546to retransmit a resolver query
2547for the first attempt
2548to deliver a message
2549[varies].
2550.ip resolver.retry.normal\(dd
2551The number of times
2552to retransmit a resolver query
2553for all resolver lookups
2554 except the first delivery attempt
2555[varies].
2556.lp
2557For compatibility with old configuration files,
2558if no
2559.i suboption
2560is specified,
2561all the timeouts marked with
2562.DG
2563(\(dg) are set to the indicated value.
2564All but those marked with
2565.DD
2566(\(dd) apply to client SMTP.
2567.pp
2568For example, the lines:
2569.(b
2570O Timeout.command=25m
2571O Timeout.datablock=3h
2572.)b
2573sets the server SMTP command timeout to 25 minutes
2574and the input data block timeout to three hours.
2575.sh 3 "Message timeouts"
2576.pp
2577After sitting in the queue for a few days,
2578an undeliverable message will time out.
2579This is to insure that at least the sender is aware
2580of the inability to send a message.
2581The timeout is typically set to five days.
2582It is sometimes considered convenient to also send a warning message
2583if the message is in the queue longer than a few hours
2584(assuming you normally have good connectivity;
2585if your messages normally took several hours to send
2586you wouldn't want to do this because it wouldn't be an unusual event).
2587These timeouts are set using the
2588.b Timeout.queuereturn
2589and
2590.b Timeout.queuewarn
2591options in the configuration file
2592(previously both were set using the
2593.b T
2594option).
2595.pp
2596If the message is submitted using the
2597.sm NOTIFY
2598.sm SMTP
2599extension,
2600warning messages will only be sent if
2601.sm NOTIFY=DELAY
2602is specified.
2603The queuereturn and queuewarn timeouts
2604can be further qualified with a tag based on the Precedence: field
2605in the message;
2606they must be one of
2607.q urgent
2608(indicating a positive non-zero precedence)
2609.q normal
2610(indicating a zero precedence), or
2611.q non-urgent
2612(indicating negative precedences).
2613For example, setting
2614.q Timeout.queuewarn.urgent=1h
2615sets the warning timeout for urgent messages only
2616to one hour.
2617The default if no precedence is indicated
2618is to set the timeout for all precedences.
2619The value "now" can be used for
2620-O Timeout.queuereturn
2621to return entries immediately during a queue run,
2622e.g., to bounce messages independent of their time in the queue.
2623.pp
2624Since these options are global,
2625and since you cannot know
2626.i "a priori"
2627how long another host outside your domain will be down,
2628a five day timeout is recommended.
2629This allows a recipient to fix the problem even if it occurs
2630at the beginning of a long weekend.
2631RFC 1123 section 5.3.1.1 says that this parameter
2632should be ``at least 4\-5 days''.
2633.pp
2634The
2635.b Timeout.queuewarn
2636value can be piggybacked on the
2637.b T
2638option by indicating a time after which
2639a warning message should be sent;
2640the two timeouts are separated by a slash.
2641For example, the line
2642.(b
2643OT5d/4h
2644.)b
2645causes email to fail after five days,
2646but a warning message will be sent after four hours.
2647This should be large enough that the message will have been tried
2648several times.
2649.sh 2 "Forking During Queue Runs"
2650.pp
2651By setting the
2652.b ForkEachJob
2653(\c
2654.b Y )
2655option,
2656.i sendmail
2657will fork before each individual message
2658while running the queue.
2659This option was used with earlier releases to prevent
2660.i sendmail
2661from consuming large amounts of memory.
2662It should no longer be necessary with
2663.i sendmail
26648.12.
2665If the
2666.b ForkEachJob
2667option is not set,
2668.i sendmail
2669will keep track of hosts that are down during a queue run,
2670which can improve performance dramatically.
2671.pp
2672If the
2673.b ForkEachJob
2674option is set,
2675.i sendmail
2676cannot use connection caching.
2677.sh 2 "Queue Priorities"
2678.pp
2679Every message is assigned a priority when it is first instantiated,
2680consisting of the message size (in bytes)
2681offset by the message class
2682(which is determined from the Precedence: header)
2683times the
2684.q "work class factor"
2685and the number of recipients times the
2686.q "work recipient factor."
2687The priority is used to order the queue.
2688Higher numbers for the priority mean that the message will be processed later
2689when running the queue.
2690.pp
2691The message size is included so that large messages are penalized
2692relative to small messages.
2693The message class allows users to send
2694.q "high priority"
2695messages by including a
2696.q Precedence:
2697field in their message;
2698the value of this field is looked up in the
2699.b P
2700lines of the configuration file.
2701Since the number of recipients affects the amount of load a message presents
2702to the system,
2703this is also included into the priority.
2704.pp
2705The recipient and class factors
2706can be set in the configuration file using the
2707.b RecipientFactor
2708(\c
2709.b y )
2710and
2711.b ClassFactor
2712(\c
2713.b z )
2714options respectively.
2715They default to 30000 (for the recipient factor)
2716and 1800
2717(for the class factor).
2718The initial priority is:
2719.EQ
2720pri = msgsize - (class times bold ClassFactor) + (nrcpt times bold RecipientFactor)
2721.EN
2722(Remember, higher values for this parameter actually mean
2723that the job will be treated with lower priority.)
2724.pp
2725The priority of a job can also be adjusted each time it is processed
2726(that is, each time an attempt is made to deliver it)
2727using the
2728.q "work time factor,"
2729set by the
2730.b RetryFactor
2731(\c
2732.b Z )
2733option.
2734This is added to the priority,
2735so it normally decreases the precedence of the job,
2736on the grounds that jobs that have failed many times
2737will tend to fail again in the future.
2738The
2739.b RetryFactor
2740option defaults to 90000.
2741.sh 2 "Load Limiting"
2742.pp
2743.i Sendmail
2744can be asked to queue (but not deliver) mail
2745if the system load average gets too high using the
2746.b QueueLA
2747(\c
2748.b x )
2749option.
2750When the load average exceeds the value of the
2751.b QueueLA
2752option, the delivery mode is set to
2753.b q
2754(queue only) if the
2755.b QueueFactor
2756(\c
2757.b q )
2758option divided by the difference in the current load average and the
2759.b QueueLA
2760option plus one
2761is less than the priority of the message \(em
2762that is, the message is queued iff:
2763.EQ
2764pri > { bold QueueFactor } over { LA - { bold QueueLA } + 1 }
2765.EN
2766The
2767.b QueueFactor
2768option defaults to 600000,
2769so each point of load average is worth 600000 priority points
2770(as described above).
2771.pp
2772For drastic cases, the
2773.b RefuseLA
2774(\c
2775.b X )
2776option defines a load average at which
2777.i sendmail
2778will refuse to accept network connections.
2779Locally generated mail, i.e., mail which is not submitted via SMTP
2780(including incoming UUCP mail),
2781is still accepted.
2782Notice that the MSP submits mail to the MTA via SMTP, and hence
2783mail will be queued in the client queue in such a case.
2784Therefore it is necessary to run the client mail queue periodically.
2785.sh 2 "Resource Limits"
2786.pp
2787.i Sendmail
2788has several parameters to control resource usage.
2789Besides those mentionted in the previous section, there are at least
2790.b MaxDaemonChildren ,
2791.b ConnectionRateThrottle ,
2792.b MaxQueueChildren ,
2793and
2794.b MaxRunnersPerQueue .
2795The latter two limit the number of
2796.i sendmail
2797processes that operate on the queue.
2798These are discussed in the section
2799``Queue Group Declaration''.
2800The former two can be used to limit the number of incoming connections.
2801Their appropriate values depend on the host operating system and
2802the hardware, e.g., amount of memory.
2803In many situations it might be useful to set limits to prevent
2804to have too many
2805.i sendmail
2806processes, however, these limits can be abused to mount a
2807denial of service attack.
2808For example, if
2809.b MaxDaemonChildren=10
2810then an attacker needs to open only 10 SMTP sessions to the server,
2811leave them idle for most of the time,
2812and no more connections will be accepted.
2813.sh 2 "Delivery Mode"
2814.pp
2815There are a number of delivery modes that
2816.i sendmail
2817can operate in,
2818set by the
2819.b DeliveryMode
2820(\c
2821.b d )
2822configuration option.
2823These modes
2824specify how quickly mail will be delivered.
2825Legal modes are:
2826.(b
2827.ta 4n
2828i deliver interactively (synchronously)
2829b deliver in background (asynchronously)
2830q queue only (don't deliver)
2831d defer delivery attempts (don't deliver)
2832.)b
2833There are tradeoffs.
2834Mode
2835.q i
2836gives the sender the quickest feedback,
2837but may slow down some mailers and
2838is hardly ever necessary.
2839Mode
2840.q b
2841delivers promptly but
2842can cause large numbers of processes
2843if you have a mailer that takes a long time to deliver a message.
2844Mode
2845.q q
2846minimizes the load on your machine,
2847but means that delivery may be delayed for up to the queue interval.
2848Mode
2849.q d
2850is identical to mode
2851.q q
2852except that it also prevents lookups in maps including the
2853.b -D
2854flag from working during the initial queue phase;
2855it is intended for ``dial on demand'' sites where DNS lookups
2856might cost real money.
2857Some simple error messages
2858(e.g., host unknown during the SMTP protocol)
2859will be delayed using this mode.
2860Mode
2861.q b
2862is the usual default.
2863.pp
2864If you run in mode
2865.q q
2866(queue only),
2867.q d
2868(defer),
2869or
2870.q b
2871(deliver in background)
2872.i sendmail
2873will not expand aliases and follow .forward files
2874upon initial receipt of the mail.
2875This speeds up the response to RCPT commands.
2876Mode
2877.q i
2878should not be used by the SMTP server.
2879.sh 2 "Log Level"
2880.pp
2881The level of logging can be set for
2882.i sendmail .
2883The default using a standard configuration table is level 9.
2884The levels are as follows:
2885.nr ii 0.5i
2886.ip 0
2887Minimal logging.
2888.ip 1
2889Serious system failures and potential security problems.
2890.ip 2
2891Lost communications (network problems) and protocol failures.
2892.ip 3
2893Other serious failures, malformed addresses, transient forward/include
2894errors, connection timeouts.
2895.ip 4
2896Minor failures, out of date alias databases, connection rejections
2897via check_ rulesets.
2898.ip 5
2899Message collection statistics.
2900.ip 6
2901Creation of error messages,
2902VRFY and EXPN commands.
2903.ip 7
2904Delivery failures (host or user unknown, etc.).
2905.ip 8
2906Successful deliveries and alias database rebuilds.
2907.ip 9
2908Messages being deferred
2909(due to a host being down, etc.).
2910.ip 10
2911Database expansion (alias, forward, and userdb lookups)
2912and authentication information.
2913.ip 11
2914NIS errors and end of job processing.
2915.ip 12
2916Logs all SMTP connections.
2917.ip 13
2918Log bad user shells, files with improper permissions, and other
2919questionable situations.
2920.ip 14
2921Logs refused connections.
2922.ip 15
2923Log all incoming and outgoing SMTP commands.
2924.ip 20
2925Logs attempts to run locked queue files.
2926These are not errors,
2927but can be useful to note if your queue appears to be clogged.
2928.ip 30
2929Lost locks (only if using lockf instead of flock).
2930.lp
2931Additionally,
2932values above 64 are reserved for extremely verbose debugging output.
2933No normal site would ever set these.
2934.sh 2 "File Modes"
2935.pp
2936The modes used for files depend on what functionality you want
2937and the level of security you require.
2938In many cases
2939.i sendmail
2940does careful checking of the modes
2941of files and directories
2942to avoid accidental compromise;
2943if you want to make it possible to have group-writable support files
2944you may need to use the
2945.b DontBlameSendmail
2946option to turn off some of these checks.
2947.sh 3 "To suid or not to suid?"
2948.pp
2949.i Sendmail
2950is no longer installed
2951set-user-ID to root.
2952sendmail/SECURITY
2953explains how to configure and install
2954.i sendmail
2955without set-user-ID to root but set-group-ID
2956which is the default configuration starting with 8.12.
2957.pp
2958The daemon usually runs as root, unless other measures are taken.
2959At the point where
2960.i sendmail
2961is about to
2962.i exec \|(2)
2963a mailer,
2964it checks to see if the userid is zero (root);
2965if so,
2966it resets the userid and groupid to a default
2967(set by the
2968.b U=
2969equate in the mailer line;
2970if that is not set, the
2971.b DefaultUser
2972option is used).
2973This can be overridden
2974by setting the
2975.b S
2976flag to the mailer
2977for mailers that are trusted
2978and must be called as root.
2979However,
2980this will cause mail processing
2981to be accounted
2982(using
2983.i sa \|(8))
2984to root
2985rather than to the user sending the mail.
2986.pp
2987A middle ground is to set the
2988.b RunAsUser
2989option.
2990This causes
2991.i sendmail
2992to become the indicated user as soon as it has done the startup
2993that requires root privileges
2994(primarily, opening the
2995.sm SMTP
2996socket).
2997If you use
2998.b RunAsUser ,
2999the queue directory
3000(normally
3001.i /var/spool/mqueue )
3002should be owned by that user,
3003and all files and databases
3004(including user
3005.i \&.forward
3006files,
3007alias files,
3008:include: files,
3009and external databases)
3010must be readable by that user.
3011Also, since sendmail will not be able to change it's uid,
3012delivery to programs or files will be marked as unsafe,
3013e.g., undeliverable,
3014in
3015.i \&.forward ,
3016aliases,
3017and :include: files.
3018Administrators can override this by setting the
3019.b DontBlameSendmail
3020option to the setting
3021.b NonRootSafeAddr .
3022.b RunAsUser
3023is probably best suited for firewall configurations
3024that don't have regular user logins.
3025.sh 3 "Turning off security checks"
3026.pp
3027.i Sendmail
3028is very particular about the modes of files that it reads or writes.
3029For example, by default it will refuse to read most files
3030that are group writable
3031on the grounds that they might have been tampered with
3032by someone other than the owner;
3033it will even refuse to read files in group writable directories.
3034Also, sendmail will refuse to create a new aliases database in an
3035unsafe directory. You can get around this by manually creating the
3036database file as a trusted user ahead of time and then rebuilding the
3037aliases database with
3038.b newaliases .
3039.pp
3040If you are
3041.i quite
3042sure that your configuration is safe and you want
3043.i sendmail
3044to avoid these security checks,
3045you can turn off certain checks using the
3046.b DontBlameSendmail
3047option.
3048This option takes one or more names that disable checks.
3049In the descriptions that follow,
3050.q "unsafe directory"
3051means a directory that is writable by anyone other than the owner.
3052The values are:
3053.nr ii 0.5i
3054.ip Safe
3055No special handling.
3056.ip AssumeSafeChown
3057Assume that the
3058.i chown
3059system call is restricted to root.
3060Since some versions of UNIX permit regular users
3061to give away their files to other users on some filesystems,
3062.i sendmail
3063often cannot assume that a given file was created by the owner,
3064particularly when it is in a writable directory.
3065You can set this flag if you know that file giveaway is restricted
3066on your system.
3067.ip ClassFileInUnsafeDirPath
3068When reading class files (using the
3069.b F
3070line in the configuration file),
3071allow files that are in unsafe directories.
3072.ip DontWarnForwardFileInUnsafeDirPath
3073Prevent logging of
3074unsafe directory path warnings
3075for non-existent forward files.
3076.ip ErrorHeaderInUnsafeDirPath
3077Allow the file named in the
3078.b ErrorHeader
3079option to be in an unsafe directory.
3080.ip FileDeliveryToHardLink
3081Allow delivery to files that are hard links.
3082.ip FileDeliveryToSymLink
3083Allow delivery to files that are symbolic links.
3084.ip ForwardFileInGroupWritableDirPath
3085Allow
3086.i \&.forward
3087files in group writable directories.
3088.ip ForwardFileInUnsafeDirPath
3089Allow
3090.i \&.forward
3091files in unsafe directories.
3092.ip ForwardFileInUnsafeDirPathSafe
3093Allow a
3094.i \&.forward
3095file that is in an unsafe directory to include references
3096to program and files.
3097.ip GroupReadableKeyFile
3098Accept a group-readable key file for STARTTLS.
3099.ip GroupReadableSASLDBFile
3100Accept a group-readable Cyrus SASL password file.
3101.ip GroupWritableAliasFile
3102Allow group-writable alias files.
3103.ip GroupWritableDirPathSafe
3104Change the definition of
3105.q "unsafe directory"
3106to consider group-writable directories to be safe.
3107World-writable directories are always unsafe.
3108.ip GroupWritableForwardFile
3109Allow group writable
3110.i \&.forward
3111files.
3112.ip GroupWritableForwardFileSafe
3113Accept group-writable
3114.i \&.forward
3115files as safe for program and file delivery.
3116.ip GroupWritableIncludeFile
3117Allow group wriable
3118.i :include:
3119files.
3120.ip GroupWritableIncludeFileSafe
3121Accept group-writable
3122.i :include:
3123files as safe for program and file delivery.
3124.ip GroupWritableSASLDBFile
3125Accept a group-writable Cyrus SASL password file.
3126.ip HelpFileInUnsafeDirPath
3127Allow the file named in the
3128.b HelpFile
3129option to be in an unsafe directory.
3130.ip IncludeFileInGroupWritableDirPath
3131Allow
3132.i :include:
3133files in group writable directories.
3134.ip IncludeFileInUnsafeDirPath
3135Allow
3136.i :include:
3137files in unsafe directories.
3138.ip IncludeFileInUnsafeDirPathSafe
3139Allow a
3140.i :include:
3141file that is in an unsafe directory to include references
3142to program and files.
3143.ip InsufficientEntropy
3144Try to use STARTTLS even if the PRNG for OpenSSL is not properly seeded
3145despite the security problems.
3146.ip LinkedAliasFileInWritableDir
3147Allow an alias file that is a link in a writable directory.
3148.ip LinkedClassFileInWritableDir
3149Allow class files that are links in writable directories.
3150.ip LinkedForwardFileInWritableDir
3151Allow
3152.i \&.forward
3153files that are links in writable directories.
3154.ip LinkedIncludeFileInWritableDir
3155Allow
3156.i :include:
3157files that are links in writable directories.
3158.ip LinkedMapInWritableDir
3159Allow map files that are links in writable directories.
3160This includes alias database files.
3161.ip LinkedServiceSwitchFileInWritableDir
3162Allow the service switch file to be a link
3163even if the directory is writable.
3164.ip MapInUnsafeDirPath
3165Allow maps (e.g.,
3166.i hash ,
3167.i btree ,
3168and
3169.i dbm
3170files)
3171in unsafe directories.
3172This includes alias database files.
3173.ip NonRootSafeAddr
3174Do not mark file and program deliveries as unsafe
3175if sendmail is not running with root privileges.
3176.ip RunProgramInUnsafeDirPath
3177Run programs that are in writable directories without logging a warning.
3178.ip RunWritableProgram
3179Run programs that are group- or world-writable without logging a warning.
3180.ip TrustStickyBit
3181Allow group or world writable directories
3182if the sticky bit is set on the directory.
3183Do not set this on systems which do not honor
3184the sticky bit on directories.
3185.ip WorldWritableAliasFile
3186Accept world-writable alias files.
3187.ip WorldWritableForwardfile
3188Allow world writable
3189.i \&.forward
3190files.
3191.ip WorldWritableIncludefile
3192Allow world wriable
3193.i :include:
3194files.
3195.ip WriteMapToHardLink
3196Allow writes to maps that are hard links.
3197.ip WriteMapToSymLink
3198Allow writes to maps that are symbolic links.
3199.ip WriteStatsToHardLink
3200Allow the status file to be a hard link.
3201.ip WriteStatsToSymLink
3202Allow the status file to be a symbolic link.
3203.sh 2 "Connection Caching"
3204.pp
3205When processing the queue,
3206.i sendmail
3207will try to keep the last few open connections open
3208to avoid startup and shutdown costs.
3209This only applies to IPC connections.
3210.pp
3211When trying to open a connection
3212the cache is first searched.
3213If an open connection is found, it is probed to see if it is still active
3214by sending a
3215.sm RSET
3216command.
3217It is not an error if this fails;
3218instead, the connection is closed and reopened.
3219.pp
3220Two parameters control the connection cache.
3221The
3222.b ConnectionCacheSize
3223(\c
3224.b k )
3225option defines the number of simultaneous open connections
3226that will be permitted.
3227If it is set to zero,
3228connections will be closed as quickly as possible.
3229The default is one.
3230This should be set as appropriate for your system size;
3231it will limit the amount of system resources that
3232.i sendmail
3233will use during queue runs.
3234Never set this higher than 4.
3235.pp
3236The
3237.b ConnectionCacheTimeout
3238(\c
3239.b K )
3240option specifies the maximum time that any cached connection
3241will be permitted to idle.
3242When the idle time exceeds this value
3243the connection is closed.
3244This number should be small
3245(under ten minutes)
3246to prevent you from grabbing too many resources
3247from other hosts.
3248The default is five minutes.
3249.sh 2 "Name Server Access"
3250.pp
3251Control of host address lookups is set by the
3252.b hosts
3253service entry in your service switch file.
3254If you are on a system that has built-in service switch support
3255(e.g., Ultrix, Solaris, or DEC OSF/1)
3256then your system is probably configured properly already.
3257Otherwise,
3258.i sendmail
3259will consult the file
3260.b /etc/mail/service.switch ,
3261which should be created.
3262.i Sendmail
3263only uses two entries:
3264.b hosts
3265and
3266.b aliases ,
3267although system routines may use other services
3268(notably the
3269.b passwd
3270service for user name lookups by
3271.i getpwname ).
3272.pp
3273However, some systems (such as SunOS 4.X)
3274will do DNS lookups
3275regardless of the setting of the service switch entry.
3276In particular, the system routine
3277.i gethostbyname (3)
3278is used to look up host names,
3279and many vendor versions try some combination of DNS, NIS,
3280and file lookup in /etc/hosts
3281without consulting a service switch.
3282.i Sendmail
3283makes no attempt to work around this problem,
3284and the DNS lookup will be done anyway.
3285If you do not have a nameserver configured at all,
3286such as at a UUCP-only site,
3287.i sendmail
3288will get a
3289.q "connection refused"
3290message when it tries to connect to the name server.
3291If the
3292.b hosts
3293switch entry has the service
3294.q dns
3295listed somewhere in the list,
3296.i sendmail
3297will interpret this to mean a temporary failure
3298and will queue the mail for later processing;
3299otherwise, it ignores the name server data.
3300.pp
3301The same technique is used to decide whether to do MX lookups.
3302If you want MX support, you
3303.i must
3304have
3305.q dns
3306listed as a service in the
3307.b hosts
3308switch entry.
3309.pp
3310The
3311.b ResolverOptions
3312(\c
3313.b I )
3314option allows you to tweak name server options.
3315The command line takes a series of flags as documented in
3316.i resolver (3)
3317(with the leading
3318.q RES_
3319deleted).
3320Each can be preceded by an optional `+' or `\(mi'.
3321For example, the line
3322.(b
3323O ResolverOptions=+AAONLY \(miDNSRCH
3324.)b
3325turns on the AAONLY (accept authoritative answers only)
3326and turns off the DNSRCH (search the domain path) options.
3327Most resolver libraries default DNSRCH, DEFNAMES, and RECURSE
3328flags on and all others off.
3329If NETINET6 is enabled, most libraries default to USE_INET6 as well.
3330You can also include
3331.q HasWildcardMX
3332to specify that there is a wildcard MX record matching your domain;
3333this turns off MX matching when canonifying names,
3334which can lead to inappropriate canonifications.
3335Use
3336.q WorkAroundBrokenAAAA
3337when faced with a a broken nameservers that returns SERVFAIL
3338(a temporary failure)
3339on T_AAAA (IPv6) lookups
3340during hostname canonification.
3341Notice: it might be necessary to apply the same (or similar) options to
3342.i submit.cf
3343too.
3344.pp
3345Version level 1 configurations (see the section about
3346Configuration Version Level)
3347turn DNSRCH and DEFNAMES off when doing delivery lookups,
3348but leave them on everywhere else.
3349Version 8 of
3350.i sendmail
3351ignores them when doing canonification lookups
3352(that is, when using $[ ... $]),
3353and always does the search.
3354If you don't want to do automatic name extension,
3355don't call $[ ... $].
3356.pp
3357The search rules for $[ ... $] are somewhat different than usual.
3358If the name being looked up
3359has at least one dot, it always tries the unmodified name first.
3360If that fails, it tries the reduced search path,
3361and lastly tries the unmodified name
3362(but only for names without a dot,
3363since names with a dot have already been tried).
3364This allows names such as
3365``utc.CS''
3366to match the site in Czechoslovakia
3367rather than the site in your local Computer Science department.
3368It also prefers A and CNAME records over MX records \*-
3369that is, if it finds an MX record it makes note of it,
3370but keeps looking.
3371This way, if you have a wildcard MX record matching your domain,
3372it will not assume that all names match.
3373.pp
3374To completely turn off all name server access
3375on systems without service switch support
3376(such as SunOS 4.X)
3377you will have to recompile with
3378\-DNAMED_BIND=0
3379and remove \-lresolv from the list of libraries to be searched
3380when linking.
3381.sh 2 "Moving the Per-User Forward Files"
3382.pp
3383Some sites mount each user's home directory
3384from a local disk on their workstation,
3385so that local access is fast.
3386However, the result is that .forward file lookups
3387from a central mail server are slow.
3388In some cases,
3389mail can even be delivered on machines inappropriately
3390because of a file server being down.
3391The performance can be especially bad if you run the automounter.
3392.pp
3393The
3394.b ForwardPath
3395(\c
3396.b J )
3397option allows you to set a path of forward files.
3398For example, the config file line
3399.(b
3400O ForwardPath=/var/forward/$u:$z/.forward.$w
3401.)b
3402would first look for a file with the same name as the user's login
3403in /var/forward;
3404if that is not found (or is inaccessible)
3405the file
3406``.forward.\c
3407.i machinename ''
3408in the user's home directory is searched.
3409A truly perverse site could also search by sender
3410by using $r, $s, or $f.
3411.pp
3412If you create a directory such as /var/forward,
3413it should be mode 1777
3414(that is, the sticky bit should be set).
3415Users should create the files mode 0644.
3416Note that you must use the
3417ForwardFileInUnsafeDirPath and
3418ForwardFileInUnsafeDirPathSafe
3419flags with the
3420.b DontBlameSendmail
3421option to allow forward files in a world writable directory.
3422This might also be used as a denial of service attack
3423(users could create forward files for other users);
3424a better approach might be to create
3425/var/forward
3426mode 0755
3427and create empty files for each user,
3428owned by that user,
3429mode 0644.
3430If you do this, you don't have to set the DontBlameSendmail options
3431indicated above.
3432.sh 2 "Free Space"
3433.pp
3434On systems that have one of the system calls in the
3435.i statfs (2)
3436family
3437(including
3438.i statvfs
3439and
3440.i ustat ),
3441you can specify a minimum number of free blocks on the queue filesystem
3442using the
3443.b MinFreeBlocks
3444(\c
3445.b b )
3446option.
3447If there are fewer than the indicated number of blocks free
3448on the filesystem on which the queue is mounted
3449the SMTP server will reject mail
3450with the
3451452 error code.
3452This invites the SMTP client to try again later.
3453.pp
3454Beware of setting this option too high;
3455it can cause rejection of email
3456when that mail would be processed without difficulty.
3457.sh 2 "Maximum Message Size"
3458.pp
3459To avoid overflowing your system with a large message,
3460the
3461.b MaxMessageSize
3462option can be set to set an absolute limit
3463on the size of any one message.
3464This will be advertised in the ESMTP dialogue
3465and checked during message collection.
3466.sh 2 "Privacy Flags"
3467.pp
3468The
3469.b PrivacyOptions
3470(\c
3471.b p )
3472option allows you to set certain
3473``privacy''
3474flags.
3475Actually, many of them don't give you any extra privacy,
3476rather just insisting that client SMTP servers
3477use the HELO command
3478before using certain commands
3479or adding extra headers to indicate possible spoof attempts.
3480.pp
3481The option takes a series of flag names;
3482the final privacy is the inclusive or of those flags.
3483For example:
3484.(b
3485O PrivacyOptions=needmailhelo, noexpn
3486.)b
3487insists that the HELO or EHLO command be used before a MAIL command is accepted
3488and disables the EXPN command.
3489.pp
3490The flags are detailed in section
3491.\"XREF
34925.6.
3493.sh 2 "Send to Me Too"
3494.pp
3495Beginning with version 8.10,
3496.i sendmail
3497includes by default the (envelope) sender in any list expansions.
3498For example, if
3499.q matt
3500sends to a list that contains
3501.q matt
3502as one of the members he will get a copy of the message.
3503If the
3504.b MeToo
3505option is set to
3506.sm FALSE
3507(in the configuration file or via the command line),
3508this behavior is changed, i.e.,
3509the (envelope) sender is excluded in list expansions.
3510.sh 1 "THE WHOLE SCOOP ON THE CONFIGURATION FILE"
3511.pp
3512This section describes the configuration file
3513in detail.
3514.pp
3515There is one point that should be made clear immediately:
3516the syntax of the configuration file
3517is designed to be reasonably easy to parse,
3518since this is done every time
3519.i sendmail
3520starts up,
3521rather than easy for a human to read or write.
3522The configuration file should be generated via the method described in
3523.b cf/README ,
3524it should not be edited directly unless someone is familiar
3525with the internals of the syntax described here and it is
3526not possible to achieve the desired result via the default method.
3527.pp
3528The configuration file is organized as a series of lines,
3529each of which begins with a single character
3530defining the semantics for the rest of the line.
3531Lines beginning with a space or a tab
3532are continuation lines
3533(although the semantics are not well defined in many places).
3534Blank lines and lines beginning with a sharp symbol
3535(`#')
3536are comments.
3537.sh 2 "R and S \*- Rewriting Rules"
3538.pp
3539The core of address parsing
3540are the rewriting rules.
3541These are an ordered production system.
3542.i Sendmail
3543scans through the set of rewriting rules
3544looking for a match on the left hand side
3545(LHS)
3546of the rule.
3547When a rule matches,
3548the address is replaced by the right hand side
3549(RHS)
3550of the rule.
3551.pp
3552There are several sets of rewriting rules.
3553Some of the rewriting sets are used internally
3554and must have specific semantics.
3555Other rewriting sets
3556do not have specifically assigned semantics,
3557and may be referenced by the mailer definitions
3558or by other rewriting sets.
3559.pp
3560The syntax of these two commands are:
3561.(b F
3562.b S \c
3563.i n
3564.)b
3565Sets the current ruleset being collected to
3566.i n .
3567If you begin a ruleset more than once
3568it appends to the old definition.
3569.(b F
3570.b R \c
3571.i lhs
3572.i rhs
3573.i comments
3574.)b
3575The
3576fields must be separated
3577by at least one tab character;
3578there may be embedded spaces
3579in the fields.
3580The
3581.i lhs
3582is a pattern that is applied to the input.
3583If it matches,
3584the input is rewritten to the
3585.i rhs .
3586The
3587.i comments
3588are ignored.
3589.pp
3590Macro expansions of the form
3591.b $ \c
3592.i x
3593are performed when the configuration file is read.
3594A literal
3595.b $
3596can be included using
3597.b $$ .
3598Expansions of the form
3599.b $& \c
3600.i x
3601are performed at run time using a somewhat less general algorithm.
3602This is intended only for referencing internally defined macros
3603such as
3604.b $h
3605that are changed at runtime.
3606.sh 3 "The left hand side"
3607.pp
3608The left hand side of rewriting rules contains a pattern.
3609Normal words are simply matched directly.
3610Metasyntax is introduced using a dollar sign.
3611The metasymbols are:
3612.(b
3613.ta \w'\fB$=\fP\fIx\fP 'u
3614\fB$*\fP Match zero or more tokens
3615\fB$+\fP Match one or more tokens
3616\fB$\-\fP Match exactly one token
3617\fB$=\fP\fIx\fP Match any phrase in class \fIx\fP
3618\fB$~\fP\fIx\fP Match any word not in class \fIx\fP
3619.)b
3620If any of these match,
3621they are assigned to the symbol
3622.b $ \c
3623.i n
3624for replacement on the right hand side,
3625where
3626.i n
3627is the index in the LHS.
3628For example,
3629if the LHS:
3630.(b
3631$\-:$+
3632.)b
3633is applied to the input:
3634.(b
3635UCBARPA:eric
3636.)b
3637the rule will match, and the values passed to the RHS will be:
3638.(b
3639.ta 4n
3640$1 UCBARPA
3641$2 eric
3642.)b
3643.pp
3644Additionally, the LHS can include
3645.b $@
3646to match zero tokens.
3647This is
3648.i not
3649bound to a
3650.b $ \c
3651.i n
3652on the RHS, and is normally only used when it stands alone
3653in order to match the null input.
3654.sh 3 "The right hand side"
3655.pp
3656When the left hand side of a rewriting rule matches,
3657the input is deleted and replaced by the right hand side.
3658Tokens are copied directly from the RHS
3659unless they begin with a dollar sign.
3660Metasymbols are:
3661.(b
3662.ta \w'$#mailer\0\0\0'u
3663\fB$\fP\fIn\fP Substitute indefinite token \fIn\fP from LHS
3664\fB$[\fP\fIname\fP\fB$]\fP Canonicalize \fIname\fP
3665\fB$(\fP\fImap key\fP \fB$@\fP\fIarguments\fP \fB$:\fP\fIdefault\fP \fB$)\fP
3666 Generalized keyed mapping function
3667\fB$>\fP\fIn\fP \*(lqCall\*(rq ruleset \fIn\fP
3668\fB$#\fP\fImailer\fP Resolve to \fImailer\fP
3669\fB$@\fP\fIhost\fP Specify \fIhost\fP
3670\fB$:\fP\fIuser\fP Specify \fIuser\fP
3671.)b
3672.pp
3673The
3674.b $ \c
3675.i n
3676syntax substitutes the corresponding value from a
3677.b $+ ,
3678.b $\- ,
3679.b $* ,
3680.b $= ,
3681or
3682.b $~
3683match on the LHS.
3684It may be used anywhere.
3685.pp
3686A host name enclosed between
3687.b $[
3688and
3689.b $]
3690is looked up in the host database(s)
3691and replaced by the canonical name\**.
3692.(f
3693\**This is actually
3694completely equivalent
3695to $(host \fIhostname\fP$).
3696In particular, a
3697.b $:
3698default can be used.
3699.)f
3700For example,
3701.q $[ftp$]
3702might become
3703.q ftp.CS.Berkeley.EDU
3704and
3705.q $[[128.32.130.2]$]
3706would become
3707.q vangogh.CS.Berkeley.EDU.
3708.i Sendmail
3709recognizes its numeric IP address
3710without calling the name server
3711and replaces it with its canonical name.
3712.pp
3713The
3714.b $(
3715\&...
3716.b $)
3717syntax is a more general form of lookup;
3718it uses a named map instead of an implicit map.
3719If no lookup is found, the indicated
3720.i default
3721is inserted;
3722if no default is specified and no lookup matches,
3723the value is left unchanged.
3724The
3725.i arguments
3726are passed to the map for possible use.
3727.pp
3728The
3729.b $> \c
3730.i n
3731syntax
3732causes the remainder of the line to be substituted as usual
3733and then passed as the argument to ruleset
3734.i n .
3735The final value of ruleset
3736.i n
3737then becomes
3738the substitution for this rule.
3739The
3740.b $>
3741syntax expands everything after the ruleset name
3742to the end of the replacement string
3743and then passes that as the initial input to the ruleset.
3744Recursive calls are allowed.
3745For example,
3746.(b
3747$>0 $>3 $1
3748.)b
3749expands $1, passes that to ruleset 3, and then passes the result
3750of ruleset 3 to ruleset 0.
3751.pp
3752The
3753.b $#
3754syntax should
3755.i only
3756be used in ruleset zero,
3757a subroutine of ruleset zero,
3758or rulesets that return decisions (e.g., check_rcpt).
3759It causes evaluation of the ruleset to terminate immediately,
3760and signals to
3761.i sendmail
3762that the address has completely resolved.
3763The complete syntax for ruleset 0 is:
3764.(b
3765\fB$#\fP\fImailer\fP \fB$@\fP\fIhost\fP \fB$:\fP\fIuser\fP
3766.)b
3767This specifies the
3768{mailer, host, user}
37693-tuple necessary to direct the mailer.
3770If the mailer is local
3771the host part may be omitted\**.
3772.(f
3773\**You may want to use it for special
3774.q "per user"
3775extensions.
3776For example, in the address
3777.q jgm+foo@CMU.EDU ;
3778the
3779.q +foo
3780part is not part of the user name,
3781and is passed to the local mailer for local use.
3782.)f
3783The
3784.i mailer
3785must be a single word,
3786but the
3787.i host
3788and
3789.i user
3790may be multi-part.
3791If the
3792.i mailer
3793is the built-in IPC mailer,
3794the
3795.i host
3796may be a colon-separated list of hosts
3797that are searched in order for the first working address
3798(exactly like MX records).
3799The
3800.i user
3801is later rewritten by the mailer-specific envelope rewriting set
3802and assigned to the
3803.b $u
3804macro.
3805As a special case, if the mailer specified has the
3806.b F=@
3807flag specified
3808and the first character of the
3809.b $:
3810value is
3811.q @ ,
3812the
3813.q @
3814is stripped off, and a flag is set in the address descriptor
3815that causes sendmail to not do ruleset 5 processing.
3816.pp
3817Normally, a rule that matches is retried,
3818that is,
3819the rule loops until it fails.
3820A RHS may also be preceded by a
3821.b $@
3822or a
3823.b $:
3824to change this behavior.
3825A
3826.b $@
3827prefix causes the ruleset to return with the remainder of the RHS
3828as the value.
3829A
3830.b $:
3831prefix causes the rule to terminate immediately,
3832but the ruleset to continue;
3833this can be used to avoid continued application of a rule.
3834The prefix is stripped before continuing.
3835.pp
3836The
3837.b $@
3838and
3839.b $:
3840prefixes may precede a
3841.b $>
3842spec;
3843for example:
3844.(b
3845.ta 8n
3846R$+ $: $>7 $1
3847.)b
3848matches anything,
3849passes that to ruleset seven,
3850and continues;
3851the
3852.b $:
3853is necessary to avoid an infinite loop.
3854.pp
3855Substitution occurs in the order described,
3856that is,
3857parameters from the LHS are substituted,
3858hostnames are canonicalized,
3859.q subroutines
3860are called,
3861and finally
3862.b $# ,
3863.b $@ ,
3864and
3865.b $:
3866are processed.
3867.sh 3 "Semantics of rewriting rule sets"
3868.pp
3869There are six rewriting sets
3870that have specific semantics.
3871Five of these are related as depicted by figure 1.
3872.(z
3873.hl
3874.ie n \{\
3875.(c
3876 +---+
3877 -->| 0 |-->resolved address
3878 / +---+
3879 / +---+ +---+
3880 / ---->| 1 |-->| S |--
3881 +---+ / +---+ / +---+ +---+ \e +---+
3882addr-->| 3 |-->| D |-- --->| 4 |-->msg
3883 +---+ +---+ \e +---+ +---+ / +---+
3884 --->| 2 |-->| R |--
3885 +---+ +---+
3886.)c
3887
3888.\}
3889.el \{\
3890.ie !"\*(.T"" \{\
3891.PS
3892boxwid = 0.3i
3893boxht = 0.3i
3894movewid = 0.3i
3895moveht = 0.3i
3896linewid = 0.3i
3897lineht = 0.3i
3898
3899 box invis "addr"; arrow
3900Box3: box "3"
3901A1: arrow
3902BoxD: box "D"; line; L1: Here
3903C: [
3904 C1: arrow; box "1"; arrow; box "S"; line; E1: Here
3905 move to C1 down 0.5; right
3906 C2: arrow; box "2"; arrow; box "R"; line; E2: Here
3907 ] with .w at L1 + (0.5, 0)
3908 move to C.e right 0.5
3909L4: arrow; box "4"; arrow; box invis "msg"
3910 line from L1 to C.C1
3911 line from L1 to C.C2
3912 line from C.E1 to L4
3913 line from C.E2 to L4
3914 move to BoxD.n up 0.6; right
3915Box0: arrow; box "0"
3916 arrow; box invis "resolved address" width 1.3
3917 line from 1/3 of the way between A1 and BoxD.w to Box0
3918.PE
3919.\}
3920.el .sp 2i
3921.\}
3922.ce
3923Figure 1 \*- Rewriting set semantics
3924.(c
3925D \*- sender domain addition
3926S \*- mailer-specific sender rewriting
3927R \*- mailer-specific recipient rewriting
3928.)c
3929.hl
3930.)z
3931.pp
3932Ruleset three
3933should turn the address into
3934.q "canonical form."
3935This form should have the basic syntax:
3936.(b
3937local-part@host-domain-spec
3938.)b
3939Ruleset three
3940is applied by
3941.i sendmail
3942before doing anything with any address.
3943.pp
3944If no
3945.q @
3946sign is specified,
3947then the
3948host-domain-spec
3949.i may
3950be appended (box
3951.q D
3952in Figure 1)
3953from the
3954sender address
3955(if the
3956.b C
3957flag is set in the mailer definition
3958corresponding to the
3959.i sending
3960mailer).
3961.pp
3962Ruleset zero
3963is applied after ruleset three
3964to addresses that are going to actually specify recipients.
3965It must resolve to a
3966.i "{mailer, host, address}"
3967triple.
3968The
3969.i mailer
3970must be defined in the mailer definitions
3971from the configuration file.
3972The
3973.i host
3974is defined into the
3975.b $h
3976macro
3977for use in the argv expansion of the specified mailer.
3978.pp
3979Rulesets one and two
3980are applied to all sender and recipient addresses respectively.
3981They are applied before any specification
3982in the mailer definition.
3983They must never resolve.
3984.pp
3985Ruleset four is applied to all addresses
3986in the message.
3987It is typically used
3988to translate internal to external form.
3989.pp
3990In addition,
3991ruleset 5 is applied to all local addresses
3992(specifically, those that resolve to a mailer with the `F=5'
3993flag set)
3994that do not have aliases.
3995This allows a last minute hook for local names.
3996.sh 3 "Ruleset hooks"
3997.pp
3998A few extra rulesets are defined as
3999.q hooks
4000that can be defined to get special features.
4001They are all named rulesets.
4002The
4003.q check_*
4004forms all give accept/reject status;
4005falling off the end or returning normally is an accept,
4006and resolving to
4007.b $#error
4008is a reject.
4009Many of these can also resolve to the special mailer name
4010.b $#discard ;
4011this accepts the message as though it were successful
4012but then discards it without delivery.
4013Note,
4014this mailer cannot be chosen as a mailer in ruleset 0.
4015Note also that all
4016.q check_*
4017rulesets have to deal with temporary failures, especially for map lookups,
4018themselves, i.e., they should return a temporary error code
4019or at least they should make a proper decision in those cases.
4020.sh 4 "check_relay"
4021.pp
4022The
4023.i check_relay
4024ruleset is called after a connection is accepted by the daemon.
4025It is not called when sendmail is started using the
4026.b \-bs
4027option.
4028It is passed
4029.(b
4030client.host.name $| client.host.address
4031.)b
4032where
4033.b $|
4034is a metacharacter separating the two parts.
4035This ruleset can reject connections from various locations.
4036.sh 4 "check_mail"
4037.pp
4038The
4039.i check_mail
4040ruleset is passed the user name parameter of the
4041.sm "SMTP MAIL"
4042command.
4043It can accept or reject the address.
4044.sh 4 "check_rcpt"
4045.pp
4046The
4047.i check_rcpt
4048ruleset is passed the user name parameter of the
4049.sm "SMTP RCPT"
4050command.
4051It can accept or reject the address.
4052.sh 4 "check_data"
4053.pp
4054The
4055.i check_data
4056ruleset is called after the
4057.sm "SMTP DATA"
4058command, its parameter is the number of recipients.
4059It can accept or reject the command.
4060.sh 4 "check_compat"
4061.pp
4062The
4063.i check_compat
4064ruleset is passed
4065.(b
4066sender-address $| recipient-address
4067.)b
4068where
4069.b $|
4070is a metacharacter separating the addresses.
4071It can accept or reject mail transfer between these two addresses
4072much like the
4073.i checkcompat()
4074function.
4075.sh 4 "check_eoh"
4076.pp
4077The
4078.i check_eoh
4079ruleset is passed
4080.(b
4081number-of-headers $| size-of-headers
4082.)b
4083where
4084.b $|
4085is a metacharacter separating the numbers.
4086These numbers can be used for size comparisons with the
4087.b arith
4088map.
4089The ruleset is triggered after
4090all of the headers have been read.
4091It can be used to correlate information gathered
4092from those headers using the
4093.b macro
4094storage map.
4095One possible use is to check for a missing header.
4096For example:
4097.(b
4098.ta 1.5i
4099Kstorage macro
4100HMessage-Id: $>CheckMessageId
4101
4102SCheckMessageId
4103# Record the presence of the header
4104R$* $: $(storage {MessageIdCheck} $@ OK $) $1
4105R< $+ @ $+ > $@ OK
4106R$* $#error $: 553 Header Error
4107
4108Scheck_eoh
4109# Check the macro
4110R$* $: < $&{MessageIdCheck} >
4111# Clear the macro for the next message
4112R$* $: $(storage {MessageIdCheck} $) $1
4113# Has a Message-Id: header
4114R< $+ > $@ OK
4115# Allow missing Message-Id: from local mail
4116R$* $: < $&{client_name} >
4117R< > $@ OK
4118R< $=w > $@ OK
4119# Otherwise, reject the mail
4120R$* $#error $: 553 Header Error
4121.)b
4122Keep in mind the Message-Id: header is not a required header and
4123is not a guaranteed spam indicator.
4124This ruleset is an example and
4125should probably not be used in production.
4126.sh 4 "check_etrn"
4127.pp
4128The
4129.i check_etrn
4130ruleset is passed the parameter of the
4131.sm "SMTP ETRN"
4132command.
4133It can accept or reject the command.
4134.sh 4 "check_expn"
4135.pp
4136The
4137.i check_expn
4138ruleset is passed the user name parameter of the
4139.sm "SMTP EXPN"
4140command.
4141It can accept or reject the address.
4142.sh 4 "check_vrfy"
4143.pp
4144The
4145.i check_vrfy
4146ruleset is passed the user name parameter of the
4147.sm "SMTP VRFY"
4148command.
4149It can accept or reject the command.
4150.sh 4 "trust_auth"
4151.pp
4152The
4153.i trust_auth
4154ruleset is passed the AUTH= parameter of the
4155.sm "SMTP MAIL"
4156command.
4157It is used to determine whether this value should be
4158trusted. In order to make this decision, the ruleset
4159may make use of the various
4160.b ${auth_*}
4161macros.
4162If the ruleset does resolve to the
4163.q error
4164mailer the AUTH= parameter is not trusted and hence
4165not passed on to the next relay.
4166.sh 4 "tls_client"
4167.pp
4168The
4169.i tls_client
4170ruleset is called when sendmail acts as server, after a STARTTLS command
4171has been issued, and from
4172.i check_mail.
4173The parameter is the value of
4174.b ${verify}
4175and STARTTLS or MAIL, respectively.
4176If the ruleset does resolve to the
4177.q error
4178mailer, the appropriate error code is returned to the client.
4179.sh 4 "tls_server"
4180.pp
4181The
4182.i tls_server
4183ruleset is called when sendmail acts as client after a STARTTLS command
4184(should) have been issued.
4185The parameter is the value of
4186.b ${verify} .
4187If the ruleset does resolve to the
4188.q error
4189mailer, the connection is aborted
4190(treated as non-deliverable with a permanent or temporary error).
4191.sh 4 "tls_rcpt"
4192.pp
4193The
4194.i tls_rcpt
4195ruleset is called each time before a RCPT TO command is sent.
4196The parameter is the current recipient.
4197If the ruleset does resolve to the
4198.q error
4199mailer, the RCPT TO command is suppressed
4200(treated as non-deliverable with a permanent or temporary error).
4201This ruleset allows to require encryption or verification of
4202the recipient's MTA even if the mail is somehow redirected
4203to another host.
4204For example, sending mail to
4205.i luke@endmail.org
4206may get redirected to a host named
4207.i death.star
4208and hence the tls_server ruleset won't apply.
4209By introducing per recipient restrictions such attacks
4210(e.g., via DNS spoofing) can be made impossible.
4211See
4212.i cf/README
4213how this ruleset can be used.
4214.sh 4 "srv_features"
4215.pp
4216The
4217.i srv_features
4218ruleset is called when a client connects to sendmail.
4219This ruleset should return
4220.b $#
4221followed by a list of options (single characters
4222delimited by white space).
4223If the return value starts with anything else it is silently ignored.
4224Generally upper case characters turn off a feature
4225while lower case characters turn it on.
4226The option `S' causes the server not to offer STARTTLS.
4227This is useful to interact with MTAs/MUAs that have broken
4228STARTTLS implementations by simply not offering it.
4229`V' turns off the request for a client certificate
4230during the TLS handshake.
4231Option `A' and `P' suppress SMTP AUTH and PIPELINING, respectively.
4232The ruleset may return `$#temp' to indicate that there is a temporary
4233problem determining the correct features, e.g., if a map is unavailable.
4234In that case, the SMTP server issues a temporary failure and does not
4235accept email.
4236.sh 4 "try_tls"
4237.pp
4238The
4239.i try_tls
4240ruleset is called when sendmail connects to another MTA.
4241If the ruleset does resolve to the
4242.q error
4243mailer, sendmail does not try STARTTLS even if it is offered.
4244This is useful to interact with MTAs that have broken
4245STARTTLS implementations by simply not using it.
4246.sh 4 "authinfo"
4247.pp
4248The
4249.i authinfo
4250ruleset is called when sendmail tries to authenticate to another MTA.
4251It should return
4252.b $#
4253followed by a list of tokens that are used for SMTP AUTH.
4254If the return value starts with anything else it is silently ignored.
4255Each token is a tagged string of the form:
4256"TDstring"
4257(including the quotes), where
4258.(b
4259.ta 9n
4260T Tag which describes the item
4261D Delimiter: ':' simple text follows
4262 '=' string is base64 encoded
4263string Value of the item
4264.)b
4265Valid values for the tag are:
4266.(b
4267.ta 9n
4268U user (authorization) id
4269I authentication id
4270P password
4271R realm
4272M list of mechanisms delimited by spaces
4273.)b
4274If this ruleset is defined, the option
4275.b DefaultAuthInfo
4276is ignored (even if the ruleset does not return a ``useful'' result).
4277.sh 4 "queuegroup"
4278.pp
4279The
4280.i queuegroup
4281ruleset is used to map an address to a queue group name.
4282It should return
4283.b $#
4284followed by the name of a queue group.
4285If the return value starts with anything else it is silently ignored.
4286See the section about Queue Groups and Queue Directories
4287for further information.
4288.sh 3 "IPC mailers"
4289.pp
4290Some special processing occurs
4291if the ruleset zero resolves to an IPC mailer
4292(that is, a mailer that has
4293.q [IPC]
4294listed as the Path in the
4295.b M
4296configuration line.
4297The host name passed after
4298.q $@
4299has MX expansion performed if not delivering via a named socket;
4300this looks the name up in DNS to find alternate delivery sites.
4301.pp
4302The host name can also be provided as a dotted quad
4303or an IPv6 address in square brackets;
4304for example:
4305.(b
4306[128.32.149.78]
4307.)b
4308or
4309.(b
4310[IPv6:2002:c0a8:51d2::23f4]
4311.)b
4312This causes direct conversion of the numeric value
4313to an IP host address.
4314.pp
4315The host name passed in after the
4316.q $@
4317may also be a colon-separated list of hosts.
4318Each is separately MX expanded and the results are concatenated
4319to make (essentially) one long MX list.
4320The intent here is to create
4321.q fake
4322MX records that are not published in DNS
4323for private internal networks.
4324.pp
4325As a final special case, the host name can be passed in
4326as a text string
4327in square brackets:
4328.(b
4329[ucbvax.berkeley.edu]
4330.)b
4331This form avoids the MX mapping.
4332.b N.B.:
4333.i
4334This is intended only for situations where you have a network firewall
4335or other host that will do special processing for all your mail,
4336so that your MX record points to a gateway machine;
4337this machine could then do direct delivery to machines
4338within your local domain.
4339Use of this feature directly violates RFC 1123 section 5.3.5:
4340it should not be used lightly.
4341.r
4342.sh 2 "D \*- Define Macro"
4343.pp
4344Macros are named with a single character
4345or with a word in {braces}.
4346The names ``x'' and ``{x}'' denote the same macro
4347for every single character ``x''.
4348Single character names may be selected from the entire ASCII set,
4349but user-defined macros
4350should be selected from the set of upper case letters only.
4351Lower case letters
4352and special symbols
4353are used internally.
4354Long names beginning with a lower case letter or a punctuation character
4355are reserved for use by sendmail,
4356so user-defined long macro names should begin with an upper case letter.
4357.pp
4358The syntax for macro definitions is:
4359.(b F
4360.b D \c
4361.i x\|val
4362.)b
4363where
4364.i x
4365is the name of the macro
4366(which may be a single character
4367or a word in braces)
4368and
4369.i val
4370is the value it should have.
4371There should be no spaces given
4372that do not actually belong in the macro value.
4373.pp
4374Macros are interpolated
4375using the construct
4376.b $ \c
4377.i x ,
4378where
4379.i x
4380is the name of the macro to be interpolated.
4381This interpolation is done when the configuration file is read,
4382except in
4383.b M
4384lines.
4385The special construct
4386.b $& \c
4387.i x
4388can be used in
4389.b R
4390lines to get deferred interpolation.
4391.pp
4392Conditionals can be specified using the syntax:
4393.(b
4394$?x text1 $| text2 $.
4395.)b
4396This interpolates
4397.i text1
4398if the macro
4399.b $x
4400is set and non-null,
4401and
4402.i text2
4403otherwise.
4404The
4405.q else
4406(\c
4407.b $| )
4408clause may be omitted.
4409.pp
4410The following macros are defined and/or used internally by
4411.i sendmail
4412for interpolation into argv's for mailers
4413or for other contexts.
4414The ones marked \(dg are information passed into sendmail\**,
4415.(f
4416\**As of version 8.6,
4417all of these macros have reasonable defaults.
4418Previous versions required that they be defined.
4419.)f
4420the ones marked \(dd are information passed both in and out of sendmail,
4421and the unmarked macros are passed out of sendmail
4422but are not otherwise used internally.
4423These macros are:
4424.nr ii 5n
4425.ip $a
4426The origination date in RFC 822 format.
4427This is extracted from the Date: line.
4428.ip $b
4429The current date in RFC 822 format.
4430.ip $c
4431The hop count.
4432This is a count of the number of Received: lines
4433plus the value of the
4434.b \-h
4435command line flag.
4436.ip $d
4437The current date in UNIX (ctime) format.
4438.ip $e\(dg
4439(Obsolete; use SmtpGreetingMessage option instead.)
4440The SMTP entry message.
4441This is printed out when SMTP starts up.
4442The first word must be the
4443.b $j
4444macro as specified by RFC 821.
4445Defaults to
4446.q "$j Sendmail $v ready at $b" .
4447Commonly redefined to include the configuration version number, e.g.,
4448.q "$j Sendmail $v/$Z ready at $b"
4449.ip $f
4450The envelope sender (from) address.
4451.ip $g
4452The sender address relative to the recipient.
4453For example, if
4454.b $f
4455is
4456.q foo ,
4457.b $g
4458will be
4459.q host!foo ,
4460.q foo@host.domain ,
4461or whatever is appropriate for the receiving mailer.
4462.ip $h
4463The recipient host.
4464This is set in ruleset 0 from the $@ field of a parsed address.
4465.ip $i
4466The queue id,
4467e.g.,
4468.q f344MXxp018717 .
4469.ip $j\(dd
4470The \*(lqofficial\*(rq domain name for this site.
4471This is fully qualified if the full qualification can be found.
4472It
4473.i must
4474be redefined to be the fully qualified domain name
4475if your system is not configured so that information can find
4476it automatically.
4477.ip $k
4478The UUCP node name (from the uname system call).
4479.ip $l\(dg
4480(Obsolete; use UnixFromLine option instead.)
4481The format of the UNIX from line.
4482Unless you have changed the UNIX mailbox format,
4483you should not change the default,
4484which is
4485.q "From $g $d" .
4486.ip $m
4487The domain part of the \fIgethostname\fP return value.
4488Under normal circumstances,
4489.b $j
4490is equivalent to
4491.b $w.$m .
4492.ip $n\(dg
4493The name of the daemon (for error messages).
4494Defaults to
4495.q MAILER-DAEMON .
4496.ip $o\(dg
4497(Obsolete: use OperatorChars option instead.)
4498The set of \*(lqoperators\*(rq in addresses.
4499A list of characters
4500which will be considered tokens
4501and which will separate tokens
4502when doing parsing.
4503For example, if
4504.q @
4505were in the
4506.b $o
4507macro, then the input
4508.q a@b
4509would be scanned as three tokens:
4510.q a,
4511.q @,
4512and
4513.q b.
4514Defaults to
4515.q ".:@[]" ,
4516which is the minimum set necessary to do RFC 822 parsing;
4517a richer set of operators is
4518.q ".:%@!/[]" ,
4519which adds support for UUCP, the %-hack, and X.400 addresses.
4520.ip $p
4521Sendmail's process id.
4522.ip $q\(dg
4523Default format of sender address.
4524The
4525.b $q
4526macro specifies how an address should appear in a message
4527when it is defaulted.
4528Defaults to
4529.q "<$g>" .
4530It is commonly redefined to be
4531.q "$?x$x <$g>$|$g$."
4532or
4533.q "$g$?x ($x)$." ,
4534corresponding to the following two formats:
4535.(b
4536Eric Allman <eric@CS.Berkeley.EDU>
4537eric@CS.Berkeley.EDU (Eric Allman)
4538.)b
4539.i Sendmail
4540properly quotes names that have special characters
4541if the first form is used.
4542.ip $r
4543Protocol used to receive the message.
4544Set from the
4545.b \-p
4546command line flag or by the SMTP server code.
4547.ip $s
4548Sender's host name.
4549Set from the
4550.b \-p
4551command line flag or by the SMTP server code.
4552.ip $t
4553A numeric representation of the current time.
4554.ip $u
4555The recipient user.
4556.ip $v
4557The version number of the
4558.i sendmail
4559binary.
4560.ip $w\(dd
4561The hostname of this site.
4562This is the root name of this host (but see below for caveats).
4563.ip $x
4564The full name of the sender.
4565.ip $z
4566The home directory of the recipient.
4567.ip $_
4568The validated sender address.
4569See also
4570.b ${client_resolve} .
4571.ip ${addr_type}
4572The type of the address which is currently being rewritten.
4573This macro contains up to three characters, the first
4574is either `e' or `h' for envelope/header address,
4575the second is a space,
4576and the third is either `s' or `r' for sender/recipient address.
4577Notice: for header addresses no distinction is currently made
4578between sender and recipient addresses, i.e., the macro contains
4579only `h'.
|
| 4580.ip ${alg_bits}
4581The maximum keylength (in bits) of the symmetric encryption algorithm
4582used for a TLS connection.
4583This may be less than the effective keylength,
4584which is stored in
4585.b ${cipher_bits} ,
4586for ``export controlled'' algorithms.
|
4580.ip ${auth_authen}
4581The client's authentication credentials as determined by authentication
4582(only set if successful).
4583The format depends on the mechanism used, it might be just `user',
4584or `user@realm', or something similar (SMTP AUTH only).
4585.ip ${auth_author}
4586The authorization identity, i.e. the AUTH= parameter of the
4587.sm "SMTP MAIL"
4588command if supplied.
4589.ip ${auth_type}
4590The mechanism used for SMTP authentication
4591(only set if successful).
4592.ip ${auth_ssf}
4593The keylength (in bits) of the symmetric encryption algorithm
4594used for the security layer of a SASL mechanism.
4595.ip ${bodytype}
4596The message body type
4597(7BIT or 8BITMIME),
4598as determined from the envelope.
4599.ip ${cert_issuer}
4600The DN (distinguished name) of the CA (certificate authority)
4601that signed the presented certificate (the cert issuer)
4602(STARTTLS only).
4603.ip ${cert_md5}
4604The MD5 hash of the presented certificate (STARTTLS only).
4605.ip ${cert_subject}
4606The DN of the presented certificate (called the cert subject)
4607(STARTTLS only).
4608.ip ${cipher}
4609The cipher suite used for the connection, e.g., EDH-DSS-DES-CBC3-SHA,
4610EDH-RSA-DES-CBC-SHA, DES-CBC-MD5, DES-CBC3-SHA
4611(STARTTLS only).
4612.ip ${cipher_bits}
| 4587.ip ${auth_authen}
4588The client's authentication credentials as determined by authentication
4589(only set if successful).
4590The format depends on the mechanism used, it might be just `user',
4591or `user@realm', or something similar (SMTP AUTH only).
4592.ip ${auth_author}
4593The authorization identity, i.e. the AUTH= parameter of the
4594.sm "SMTP MAIL"
4595command if supplied.
4596.ip ${auth_type}
4597The mechanism used for SMTP authentication
4598(only set if successful).
4599.ip ${auth_ssf}
4600The keylength (in bits) of the symmetric encryption algorithm
4601used for the security layer of a SASL mechanism.
4602.ip ${bodytype}
4603The message body type
4604(7BIT or 8BITMIME),
4605as determined from the envelope.
4606.ip ${cert_issuer}
4607The DN (distinguished name) of the CA (certificate authority)
4608that signed the presented certificate (the cert issuer)
4609(STARTTLS only).
4610.ip ${cert_md5}
4611The MD5 hash of the presented certificate (STARTTLS only).
4612.ip ${cert_subject}
4613The DN of the presented certificate (called the cert subject)
4614(STARTTLS only).
4615.ip ${cipher}
4616The cipher suite used for the connection, e.g., EDH-DSS-DES-CBC3-SHA,
4617EDH-RSA-DES-CBC-SHA, DES-CBC-MD5, DES-CBC3-SHA
4618(STARTTLS only).
4619.ip ${cipher_bits}
|
4613The keylength (in bits) of the symmetric encryption algorithm
| 4620The effective keylength (in bits) of the symmetric encryption algorithm
|
4614used for a TLS connection.
4615.ip ${client_addr}
4616The IP address of the SMTP client.
4617IPv6 addresses are tagged with "IPv6:" before the address.
4618Defined in the SMTP server only.
4619.ip ${client_name}
4620The host name of the SMTP client.
4621This may be the client's bracketed IP address
4622in the form [ nnn.nnn.nnn.nnn ] for IPv4
4623and [ IPv6:nnnn:...:nnnn ] for IPv6
4624if the client's
4625IP address is not resolvable, or if it is resolvable
4626but the IP address of the resolved hostname
4627doesn't match the original IP address.
4628Defined in the SMTP server only.
4629See also
4630.b ${client_resolve} .
4631.ip ${client_port}
4632The port number of the SMTP client.
4633Defined in the SMTP server only.
4634.ip ${client_resolve}
4635Holds the result of the resolve call for
4636.b ${client_name} .
4637Possible values are:
4638.(b
4639.ta 10n
4640OK resolved successfully
4641FAIL permanent lookup failure
4642FORGED forward lookup doesn't match reverse lookup
4643TEMP temporary lookup failure
4644.)b
4645Defined in the SMTP server only.
4646.i sendmail
4647performs a hostname lookup on the IP address of the connecting client.
4648Next the IP addresses of that hostname are looked up.
4649If the client IP address does not appear in that list,
4650then the hostname is maybe forged.
4651This is reflected as the value FORGED for
4652.b ${client_resolve}
4653and it also shows up in
4654.b $_
4655as "(may be forged)".
4656.ip ${cn_issuer}
4657The CN (common name) of the CA that signed the presented certificate
4658(STARTTLS only).
4659.ip ${cn_subject}
4660The CN (common name) of the presented certificate
4661(STARTTLS only).
4662.ip ${currHeader}
4663Header value as quoted string
4664(possibly truncated to
4665.b MAXNAME ).
4666This macro is only available in header check rulesets.
4667.ip ${daemon_addr}
4668The IP address the daemon is listening on for connections.
4669.ip ${daemon_family}
4670The network family
4671if the daemon is accepting network connections.
4672Possible values include
4673.q inet ,
4674.q inet6 ,
4675.q iso ,
4676.q ns ,
4677.q x.25
4678.ip ${daemon_flags}
4679The flags for the daemon as specified by the
4680Modifier= part of
4681.b DaemonPortOptions
4682whereby the flags are separated from each other by spaces,
4683and upper case flags are doubled.
4684That is,
4685Modifier=Ea
4686will be represented as
4687"EE a" in
4688.b ${daemon_flags} ,
4689which is required for testing the flags in rulesets.
4690.ip ${daemon_info}
4691Some information about a daemon as a text string.
4692For example,
4693.q SMTP+queueing@00:30:00 .
4694.ip ${daemon_name}
4695The name of the daemon from
4696.b DaemonPortOptions
4697Name= suboption.
4698If this suboption is not set,
4699"Daemon#",
4700where # is the daemon number,
4701is used.
4702.ip ${daemon_port}
4703The port the daemon is accepting connection on.
4704Unless
4705.b DaemonPortOptions
4706is set, this will most likely be
4707.q 25 .
4708.ip ${deliveryMode}
4709The current delivery mode sendmail is using.
4710It is initially set to the value of the
4711.b DeliveryMode
4712option.
4713.ip ${envid}
4714The envelope id parameter (ENVID=) passed to sendmail as part of the envelope.
4715.ip ${hdrlen}
4716The length of the header value which is stored in
4717${currHeader} (before possible truncation).
4718If this value is greater than or equal to
4719.b MAXNAME
4720the header has been truncated.
4721.ip ${hdr_name}
4722The name of the header field for which the current header
4723check ruleset has been called.
4724This is useful for a default header check ruleset to get
4725the name of the header;
4726the macro is only available in header check rulesets.
4727.ip ${if_addr}
4728The IP address of the interface of an incoming connection
4729unless it is in the loopback net.
4730IPv6 addresses are tagged with "IPv6:" before the address.
4731.ip ${if_addr_out}
4732The IP address of the interface of an outgoing connection
4733unless it is in the loopback net.
4734IPv6 addresses are tagged with "IPv6:" before the address.
4735.ip ${if_family}
4736The IP family of the interface of an incoming connection
4737unless it is in the loopback net.
4738.ip ${if_family_out}
4739The IP family of the interface of an outgoing connection
4740unless it is in the loopback net.
4741.ip ${if_name}
4742The hostname associated with the interface of an incoming connection.
4743This macro can be used for
4744SmtpGreetingMessage and HReceived for virtual hosting.
4745For example:
4746.(b
4747O SmtpGreetingMessage=$?{if_name}${if_name}$|$j$. MTA
4748.)b
4749.ip ${if_name_out}
4750The name of the interface of an outgoing connection.
4751.ip ${mail_addr}
4752The address part of the resolved triple of the address given for the
4753.sm "SMTP MAIL"
4754command.
4755Defined in the SMTP server only.
4756.ip ${mail_host}
4757The host from the resolved triple of the address given for the
4758.sm "SMTP MAIL"
4759command.
4760Defined in the SMTP server only.
4761.ip ${mail_mailer}
4762The mailer from the resolved triple of the address given for the
4763.sm "SMTP MAIL"
4764command.
4765Defined in the SMTP server only.
4766.ip ${msg_size}
4767The value of the SIZE= parameter,
4768i.e., usually the size of the message (in an ESMTP dialogue),
4769before the message has been collected, thereafter
4770the message size as computed by
4771.i sendmail
4772(and can be used in check_compat).
4773.ip ${nrcpts}
4774The number of validated recipients for a single message.
4775Note: since recipient validation happens after
4776.i check_rcpt
4777has been called, the value in this ruleset
4778is one less than what might be expected.
4779.ip ${ntries}
4780The number of delivery attempts.
4781.ip ${opMode}
4782The current operation mode (from the
4783.b \-b
4784flag).
4785.ip ${queue_interval}
4786The queue run interval given by the
4787.b \-q
4788flag.
4789For example,
4790.b \-q30m
4791would set
4792.b ${queue_interval}
4793to
4794.q 00:30:00 .
4795.ip ${rcpt_addr}
4796The address part of the resolved triple of the address given for the
4797.sm "SMTP RCPT"
4798command.
4799Defined in the SMTP server only after a RCPT command.
4800.ip ${rcpt_host}
4801The host from the resolved triple of the address given for the
4802.sm "SMTP RCPT"
4803command.
4804Defined in the SMTP server only after a RCPT command.
4805.ip ${rcpt_mailer}
4806The mailer from the resolved triple of the address given for the
4807.sm "SMTP RCPT"
4808command.
4809Defined in the SMTP server only after a RCPT command.
4810.ip ${server_addr}
4811The address of the server of the current outgoing SMTP connection.
4812For LMTP delivery the macro is set to the name of the mailer.
4813.ip ${server_name}
4814The name of the server of the current outgoing SMTP or LMTP connection.
4815.ip ${tls_version}
4816The TLS/SSL version used for the connection, e.g., TLSv1, SSLv3, SSLv2;
4817defined after STARTTLS has been used.
4818.ip ${verify}
4819The result of the verification of the presented cert;
4820only defined after STARTTLS has been used.
4821Possible values are:
4822.(b
4823.ta 13n
4824OK verification succeeded.
4825NO no cert presented.
4826NOT no cert requested.
4827FAIL cert presented but could not be verified,
4828 e.g., the signing CA is missing.
4829NONE STARTTLS has not been performed.
4830TEMP temporary error occurred.
4831PROTOCOL some protocol error occurred.
4832SOFTWARE STARTTLS handshake failed,
4833 which is a fatal error for this session,
4834 the e-mail will be queued.
4835.)b
4836.pp
4837There are three types of dates that can be used.
4838The
4839.b $a
4840and
4841.b $b
4842macros are in RFC 822 format;
4843.b $a
4844is the time as extracted from the
4845.q Date:
4846line of the message
4847(if there was one),
4848and
4849.b $b
4850is the current date and time
4851(used for postmarks).
4852If no
4853.q Date:
4854line is found in the incoming message,
4855.b $a
4856is set to the current time also.
4857The
4858.b $d
4859macro is equivalent to the
4860.b $b
4861macro in UNIX
4862(ctime)
4863format.
4864.pp
4865The macros
4866.b $w ,
4867.b $j ,
4868and
4869.b $m
4870are set to the identity of this host.
4871.i Sendmail
4872tries to find the fully qualified name of the host
4873if at all possible;
4874it does this by calling
4875.i gethostname (2)
4876to get the current hostname
4877and then passing that to
4878.i gethostbyname (3)
4879which is supposed to return the canonical version of that host name.\**
4880.(f
4881\**For example, on some systems
4882.i gethostname
4883might return
4884.q foo
4885which would be mapped to
4886.q foo.bar.com
4887by
4888.i gethostbyname .
4889.)f
4890Assuming this is successful,
4891.b $j
4892is set to the fully qualified name
4893and
4894.b $m
4895is set to the domain part of the name
4896(everything after the first dot).
4897The
4898.b $w
4899macro is set to the first word
4900(everything before the first dot)
4901if you have a level 5 or higher configuration file;
4902otherwise, it is set to the same value as
4903.b $j .
4904If the canonification is not successful,
4905it is imperative that the config file set
4906.b $j
4907to the fully qualified domain name\**.
4908.(f
4909\**Older versions of sendmail didn't pre-define
4910.b $j
4911at all, so up until 8.6,
4912config files
4913.i always
4914had to define
4915.b $j .
4916.)f
4917.pp
4918The
4919.b $f
4920macro is the id of the sender
4921as originally determined;
4922when mailing to a specific host
4923the
4924.b $g
4925macro is set to the address of the sender
4926.ul
4927relative to the recipient.
4928For example,
4929if I send to
4930.q bollard@matisse.CS.Berkeley.EDU
4931from the machine
4932.q vangogh.CS.Berkeley.EDU
4933the
4934.b $f
4935macro will be
4936.q eric
4937and the
4938.b $g
4939macro will be
4940.q eric@vangogh.CS.Berkeley.EDU.
4941.pp
4942The
4943.b $x
4944macro is set to the full name of the sender.
4945This can be determined in several ways.
4946It can be passed as flag to
4947.i sendmail .
4948It can be defined in the
4949.sm NAME
4950environment variable.
4951The third choice is the value of the
4952.q Full-Name:
4953line in the header if it exists,
4954and the fourth choice is the comment field
4955of a
4956.q From:
4957line.
4958If all of these fail,
4959and if the message is being originated locally,
4960the full name is looked up in the
4961.i /etc/passwd
4962file.
4963.pp
4964When sending,
4965the
4966.b $h ,
4967.b $u ,
4968and
4969.b $z
4970macros get set to the host, user, and home directory
4971(if local)
4972of the recipient.
4973The first two are set from the
4974.b $@
4975and
4976.b $:
4977part of the rewriting rules, respectively.
4978.pp
4979The
4980.b $p
4981and
4982.b $t
4983macros are used to create unique strings
4984(e.g., for the
4985.q Message-Id:
4986field).
4987The
4988.b $i
4989macro is set to the queue id on this host;
4990if put into the timestamp line
4991it can be extremely useful for tracking messages.
4992The
4993.b $v
4994macro is set to be the version number of
4995.i sendmail ;
4996this is normally put in timestamps
4997and has been proven extremely useful for debugging.
4998.pp
4999The
5000.b $c
5001field is set to the
5002.q "hop count,"
5003i.e., the number of times this message has been processed.
5004This can be determined
5005by the
5006.b \-h
5007flag on the command line
5008or by counting the timestamps in the message.
5009.pp
5010The
5011.b $r
5012and
5013.b $s
5014fields are set to the protocol used to communicate with
5015.i sendmail
5016and the sending hostname.
5017They can be set together using the
5018.b \-p
5019command line flag or separately using the
5020.b \-M
5021or
5022.b \-oM
5023flags.
5024.pp
5025The
5026.b $_
5027is set to a validated sender host name.
5028If the sender is running an RFC 1413 compliant IDENT server
5029and the receiver has the IDENT protocol turned on,
5030it will include the user name on that host.
5031.pp
5032The
5033.b ${client_name} ,
5034.b ${client_addr} ,
5035and
5036.b ${client_port}
5037macros
5038are set to the name, address, and port number of the SMTP client
5039who is invoking
5040.i sendmail
5041as a server.
5042These can be used in the
5043.i check_*
5044rulesets (using the
5045.b $&
5046deferred evaluation form, of course!).
5047.sh 2 "C and F \*- Define Classes"
5048.pp
5049Classes of phrases may be defined
5050to match on the left hand side of rewriting rules,
5051where a
5052.q phrase
5053is a sequence of characters that does not contain space characters.
5054For example
5055a class of all local names for this site
5056might be created
5057so that attempts to send to oneself
5058can be eliminated.
5059These can either be defined directly in the configuration file
5060or read in from another file.
5061Classes are named as a single letter or a word in {braces}.
5062Class names beginning with lower case letters
5063and special characters are reserved for system use.
5064Classes defined in config files may be given names
5065from the set of upper case letters for short names
5066or beginning with an upper case letter for long names.
5067.pp
5068The syntax is:
5069.(b F
5070.b C \c
5071.i c\|phrase1
5072.i phrase2...
5073.br
5074.b F \c
5075.i c\|file
5076.br
5077.b F \c
5078.i c\||program
5079.br
5080.b F \c
5081.i c\|[mapkey]@mapclass:mapspec
5082.)b
5083The first form defines the class
5084.i c
5085to match any of the named words.
5086If
5087.i phrase1
5088or
5089.i phrase2
5090is another class,
5091e.g.,
5092.i $=S ,
5093the contents of class
5094.i S
5095are added to class
5096.i c .
5097It is permissible to split them among multiple lines;
5098for example, the two forms:
5099.(b
5100CHmonet ucbmonet
5101.)b
5102and
5103.(b
5104CHmonet
5105CHucbmonet
5106.)b
5107are equivalent.
5108The ``F'' forms
5109read the elements of the class
5110.i c
5111from the named
5112.i file ,
5113.i program ,
5114or
5115.i "map specification" .
5116Each element should be listed on a separate line.
5117To specify an optional file, use ``\-o'' between the class
5118name and the file name, e.g.,
5119.(b
5120Fc \-o /path/to/file
5121.)b
5122If the file can't be used,
5123.i sendmail
5124will not complain but silently ignore it.
5125The map form should be an optional map key, an at sign,
5126and a map class followed by the specification for that map.
5127Examples include:
5128.(b
5129F{VirtHosts}@ldap:\-k (&(objectClass=virtHosts)(host=*)) \-v host
5130F{MyClass}foo@hash:/etc/mail/classes
5131.)b
5132will fill the class
5133.b $={VirtHosts}
5134from an LDAP map lookup and
5135.b $={MyClass}
5136from a hash database map lookup of the
5137.b foo .
5138There is also a built-in schema that can be accessed by only specifying:
5139.(b
5140F{\c
5141.i ClassName }@LDAP
5142.)b
5143This will tell sendmail to use the default schema:
5144.(b
5145\-k (&(objectClass=sendmailMTAClass)
5146 (sendmailMTAClassName=\c
5147.i ClassName )
5148 (|(sendmailMTACluster=${sendmailMTACluster})
5149 (sendmailMTAHost=$j)))
5150\-v sendmailMTAClassValue
5151.)b
5152Note that the lookup is only done when sendmail is initially started.
5153.pp
5154Elements of classes can be accessed in rules using
5155.b $=
5156or
5157.b $~ .
5158The
5159.b $~
5160(match entries not in class)
5161only matches a single word;
5162multi-word entries in the class are ignored in this context.
5163.pp
5164Some classes have internal meaning to
5165.i sendmail :
5166.nr ii 0.5i
5167.\".ip $=b
5168.\"A set of Content-Types that will not have the newline character
5169.\"translated to CR-LF before encoding into base64 MIME.
5170.\"The class can have major times
5171.\"(e.g.,
5172.\".q image )
5173.\"or full types
5174.\"(such as
5175.\".q application/octet-stream ).
5176.\"The class is initialized with
5177.\".q application/octet-stream ,
5178.\".q image ,
5179.\".q audio ,
5180.\"and
5181.\".q video .
5182.ip $=e
5183contains the Content-Transfer-Encodings that can be 8\(->7 bit encoded.
5184It is predefined to contain
5185.q 7bit ,
5186.q 8bit ,
5187and
5188.q binary .
5189.ip $=k
5190set to be the same as
5191.b $k ,
5192that is, the UUCP node name.
5193.ip $=m
5194set to the set of domains by which this host is known,
5195initially just
5196.b $m .
5197.ip $=n
5198can be set to the set of MIME body types
5199that can never be eight to seven bit encoded.
5200It defaults to
5201.q multipart/signed .
5202Message types
5203.q message/*
5204and
5205.q multipart/*
5206are never encoded directly.
5207Multipart messages are always handled recursively.
5208The handling of message/* messages
5209are controlled by class
5210.b $=s .
5211.ip $=q
5212A set of Content-Types that will never be encoded as base64
5213(if they have to be encoded, they will be encoded as quoted-printable).
5214It can have primary types
5215(e.g.,
5216.q text )
5217or full types
5218(such as
5219.q text/plain ).
5220The class is initialized to have
5221.q text/plain
5222only.
5223.ip $=s
5224contains the set of subtypes of message that can be treated recursively.
5225By default it contains only
5226.q rfc822 .
5227Other
5228.q message/*
5229types cannot be 8\(->7 bit encoded.
5230If a message containing eight bit data is sent to a seven bit host,
5231and that message cannot be encoded into seven bits,
5232it will be stripped to 7 bits.
5233.ip $=t
5234set to the set of trusted users by the
5235.b T
5236configuration line.
5237If you want to read trusted users from a file, use
5238.b Ft \c
5239.i /file/name .
5240.ip $=w
5241set to be the set of all names
5242this host is known by.
5243This can be used to match local hostnames.
5244.ip $={persistentMacros}
5245set to the macros would should be saved across queue runs.
5246Care should be taken when adding macro names to this class.
5247.pp
5248.i Sendmail
5249can be compiled to allow a
5250.i scanf (3)
5251string on the
5252.b F
5253line.
5254This lets you do simplistic parsing of text files.
5255For example, to read all the user names in your system
5256.i /etc/passwd
5257file into a class, use
5258.(b
5259FL/etc/passwd %[^:]
5260.)b
5261which reads every line up to the first colon.
5262.sh 2 "M \*- Define Mailer"
5263.pp
5264Programs and interfaces to mailers
5265are defined in this line.
5266The format is:
5267.(b F
5268.b M \c
5269.i name ,
5270{\c
5271.i field =\c
5272.i value \|}*
5273.)b
5274where
5275.i name
5276is the name of the mailer
5277(used internally only)
5278and the
5279.q field=name
5280pairs define attributes of the mailer.
5281Fields are:
5282.(b
5283.ta 1i
5284Path The pathname of the mailer
5285Flags Special flags for this mailer
5286Sender Rewriting set(s) for sender addresses
5287Recipient Rewriting set(s) for recipient addresses
5288recipients Maximum number of recipients per connection
5289Argv An argument vector to pass to this mailer
5290Eol The end-of-line string for this mailer
5291Maxsize The maximum message length to this mailer
5292maxmessages The maximum message deliveries per connection
5293Linelimit The maximum line length in the message body
5294Directory The working directory for the mailer
5295Userid The default user and group id to run as
5296Nice The nice(2) increment for the mailer
5297Charset The default character set for 8-bit characters
5298Type Type information for DSN diagnostics
5299Wait The maximum time to wait for the mailer
5300Queuegroup The default queue group for the mailer
5301/ The root directory for the mailer
5302.)b
5303Only the first character of the field name is checked
5304(it's case-sensitive).
5305.pp
5306The following flags may be set in the mailer description.
5307Any other flags may be used freely
5308to conditionally assign headers to messages
5309destined for particular mailers.
5310Flags marked with \(dg
5311are not interpreted by the
5312.i sendmail
5313binary;
5314these are the conventionally used to correlate to the flags portion
5315of the
5316.b H
5317line.
5318Flags marked with \(dd
5319apply to the mailers for the sender address
5320rather than the usual recipient mailers.
5321.nr ii 4n
5322.ip a
5323Run Extended SMTP (ESMTP) protocol (defined in RFCs 1869, 1652, and 1870).
5324This flag defaults on if the SMTP greeting message includes the word
5325.q ESMTP .
5326.ip A
5327Look up the user part of the address in the alias database.
5328Normally this is only set for local mailers.
5329.ip b
5330Force a blank line on the end of a message.
5331This is intended to work around some stupid versions of
5332/bin/mail
5333that require a blank line, but do not provide it themselves.
5334It would not normally be used on network mail.
5335.ip c
5336Do not include comments in addresses.
5337This should only be used if you have to work around
5338a remote mailer that gets confused by comments.
5339This strips addresses of the form
5340.q "Phrase <address>"
5341or
5342.q "address (Comment)"
5343down to just
5344.q address .
5345.ip C\(dd
5346If mail is
5347.i received
5348from a mailer with this flag set,
5349any addresses in the header that do not have an at sign
5350(\c
5351.q @ )
5352after being rewritten by ruleset three
5353will have the
5354.q @domain
5355clause from the sender envelope address
5356tacked on.
5357This allows mail with headers of the form:
5358.(b
5359From: usera@hosta
5360To: userb@hostb, userc
5361.)b
5362to be rewritten as:
5363.(b
5364From: usera@hosta
5365To: userb@hostb, userc@hosta
5366.)b
5367automatically.
5368However, it doesn't really work reliably.
5369.ip d
5370Do not include angle brackets around route-address syntax addresses.
5371This is useful on mailers that are going to pass addresses to a shell
5372that might interpret angle brackets as I/O redirection.
5373However, it does not protect against other shell metacharacters.
5374Therefore, passing addresses to a shell should not be considered secure.
5375.ip D\(dg
5376This mailer wants a
5377.q Date:
5378header line.
5379.ip e
5380This mailer is expensive to connect to,
5381so try to avoid connecting normally;
5382any necessary connection will occur during a queue run.
5383See also option
5384.b HoldExpensive .
5385.ip E
5386Escape lines beginning with
5387.q From\0
5388in the message with a `>' sign.
5389.ip f
5390The mailer wants a
5391.b \-f
5392.i from
5393flag,
5394but only if this is a network forward operation
5395(i.e.,
5396the mailer will give an error
5397if the executing user
5398does not have special permissions).
5399.ip F\(dg
5400This mailer wants a
5401.q From:
5402header line.
5403.ip g
5404Normally,
5405.i sendmail
5406sends internally generated email (e.g., error messages)
5407using the null return address
5408as required by RFC 1123.
5409However, some mailers don't accept a null return address.
5410If necessary,
5411you can set the
5412.b g
5413flag to prevent
5414.i sendmail
5415from obeying the standards;
5416error messages will be sent as from the MAILER-DAEMON
5417(actually, the value of the
5418.b $n
5419macro).
5420.ip h
5421Upper case should be preserved in host names
5422(the $@ portion of the mailer triplet resolved from ruleset 0)
5423for this mailer.
5424.ip i
5425Do User Database rewriting on envelope sender address.
5426.ip I
5427This mailer will be speaking SMTP
5428to another
5429.i sendmail
5430\*-
5431as such it can use special protocol features.
5432This flag should not be used except for debugging purposes
5433because it uses
5434.b VERB
5435as SMTP command.
5436.ip j
5437Do User Database rewriting on recipients as well as senders.
5438.ip k
5439Normally when
5440.i sendmail
5441connects to a host via SMTP,
5442it checks to make sure that this isn't accidently the same host name
5443as might happen if
5444.i sendmail
5445is misconfigured or if a long-haul network interface is set in loopback mode.
5446This flag disables the loopback check.
5447It should only be used under very unusual circumstances.
5448.ip K
5449Currently unimplemented.
5450Reserved for chunking.
5451.ip l
5452This mailer is local
5453(i.e.,
5454final delivery will be performed).
5455.ip L
5456Limit the line lengths as specified in RFC 821.
5457This deprecated option should be replaced by the
5458.b L=
5459mail declaration.
5460For historic reasons, the
5461.b L
5462flag also sets the
5463.b 7
5464flag.
5465.ip m
5466This mailer can send to multiple users
5467on the same host
5468in one transaction.
5469When a
5470.b $u
5471macro occurs in the
5472.i argv
5473part of the mailer definition,
5474that field will be repeated as necessary
5475for all qualifying users.
5476Removing this flag can defeat duplicate supression on a remote site
5477as each recipient is sent in a separate transaction.
5478.ip M\(dg
5479This mailer wants a
5480.q Message-Id:
5481header line.
5482.ip n
5483Do not insert a UNIX-style
5484.q From
5485line on the front of the message.
5486.ip o
5487Always run as the owner of the recipient mailbox.
5488Normally
5489.i sendmail
5490runs as the sender for locally generated mail
5491or as
5492.q daemon
5493(actually, the user specified in the
5494.b u
5495option)
5496when delivering network mail.
5497The normal behavior is required by most local mailers,
5498which will not allow the envelope sender address
5499to be set unless the mailer is running as daemon.
5500This flag is ignored if the
5501.b S
5502flag is set.
5503.ip p
5504Use the route-addr style reverse-path in the SMTP
5505.q "MAIL FROM:"
5506command
5507rather than just the return address;
5508although this is required in RFC 821 section 3.1,
5509many hosts do not process reverse-paths properly.
5510Reverse-paths are officially discouraged by RFC 1123.
5511.ip P\(dg
5512This mailer wants a
5513.q Return-Path:
5514line.
5515.ip q
5516When an address that resolves to this mailer is verified
5517(SMTP VRFY command),
5518generate 250 responses instead of 252 responses.
5519This will imply that the address is local.
5520.ip r
5521Same as
5522.b f ,
5523but sends a
5524.b \-r
5525flag.
5526.ip R
5527Open SMTP connections from a
5528.q secure
5529port.
5530Secure ports aren't
5531(secure, that is)
5532except on UNIX machines,
5533so it is unclear that this adds anything.
5534.i sendmail
5535must be running as root to be able to use this flag.
5536.ip s
5537Strip quote characters (" and \e) off of the address
5538before calling the mailer.
5539.ip S
5540Don't reset the userid
5541before calling the mailer.
5542This would be used in a secure environment
5543where
5544.i sendmail
5545ran as root.
5546This could be used to avoid forged addresses.
5547If the
5548.b U=
5549field is also specified,
5550this flag causes the effective user id to be set to that user.
5551.ip u
5552Upper case should be preserved in user names for this mailer. Standards
5553require preservation of case in the local part of addresses, except for
5554those address for which your system accepts responsibility.
5555RFC 2142 provides a long list of addresses which should be case
5556insensitive.
5557If you use this flag, you may be violating RFC 2142.
5558Note that postmaster is always treated as a case insensitive address
5559regardless of this flag.
5560.ip U
5561This mailer wants UUCP-style
5562.q From
5563lines with the ugly
5564.q "remote from <host>"
5565on the end.
5566.ip w
5567The user must have a valid account on this machine,
5568i.e.,
5569.i getpwnam
5570must succeed.
5571If not, the mail is bounced.
5572See also the
5573.b MailBoxDatabase
5574option.
5575This is required to get
5576.q \&.forward
5577capability.
5578.ip x\(dg
5579This mailer wants a
5580.q Full-Name:
5581header line.
5582.ip X
5583This mailer wants to use the hidden dot algorithm as specified in RFC 821;
5584basically, any line beginning with a dot will have an extra dot prepended
5585(to be stripped at the other end).
5586This insures that lines in the message containing a dot
5587will not terminate the message prematurely.
5588.ip z
5589Run Local Mail Transfer Protocol (LMTP)
5590between
5591.i sendmail
5592and the local mailer.
5593This is a variant on SMTP
5594defined in RFC 2033
5595that is specifically designed for delivery to a local mailbox.
5596.ip Z
5597Apply DialDelay (if set) to this mailer.
5598.ip 0
5599Don't look up MX records for hosts sent via SMTP/LMTP.
5600Do not apply
5601.b FallbackMXhost
5602either.
5603.ip 1
5604Don't send null characters ('\\0') to this mailer.
5605.ip 2
5606Don't use ESMTP even if offered; this is useful for broken
5607systems that offer ESMTP but fail on EHLO (without recovering
5608when HELO is tried next).
5609.ip 3
5610Extend the list of characters converted to =XX notation
5611when converting to Quoted-Printable
5612to include those that don't map cleanly between ASCII and EBCDIC.
5613Useful if you have IBM mainframes on site.
5614.ip 5
5615If no aliases are found for this address,
5616pass the address through ruleset 5 for possible alternate resolution.
5617This is intended to forward the mail to an alternate delivery spot.
5618.ip 6
5619Strip headers to seven bits.
5620.ip 7
5621Strip all output to seven bits.
5622This is the default if the
5623.b L
5624flag is set.
5625Note that clearing this option is not
5626sufficient to get full eight bit data passed through
5627.i sendmail .
5628If the
5629.b 7
5630option is set, this is essentially always set,
5631since the eighth bit was stripped on input.
5632Note that this option will only impact messages
5633that didn't have 8\(->7 bit MIME conversions performed.
5634.ip 8
5635If set,
5636it is acceptable to send eight bit data to this mailer;
5637the usual attempt to do 8\(->7 bit MIME conversions will be bypassed.
5638.ip 9
5639If set,
5640do
5641.i limited
56427\(->8 bit MIME conversions.
5643These conversions are limited to text/plain data.
5644.ip :
5645Check addresses to see if they begin
5646.q :include: ;
5647if they do, convert them to the
5648.q *include*
5649mailer.
5650.ip |
5651Check addresses to see if they begin with a `|';
5652if they do, convert them to the
5653.q prog
5654mailer.
5655.ip /
5656Check addresses to see if they begin with a `/';
5657if they do, convert them to the
5658.q *file*
5659mailer.
5660.ip @
5661Look up addresses in the user database.
5662.ip %
5663Do not attempt delivery on initial recipient of a message
5664or on queue runs
5665unless the queued message is selected
5666using one of the -qI/-qR/-qS queue run modifiers
5667or an ETRN request.
5668.pp
5669Configuration files prior to level 6
5670assume the `A', `w', `5', `:', `|', `/', and `@' options
5671on the mailer named
5672.q local .
5673.pp
5674The mailer with the special name
5675.q error
5676can be used to generate a user error.
5677The (optional) host field is an exit status to be returned,
5678and the user field is a message to be printed.
5679The exit status may be numeric or one of the values
5680USAGE, NOUSER, NOHOST, UNAVAILABLE, SOFTWARE, TEMPFAIL, PROTOCOL, or CONFIG
5681to return the corresponding EX_ exit code,
5682or an enhanced error code as described in RFC 1893,
5683.ul
5684Enhanced Mail System Status Codes.
5685For example, the entry:
5686.(b
5687$#error $@ NOHOST $: Host unknown in this domain
5688.)b
5689on the RHS of a rule
5690will cause the specified error to be generated
5691and the
5692.q "Host unknown"
5693exit status to be returned
5694if the LHS matches.
5695This mailer is only functional in rulesets 0, 5,
5696or one of the check_* rulesets.
5697.pp
5698The mailer with the special name
5699.q discard
5700causes any mail sent to it to be discarded
5701but otherwise treated as though it were successfully delivered.
5702This mailer cannot be used in ruleset 0,
5703only in the various address checking rulesets.
5704.pp
5705The mailer named
5706.q local
5707.i must
5708be defined in every configuration file.
5709This is used to deliver local mail,
5710and is treated specially in several ways.
5711Additionally, three other mailers named
5712.q prog ,
5713.q *file* ,
5714and
5715.q *include*
5716may be defined to tune the delivery of messages to programs,
5717files,
5718and :include: lists respectively.
5719They default to:
5720.(b
5721Mprog, P=/bin/sh, F=lsoDq9, T=DNS/RFC822/X-Unix, A=sh \-c $u
5722M*file*, P=[FILE], F=lsDFMPEouq9, T=DNS/RFC822/X-Unix, A=FILE $u
5723M*include*, P=/dev/null, F=su, A=INCLUDE $u
5724.)b
5725.pp
5726Builtin pathnames are [FILE] and [IPC], the former is used for
5727delivery to files, the latter for delivery via interprocess communication.
5728For mailers that use [IPC] as pathname the argument vector (A=)
5729must start with TCP or FILE for delivery via a TCP or a Unix domain socket.
5730If TCP is used, the second argument must be the name of the host
5731to contact.
5732Optionally a third argument can be used to specify a port,
5733the default is smtp (port 25).
5734If FILE is used, the second argument must be the name of
5735the Unix domain socket.
5736.pp
5737If the argument vector does not contain $u then
5738.i sendmail
5739will speak SMTP (or LMTP if the mailer flag z is specified) to the mailer.
5740.pp
5741If no Eol field is defined, then the default is "\\r\\n" for
5742SMTP mailers and "\\n" of others.
5743.pp
5744The Sender and Recipient rewriting sets
5745may either be a simple ruleset id
5746or may be two ids separated by a slash;
5747if so, the first rewriting set is applied to envelope
5748addresses
5749and the second is applied to headers.
5750Setting any value to zero disables corresponding mailer-specific rewriting.
5751.pp
5752The Directory
5753is actually a colon-separated path of directories to try.
5754For example, the definition
5755.q D=$z:/
5756first tries to execute in the recipient's home directory;
5757if that is not available,
5758it tries to execute in the root of the filesystem.
5759This is intended to be used only on the
5760.q prog
5761mailer,
5762since some shells (such as
5763.i csh )
5764refuse to execute if they cannot read the current directory.
5765Since the queue directory is not normally readable by unprivileged users
5766.i csh
5767scripts as recipients can fail.
5768.pp
5769The Userid
5770specifies the default user and group id to run as,
5771overriding the
5772.b DefaultUser
5773option (q.v.).
5774If the
5775.b S
5776mailer flag is also specified,
5777this user and group will be set as the
5778effective uid and gid for the process.
5779This may be given as
5780.i user:group
5781to set both the user and group id;
5782either may be an integer or a symbolic name to be looked up
5783in the
5784.i passwd
5785and
5786.i group
5787files respectively.
5788If only a symbolic user name is specified,
5789the group id in the
5790.i passwd
5791file for that user is used as the group id.
5792.pp
5793The Charset field
5794is used when converting a message to MIME;
5795this is the character set used in the
5796Content-Type: header.
5797If this is not set, the
5798.b DefaultCharset
5799option is used,
5800and if that is not set, the value
5801.q unknown-8bit
5802is used.
5803.b WARNING:
5804this field applies to the sender's mailer,
5805not the recipient's mailer.
5806For example, if the envelope sender address
5807lists an address on the local network
5808and the recipient is on an external network,
5809the character set will be set from the Charset= field
5810for the local network mailer,
5811not that of the external network mailer.
5812.pp
5813The Type= field
5814sets the type information
5815used in MIME error messages
5816as defined by
5817RFC 1894.
5818It is actually three values separated by slashes:
5819the MTA-type (that is, the description of how hosts are named),
5820the address type (the description of e-mail addresses),
5821and the diagnostic type (the description of error diagnostic codes).
5822Each of these must be a registered value
5823or begin with
5824.q X\- .
5825The default is
5826.q dns/rfc822/smtp .
5827.pp
5828The m= field specifies the maximum number of messages
5829to attempt to deliver on a single SMTP or LMTP connection.
5830The default is infinite.
5831.pp
5832The r= field specifies the maximum number of recipients
5833to attempt to deliver in a single envelope.
5834It defaults to 100.
5835.pp
5836The /= field specifies a new root directory for the mailer. The path is
5837macro expanded and then passed to the
5838.q chroot
5839system call. The root directory is changed before the Directory field is
5840consulted or the uid is changed.
5841.pp
5842The Wait= field specifies the maximum time to wait for the
5843mailer to return after sending all data to it.
5844This applies to mailers that have been forked by
5845.i sendmail .
5846.pp
5847The Queuegroup= field specifies the default queue group in which
5848received mail should be queued.
5849This can be overridden by other means as explained in section
5850``Queue Groups and Queue Directories''.
5851.sh 2 "H \*- Define Header"
5852.pp
5853The format of the header lines that
5854.i sendmail
5855inserts into the message
5856are defined by the
5857.b H
5858line.
5859The syntax of this line is one of the following:
5860.(b F
5861.b H \c
5862.i hname \c
5863.b :
5864.i htemplate
5865.)b
5866.(b F
5867.b H [\c
5868.b ? \c
5869.i mflags \c
5870.b ? \c
5871.b ]\c
5872.i hname \c
5873.b :
5874.i htemplate
5875.)b
5876.(b F
5877.b H [\c
5878.b ?$ \c
5879.i {macro} \c
5880.b ? \c
5881.b ]\c
5882.i hname \c
5883.b :
5884.i htemplate
5885.)b
5886Continuation lines in this spec
5887are reflected directly into the outgoing message.
5888The
5889.i htemplate
5890is macro-expanded before insertion into the message.
5891If the
5892.i mflags
5893(surrounded by question marks)
5894are specified,
5895at least one of the specified flags
5896must be stated in the mailer definition
5897for this header to be automatically output.
5898If a
5899.i ${macro}
5900(surrounded by question marks)
5901is specified,
5902the header will be automatically output
5903if the macro is set.
5904The macro may be set using any of the normal methods,
5905including using the
5906.b macro
5907storage map in a ruleset.
5908If one of these headers is in the input
5909it is reflected to the output
5910regardless of these flags or macros.
5911Notice:
5912If a
5913.i ${macro}
5914is used to set a header, then it is useful to add that macro to class
5915.i $={persistentMacros}
5916which consists of the macros that should be saved across queue runs.
5917.pp
5918Some headers have special semantics
5919that will be described later.
5920.pp
5921A secondary syntax allows validation of headers as they are being read.
5922To enable validation, use:
5923.(b
5924.b H \c
5925.i Header \c
5926.b ": $>" \c
5927.i Ruleset
5928.b H \c
5929.i Header \c
5930.b ": $>+" \c
5931.i Ruleset
5932.)b
5933The indicated
5934.i Ruleset
5935is called for the specified
5936.i Header ,
5937and can return
5938.b $#error
5939to reject the message or
5940.b $#discard
5941to discard the message
5942(as with the other
5943.b check_ *
5944rulesets).
5945The ruleset receives the header field-body as argument,
5946i.e., not the header field-name; see also
5947${hdr_name} and ${currHeader}.
5948The header is treated as a structured field,
5949that is,
5950text in parentheses is deleted before processing,
5951unless the second form
5952.b $>+
5953is used.
5954Note: only one ruleset can be associated with a header;
5955.i sendmail
5956will silently ignore multiple entries.
5957.pp
5958For example, the configuration lines:
5959.(b
5960HMessage-Id: $>CheckMessageId
5961
5962SCheckMessageId
5963R< $+ @ $+ > $@ OK
5964R$* $#error $: Illegal Message-Id header
5965.)b
5966would refuse any message that had a Message-Id: header of any of the
5967following forms:
5968.(b
5969Message-Id: <>
5970Message-Id: some text
5971Message-Id: <legal text@domain> extra crud
5972.)b
5973A default ruleset that is called for headers which don't have a
5974specific ruleset defined for them can be specified by:
5975.(b
5976.b H \c
5977.i * \c
5978.b ": $>" \c
5979.i Ruleset
5980.)b
5981or
5982.(b
5983.b H \c
5984.i * \c
5985.b ": $>+" \c
5986.i Ruleset
5987.)b
5988.sh 2 "O \*- Set Option"
5989.pp
5990There are a number of global options that
5991can be set from a configuration file.
5992Options are represented by full words;
5993some are also representable as single characters for back compatibility.
5994The syntax of this line is:
5995.(b F
5996.b O \0
5997.i option \c
5998.b = \c
5999.i value
6000.)b
6001This sets option
6002.i option
6003to be
6004.i value .
6005Note that there
6006.i must
6007be a space between the letter `O' and the name of the option.
6008An older version is:
6009.(b F
6010.b O \c
6011.i o\|value
6012.)b
6013where the option
6014.i o
6015is a single character.
6016Depending on the option,
6017.i value
6018may be a string, an integer,
6019a boolean
6020(with legal values
6021.q t ,
6022.q T ,
6023.q f ,
6024or
6025.q F ;
6026the default is TRUE),
6027or
6028a time interval.
6029.pp
6030All filenames used in options should be absolute paths,
6031i.e., starting with '/'.
6032Relative filenames most likely cause surprises during operation
6033(unless otherwise noted).
6034.pp
6035The options supported (with the old, one character names in brackets) are:
6036.nr ii 1i
6037.ip "AliasFile=\fIspec, spec, ...\fP"
6038[A]
6039Specify possible alias file(s).
6040Each
6041.i spec
6042should be in the format
6043``\c
6044.i class \c
6045.b :
6046.i info ''
6047where
6048.i class \c
6049.b :
6050is optional and defaults to ``implicit''.
6051Note that
6052.i info
6053is required for all
6054.i class es
6055except
6056.q ldap .
6057For the
6058.q ldap
6059class,
6060if
6061.i info
6062is not specified,
6063a default
6064.i info
6065value is used as follows:
6066.(b
6067\-k (&(objectClass=sendmailMTAAliasObject)
6068 (sendmailMTAAliasName=aliases)
6069 (|(sendmailMTACluster=${sendmailMTACluster})
6070 (sendmailMTAHost=$j))
6071 (sendmailMTAKey=%0))
6072\-v sendmailMTAAliasValue
6073.)b
6074Depending on how
6075.i sendmail
6076is compiled, valid classes are
6077.q implicit
6078(search through a compiled-in list of alias file types,
6079for back compatibility),
6080.q hash
6081(if
6082.sm NEWDB
6083is specified),
6084.q btree
6085(if
6086.sm NEWDB
6087is specified),
6088.q dbm
6089(if
6090.sm NDBM
6091is specified),
6092.q stab
6093(internal symbol table \*- not normally used
6094unless you have no other database lookup),
6095.q sequence
6096(use a sequence of maps
6097previously declared),
6098.q ldap
6099(if
6100.sm LDAPMAP
6101is specified),
6102or
6103.q nis
6104(if
6105.sm NIS
6106is specified).
6107If a list of
6108.i spec s
6109are provided,
6110.i sendmail
6111searches them in order.
6112.ip AliasWait=\fItimeout\fP
6113[a]
6114If set,
6115wait up to
6116.i timeout
6117(units default to minutes)
6118for an
6119.q @:@
6120entry to exist in the alias database
6121before starting up.
6122If it does not appear in the
6123.i timeout
6124interval issue a warning.
6125.ip AllowBogusHELO
6126[no short name]
6127If set, allow HELO SMTP commands that don't include a host name.
6128Setting this violates RFC 1123 section 5.2.5,
6129but is necessary to interoperate with several SMTP clients.
6130If there is a value, it is still checked for legitimacy.
6131.ip AuthMaxBits=\fIN\fP
6132[no short name]
6133Limit the maximum encryption strength for the security layer in
6134SMTP AUTH (SASL). Default is essentially unlimited.
6135This allows to turn off additional encryption in SASL if
6136STARTTLS is already encrypting the communication, because the
6137existing encryption strength is taken into account when choosing
6138an algorithm for the security layer.
6139For example, if STARTTLS is used and the symmetric cipher is 3DES,
6140then the the keylength (in bits) is 168.
6141Hence setting
6142.b AuthMaxBits
6143to 168 will disable any encryption in SASL.
6144.ip AuthMechanisms
6145[no short name]
6146List of authentication mechanisms for AUTH (separated by spaces).
6147The advertised list of authentication mechanisms will be the
6148intersection of this list and the list of available mechanisms as
6149determined by the Cyrus SASL library.
6150If STARTTLS is active, EXTERNAL will be added to this list.
6151In that case, the value of {cert_subject} is used as authentication id.
6152.ip AuthOptions
6153[no short name]
6154List of options for SMTP AUTH consisting of single characters
6155with intervening white space or commas.
6156.(b
6157.ta 4n
6158A Use the AUTH= parameter for the MAIL FROM
6159 command only when authentication succeeded.
6160 This can be used as a workaround for broken
6161 MTAs that do not implement RFC 2554 correctly.
6162a protection from active (non-dictionary) attacks
6163 during authentication exchange.
6164c require mechanisms which pass client credentials,
6165 and allow mechanisms which can pass credentials
6166 to do so.
6167d don't permit mechanisms susceptible to passive
6168 dictionary attack.
6169f require forward secrecy between sessions
6170 (breaking one won't help break next).
6171p don't permit mechanisms susceptible to simple
6172 passive attack (e.g., PLAIN, LOGIN).
6173y don't permit mechanisms that allow anonymous login.
6174.)b
6175The first option applies to sendmail as a client, the others to a server.
6176Example:
6177.(b
6178O AuthOptions=p,y
6179.)b
6180would disallow ANONYMOUS as AUTH mechanism and would
6181allow PLAIN only if a security layer (e.g.,
6182provided by STARTTLS) is already active.
6183The options 'a', 'c', 'd', 'f', 'p', and 'y' refer to properties of the
6184selected SASL mechanisms.
6185Explanations of these properties can be found in the Cyrus SASL documentation.
6186.ip BadRcptThrottle=\fIN\fP
6187[no short name]
6188If set and more than the specified number of recipients in a single SMTP
6189envelope are rejected, sleep for one second after each rejected RCPT command.
6190.ip BlankSub=\fIc\fP
6191[B]
6192Set the blank substitution character to
6193.i c .
6194Unquoted spaces in addresses are replaced by this character.
6195Defaults to space (i.e., no change is made).
6196.ip CACERTPath
6197[no short name]
6198Path to directory with certificates of CAs.
6199This directory directory must contain the hashes of each CA certificate
6200as filenames (or as links to them).
6201.ip CACERTFile
6202[no short name]
6203File containing one or more CA certificates;
6204see section about STARTTLS for more information.
6205.ip CheckAliases
6206[n]
6207Validate the RHS of aliases when rebuilding the alias database.
6208.ip CheckpointInterval=\fIN\fP
6209[C]
6210Checkpoints the queue every
6211.i N
6212(default 10)
6213addresses sent.
6214If your system crashes during delivery to a large list,
6215this prevents retransmission to any but the last
6216.i N
6217recipients.
6218.ip ClassFactor=\fIfact\fP
6219[z]
6220The indicated
6221.i fact or
6222is multiplied by the message class
6223(determined by the Precedence: field in the user header
6224and the
6225.b P
6226lines in the configuration file)
6227and subtracted from the priority.
6228Thus, messages with a higher Priority: will be favored.
6229Defaults to 1800.
6230.ip ClientCertFile
6231[no short name]
6232File containing the certificate of the client, i.e., this certificate
6233is used when
6234.i sendmail
6235acts as client (for STARTTLS).
6236.ip ClientKeyFile
6237[no short name]
6238File containing the private key belonging to the client certificate
6239(for STARTTLS if
6240.i sendmail
6241runs as client).
6242.ip ClientPortOptions=\fIoptions\fP
6243[O]
6244Set client SMTP options.
6245The options are
6246.i key=value
6247pairs separated by commas.
6248Known keys are:
6249.(b
6250.ta 1i
6251Port Name/number of source port for connection (defaults to any free port)
6252Addr Address mask (defaults INADDR_ANY)
6253Family Address family (defaults to INET)
6254SndBufSize Size of TCP send buffer
6255RcvBufSize Size of TCP receive buffer
6256Modifier Options (flags) for the daemon
6257.)b
6258The
6259.i Addr ess
6260mask may be a numeric address in dot notation
6261or a network name.
6262.i Modifier
6263can be the following character:
6264.(b
6265.ta 1i
6266h use name of interface for HELO command
6267A don't use AUTH when sending e-mail
6268S don't use STARTTLS when sending e-mail
6269.)b
6270If ``h'' is set, the name corresponding to the outgoing interface
6271address (whether chosen via the Connection parameter or
6272the default) is used for the HELO/EHLO command.
6273However, the name must not start with a square bracket
6274and it must contain at least one dot.
6275This is a simple test whether the name is not
6276an IP address (in square brackets) but a qualified hostname.
6277Note that multiple ClientPortOptions settings are allowed
6278in order to give settings for each protocol family
6279(e.g., one for Family=inet and one for Family=inet6).
6280A restriction placed on one family only affects
6281outgoing connections on that particular family.
6282.ip ColonOkInAddr
6283[no short name]
6284If set, colons are acceptable in e-mail addresses
6285(e.g.,
6286.q host:user ).
6287If not set, colons indicate the beginning of a RFC 822 group construct
6288(\c
6289.q "groupname: member1, member2, ... memberN;" ).
6290Doubled colons are always acceptable
6291(\c
6292.q nodename::user )
6293and proper route-addr nesting is understood
6294(\c
6295.q <@relay:user@host> ).
6296Furthermore, this option defaults on if the configuration version level
6297is less than 6 (for back compatibility).
6298However, it must be off for full compatibility with RFC 822.
6299.ip ConnectionCacheSize=\fIN\fP
6300[k]
6301The maximum number of open connections that will be cached at a time.
6302The default is one.
6303This delays closing the current connection until
6304either this invocation of
6305.i sendmail
6306needs to connect to another host
6307or it terminates.
6308Setting it to zero defaults to the old behavior,
6309that is, connections are closed immediately.
6310Since this consumes file descriptors,
6311the connection cache should be kept small:
63124 is probably a practical maximum.
6313.ip ConnectionCacheTimeout=\fItimeout\fP
6314[K]
6315The maximum amount of time a cached connection will be permitted to idle
6316without activity.
6317If this time is exceeded,
6318the connection is immediately closed.
6319This value should be small (on the order of ten minutes).
6320Before
6321.i sendmail
6322uses a cached connection,
6323it always sends a RSET command
6324to check the connection;
6325if this fails, it reopens the connection.
6326This keeps your end from failing if the other end times out.
6327The point of this option is to be a good network neighbor
6328and avoid using up excessive resources
6329on the other end.
6330The default is five minutes.
6331.ip ConnectOnlyTo=\fIaddress\fP
6332[no short name]
6333This can be used to
6334override the connection address (for testing purposes).
6335.ip ConnectionRateThrottle=\fIN\fP
6336[no short name]
6337If set to a positive value,
6338allow no more than
6339.i N
6340incoming connections in a one second period per daemon.
6341This is intended to flatten out peaks
6342and allow the load average checking to cut in.
6343Defaults to zero (no limits).
6344.ip ControlSocketName=\fIname\fP
6345[no short name]
6346Name of the control socket for daemon management.
6347A running
6348.i sendmail
6349daemon can be controlled through this named socket.
6350Available commands are:
6351.i help,
6352.i restart,
6353.i shutdown,
6354and
6355.i status.
6356The
6357.i status
6358command returns the current number of daemon children,
6359the maximum number of daemon children,
6360the free disk space (in blocks) of the queue directory,
6361and the load average of the machine expressed as an integer.
6362If not set, no control socket will be available.
6363Solaris and pre-4.4BSD kernel users should see the note in sendmail/README .
6364.ip DHParameters
6365File with DH parameters for STARTTLS.
6366This is only required if a ciphersuite containing DSA/DH is used.
6367This is only for people with a good knowledge of TLS, all others
6368can ignore this option.
6369.ip DaemonPortOptions=\fIoptions\fP
6370[O]
6371Set server SMTP options.
6372Each instance of DaemonPortOptions leads to an additional incoming socket.
6373The options are
6374.i key=value
6375pairs.
6376Known keys are:
6377.(b
6378.ta 1i
6379Name User-definable name for the daemon (defaults to "Daemon#")
6380Port Name/number of listening port (defaults to "smtp")
6381Addr Address mask (defaults INADDR_ANY)
6382Family Address family (defaults to INET)
6383Listen Size of listen queue (defaults to 10)
6384Modifier Options (flags) for the daemon
6385SndBufSize Size of TCP send buffer
6386RcvBufSize Size of TCP receive buffer
6387.)b
6388The
6389.i Name
6390field is used for error messages and logging.
6391The
6392.i Addr ess
6393mask may be a numeric address in dot notation
6394or a network name.
6395The
6396.i Family
6397key defaults to INET (IPv4).
6398IPv6 users who wish to also accept IPv6 connections
6399should add additional Family=inet6 DaemonPortOptions lines.
6400.i Modifier
6401can be a sequence (without any delimiters)
6402of the following characters:
6403.(b
6404.ta 1i
6405a always require authentication
6406b bind to interface through which mail has been received
6407c perform hostname canonification (.cf)
6408f require fully qualified hostname (.cf)
6409u allow unqualified addresses (.cf)
6410A disable AUTH (overrides 'a' modifier)
6411C don't perform hostname canonification
6412E disallow ETRN (see RFC 2476)
6413O optional; if opening the socket fails ignore it
6414S don't offer STARTTLS
6415.)b
6416That is, one way to specify a message submission agent (MSA) that
6417always requires authentication is:
6418.(b
6419O DaemonPortOptions=Name=MSA, Port=587, M=Ea
6420.)b
6421The modifiers that are marked with "(.cf)" have only
6422effect in the standard configuration file, in which
6423they are available via
6424.b ${daemon_flags} .
6425Notice: Do
6426.b not
6427use the ``a'' modifier on a public accessible MTA!
6428It should only be used for a MSA that is accessed by authorized
6429users for initial mail submission.
6430Users must authenticate to use a MSA which has this option turned on.
6431The flags ``c'' and ``C'' can change the default for
6432hostname canonification in the
6433.i sendmail.cf
6434file.
6435See the relevant documentation for
6436.sm FEATURE(nocanonify) .
6437The modifier ``f'' disallows addresses of the form
6438.b user@host
6439unless they are submitted directly.
6440The flag ``u'' allows unqualified sender addresses,
6441i.e., those without @host.
6442``b'' forces sendmail to bind to the interface
6443through which the e-mail has been
6444received for the outgoing connection.
6445.b WARNING:
6446Use ``b''
6447only if outgoing mail can be routed through the incoming connection's
6448interface to its destination. No attempt is made to catch problems due to a
6449misconfiguration of this parameter, use it only for virtual hosting
6450where each virtual interface can connect to every possible location.
6451This will also override possible settings via
6452.b ClientPortOptions.
6453Note,
6454.i sendmail
6455will listen on a new socket
6456for each occurence of the DaemonPortOptions option
6457in a configuration file.
6458The modifier ``O'' causes sendmail to ignore a socket
6459if it can't be opened.
6460This applies to failures from the socket(2) and bind(2) calls.
6461.ip DefaultAuthInfo
6462[no short name]
6463Filename that contains default authentication information for outgoing
6464connections. This file must contain the user id, the authorization id,
6465the password (plain text), the realm and the list of mechanisms to use
6466on separate lines and must be readable by
6467root (or the trusted user) only.
6468If no realm is specified,
6469.b $j
6470is used.
6471If no mechanisms are specified, the list given by
6472.b AuthMechanisms
6473is used.
6474Notice: this option is deprecated and will be removed in future versions.
6475Moreover, it doesn't work for the MSP since it can't read the file
6476(the file must not be group/world-readable otherwise
6477.i sendmail
6478will complain).
6479Use the authinfo ruleset instead which provides more control over
6480the usage of the data anyway.
6481.ip DefaultCharSet=\fIcharset\fP
6482[no short name]
6483When a message that has 8-bit characters but is not in MIME format
6484is converted to MIME
6485(see the EightBitMode option)
6486a character set must be included in the Content-Type: header.
6487This character set is normally set from the Charset= field
6488of the mailer descriptor.
6489If that is not set, the value of this option is used.
6490If this option is not set, the value
6491.q unknown-8bit
6492is used.
6493.ip DataFileBufferSize=\fIthreshold\fP
6494[no short name]
6495Set the
6496.i threshold ,
6497in bytes,
6498before a memory-based
6499queue data file
6500becomes disk-based.
6501The default is 4096 bytes.
6502.ip DeadLetterDrop=\fIfile\fP
6503[no short name]
6504Defines the location of the system-wide dead.letter file,
6505formerly hardcoded to /usr/tmp/dead.letter.
6506If this option is not set (the default),
6507sendmail will not attempt to save to a system-wide dead.letter file
6508in the event
6509it cannot bounce the mail to the user or postmaster.
6510Instead, it will rename the qf file
6511as it has in the past
6512when the dead.letter file could not be opened.
6513.ip DefaultUser=\fIuser:group\fP
6514[u]
6515Set the default userid for mailers to
6516.i user:group .
6517If
6518.i group
6519is omitted and
6520.i user
6521is a user name
6522(as opposed to a numeric user id)
6523the default group listed in the /etc/passwd file for that user is used
6524as the default group.
6525Both
6526.i user
6527and
6528.i group
6529may be numeric.
6530Mailers without the
6531.i S
6532flag in the mailer definition
6533will run as this user.
6534Defaults to 1:1.
6535The value can also be given as a symbolic user name.\**
6536.(f
6537\**The old
6538.b g
6539option has been combined into the
6540.b DefaultUser
6541option.
6542.)f
6543.ip DelayLA=\fILA\fP
6544[no short name]
6545When the system load average exceeds
6546.i LA ,
6547.i sendmail
6548will sleep for one second on most SMTP commands and
6549before accepting connections.
6550.ip DeliverByMin=\fItime\fP
6551[0]
6552Set minimum time for Deliver By SMTP Service Extension (RFC 2852).
6553If 0, no time is listed, if less than 0, the extension is not offered,
6554if greater than 0, it is listed as minimum time
6555for the EHLO keyword DELIVERBY.
6556.ip DeliveryMode=\fIx\fP
6557[d]
6558Deliver in mode
6559.i x .
6560Legal modes are:
6561.(b
6562.ta 4n
6563i Deliver interactively (synchronously)
6564b Deliver in background (asynchronously)
6565q Just queue the message (deliver during queue run)
6566d Defer delivery and all map lookups (deliver during queue run)
6567.)b
6568Defaults to ``b'' if no option is specified,
6569``i'' if it is specified but given no argument
6570(i.e., ``Od'' is equivalent to ``Odi'').
6571The
6572.b \-v
6573command line flag sets this to
6574.b i .
6575.ip DialDelay=\fIsleeptime\fP
6576[no short name]
6577Dial-on-demand network connections can see timeouts
6578if a connection is opened before the call is set up.
6579If this is set to an interval and a connection times out
6580on the first connection being attempted
6581.i sendmail
6582will sleep for this amount of time and try again.
6583This should give your system time to establish the connection
6584to your service provider.
6585Units default to seconds, so
6586.q DialDelay=5
6587uses a five second delay.
6588Defaults to zero
6589(no retry).
6590This delay only applies to mailers which have the
6591Z flag set.
6592.ip DirectSubmissionModifiers=\fImodifiers\fP
6593Defines
6594.b ${daemon_flags}
6595for direct (command line) submissions.
6596If not set,
6597.b ${daemon_flags}
6598is either "CC f" if the option
6599.b \-G
6600is used or "c u" otherwise.
6601Note that only the the "CC", "c", "f", and "u" flags are checked.
6602.ip DontBlameSendmail=\fIoption,option,...\fP
6603[no short name]
6604In order to avoid possible cracking attempts
6605caused by world- and group-writable files and directories,
6606.i sendmail
6607does paranoid checking when opening most of its support files.
6608If for some reason you absolutely must run with,
6609for example,
6610a group-writable
6611.i /etc
6612directory,
6613then you will have to turn off this checking
6614(at the cost of making your system more vulnerable to attack).
6615The possible arguments have been described earlier.
6616The details of these flags are described above.
6617.\"XXX should have more here!!! XXX
6618.b "Use of this option is not recommended."
6619.ip DontExpandCnames
6620[no short name]
6621The standards say that all host addresses used in a mail message
6622must be fully canonical.
6623For example, if your host is named
6624.q Cruft.Foo.ORG
6625and also has an alias of
6626.q FTP.Foo.ORG ,
6627the former name must be used at all times.
6628This is enforced during host name canonification
6629($[ ... $] lookups).
6630If this option is set, the protocols are ignored and the
6631.q wrong
6632thing is done.
6633However, the IETF is moving toward changing this standard,
6634so the behavior may become acceptable.
6635Please note that hosts downstream may still rewrite the address
6636to be the true canonical name however.
6637.ip DontInitGroups
6638[no short name]
6639If set,
6640.i sendmail
6641will avoid using the initgroups(3) call.
6642If you are running NIS,
6643this causes a sequential scan of the groups.byname map,
6644which can cause your NIS server to be badly overloaded in a large domain.
6645The cost of this is that the only group found for users
6646will be their primary group (the one in the password file),
6647which will make file access permissions somewhat more restrictive.
6648Has no effect on systems that don't have group lists.
6649.ip DontProbeInterfaces
6650[no short name]
6651.i Sendmail
6652normally finds the names of all interfaces active on your machine
6653when it starts up
6654and adds their name to the
6655.b $=w
6656class of known host aliases.
6657If you have a large number of virtual interfaces
6658or if your DNS inverse lookups are slow
6659this can be time consuming.
6660This option turns off that probing.
6661However, you will need to be certain to include all variant names
6662in the
6663.b $=w
6664class by some other mechanism.
6665If set to
6666.b loopback ,
6667loopback interfaces (e.g., lo0) will not be probed.
6668.ip DontPruneRoutes
6669[R]
6670Normally,
6671.i sendmail
6672tries to eliminate any unnecessary explicit routes
6673when sending an error message
6674(as discussed in RFC 1123 \(sc 5.2.6).
6675For example,
6676when sending an error message to
6677.(b
6678<@known1,@known2,@known3:user@unknown>
6679.)b
6680.i sendmail
6681will strip off the
6682.q @known1,@known2
6683in order to make the route as direct as possible.
6684However, if the
6685.b R
6686option is set, this will be disabled,
6687and the mail will be sent to the first address in the route,
6688even if later addresses are known.
6689This may be useful if you are caught behind a firewall.
6690.ip DoubleBounceAddress=\fIerror-address\fP
6691[no short name]
6692If an error occurs when sending an error message,
6693send the error report
6694(termed a
6695.q "double bounce"
6696because it is an error
6697.q bounce
6698that occurs when trying to send another error
6699.q bounce )
6700to the indicated address.
6701The address is macro expanded
6702at the time of delivery.
6703If not set, defaults to
6704.q postmaster .
6705If set to an empty string, double bounces are dropped.
6706.ip EightBitMode=\fIaction\fP
6707[8]
6708Set handling of eight-bit data.
6709There are two kinds of eight-bit data:
6710that declared as such using the
6711.b BODY=8BITMIME
6712ESMTP declaration or the
6713.b \-B8BITMIME
6714command line flag,
6715and undeclared 8-bit data, that is,
6716input that just happens to be eight bits.
6717There are three basic operations that can happen:
6718undeclared 8-bit data can be automatically converted to 8BITMIME,
6719undeclared 8-bit data can be passed as-is without conversion to MIME
6720(``just send 8''),
6721and declared 8-bit data can be converted to 7-bits
6722for transmission to a non-8BITMIME mailer.
6723The possible
6724.i action s
6725are:
6726.(b
6727.\" r Reject undeclared 8-bit data;
6728.\" don't convert 8BITMIME\(->7BIT (``reject'')
6729 s Reject undeclared 8-bit data (``strict'')
6730.\" do convert 8BITMIME\(->7BIT (``strict'')
6731.\" c Convert undeclared 8-bit data to MIME;
6732.\" don't convert 8BITMIME\(->7BIT (``convert'')
6733 m Convert undeclared 8-bit data to MIME (``mime'')
6734.\" do convert 8BITMIME\(->7BIT (``mime'')
6735.\" j Pass undeclared 8-bit data;
6736.\" don't convert 8BITMIME\(->7BIT (``just send 8'')
6737 p Pass undeclared 8-bit data (``pass'')
6738.\" do convert 8BITMIME\(->7BIT (``pass'')
6739.\" a Adaptive algorithm: see below
6740.)b
6741.\"The adaptive algorithm is to accept 8-bit data,
6742.\"converting it to 8BITMIME only if the receiver understands that,
6743.\"otherwise just passing it as undeclared 8-bit data;
6744.\"8BITMIME\(->7BIT conversions are done.
6745In all cases properly declared 8BITMIME data will be converted to 7BIT
6746as needed.
6747.ip ErrorHeader=\fIfile-or-message\fP
6748[E]
6749Prepend error messages with the indicated message.
6750If it begins with a slash,
6751it is assumed to be the pathname of a file
6752containing a message (this is the recommended setting).
6753Otherwise, it is a literal message.
6754The error file might contain the name, email address, and/or phone number
6755of a local postmaster who could provide assistance
6756to end users.
6757If the option is missing or null,
6758or if it names a file which does not exist or which is not readable,
6759no message is printed.
6760.ip ErrorMode=\fIx\fP
6761[e]
6762Dispose of errors using mode
6763.i x .
6764The values for
6765.i x
6766are:
6767.(b
6768p Print error messages (default)
6769q No messages, just give exit status
6770m Mail back errors
6771w Write back errors (mail if user not logged in)
| 4621used for a TLS connection.
4622.ip ${client_addr}
4623The IP address of the SMTP client.
4624IPv6 addresses are tagged with "IPv6:" before the address.
4625Defined in the SMTP server only.
4626.ip ${client_name}
4627The host name of the SMTP client.
4628This may be the client's bracketed IP address
4629in the form [ nnn.nnn.nnn.nnn ] for IPv4
4630and [ IPv6:nnnn:...:nnnn ] for IPv6
4631if the client's
4632IP address is not resolvable, or if it is resolvable
4633but the IP address of the resolved hostname
4634doesn't match the original IP address.
4635Defined in the SMTP server only.
4636See also
4637.b ${client_resolve} .
4638.ip ${client_port}
4639The port number of the SMTP client.
4640Defined in the SMTP server only.
4641.ip ${client_resolve}
4642Holds the result of the resolve call for
4643.b ${client_name} .
4644Possible values are:
4645.(b
4646.ta 10n
4647OK resolved successfully
4648FAIL permanent lookup failure
4649FORGED forward lookup doesn't match reverse lookup
4650TEMP temporary lookup failure
4651.)b
4652Defined in the SMTP server only.
4653.i sendmail
4654performs a hostname lookup on the IP address of the connecting client.
4655Next the IP addresses of that hostname are looked up.
4656If the client IP address does not appear in that list,
4657then the hostname is maybe forged.
4658This is reflected as the value FORGED for
4659.b ${client_resolve}
4660and it also shows up in
4661.b $_
4662as "(may be forged)".
4663.ip ${cn_issuer}
4664The CN (common name) of the CA that signed the presented certificate
4665(STARTTLS only).
4666.ip ${cn_subject}
4667The CN (common name) of the presented certificate
4668(STARTTLS only).
4669.ip ${currHeader}
4670Header value as quoted string
4671(possibly truncated to
4672.b MAXNAME ).
4673This macro is only available in header check rulesets.
4674.ip ${daemon_addr}
4675The IP address the daemon is listening on for connections.
4676.ip ${daemon_family}
4677The network family
4678if the daemon is accepting network connections.
4679Possible values include
4680.q inet ,
4681.q inet6 ,
4682.q iso ,
4683.q ns ,
4684.q x.25
4685.ip ${daemon_flags}
4686The flags for the daemon as specified by the
4687Modifier= part of
4688.b DaemonPortOptions
4689whereby the flags are separated from each other by spaces,
4690and upper case flags are doubled.
4691That is,
4692Modifier=Ea
4693will be represented as
4694"EE a" in
4695.b ${daemon_flags} ,
4696which is required for testing the flags in rulesets.
4697.ip ${daemon_info}
4698Some information about a daemon as a text string.
4699For example,
4700.q SMTP+queueing@00:30:00 .
4701.ip ${daemon_name}
4702The name of the daemon from
4703.b DaemonPortOptions
4704Name= suboption.
4705If this suboption is not set,
4706"Daemon#",
4707where # is the daemon number,
4708is used.
4709.ip ${daemon_port}
4710The port the daemon is accepting connection on.
4711Unless
4712.b DaemonPortOptions
4713is set, this will most likely be
4714.q 25 .
4715.ip ${deliveryMode}
4716The current delivery mode sendmail is using.
4717It is initially set to the value of the
4718.b DeliveryMode
4719option.
4720.ip ${envid}
4721The envelope id parameter (ENVID=) passed to sendmail as part of the envelope.
4722.ip ${hdrlen}
4723The length of the header value which is stored in
4724${currHeader} (before possible truncation).
4725If this value is greater than or equal to
4726.b MAXNAME
4727the header has been truncated.
4728.ip ${hdr_name}
4729The name of the header field for which the current header
4730check ruleset has been called.
4731This is useful for a default header check ruleset to get
4732the name of the header;
4733the macro is only available in header check rulesets.
4734.ip ${if_addr}
4735The IP address of the interface of an incoming connection
4736unless it is in the loopback net.
4737IPv6 addresses are tagged with "IPv6:" before the address.
4738.ip ${if_addr_out}
4739The IP address of the interface of an outgoing connection
4740unless it is in the loopback net.
4741IPv6 addresses are tagged with "IPv6:" before the address.
4742.ip ${if_family}
4743The IP family of the interface of an incoming connection
4744unless it is in the loopback net.
4745.ip ${if_family_out}
4746The IP family of the interface of an outgoing connection
4747unless it is in the loopback net.
4748.ip ${if_name}
4749The hostname associated with the interface of an incoming connection.
4750This macro can be used for
4751SmtpGreetingMessage and HReceived for virtual hosting.
4752For example:
4753.(b
4754O SmtpGreetingMessage=$?{if_name}${if_name}$|$j$. MTA
4755.)b
4756.ip ${if_name_out}
4757The name of the interface of an outgoing connection.
4758.ip ${mail_addr}
4759The address part of the resolved triple of the address given for the
4760.sm "SMTP MAIL"
4761command.
4762Defined in the SMTP server only.
4763.ip ${mail_host}
4764The host from the resolved triple of the address given for the
4765.sm "SMTP MAIL"
4766command.
4767Defined in the SMTP server only.
4768.ip ${mail_mailer}
4769The mailer from the resolved triple of the address given for the
4770.sm "SMTP MAIL"
4771command.
4772Defined in the SMTP server only.
4773.ip ${msg_size}
4774The value of the SIZE= parameter,
4775i.e., usually the size of the message (in an ESMTP dialogue),
4776before the message has been collected, thereafter
4777the message size as computed by
4778.i sendmail
4779(and can be used in check_compat).
4780.ip ${nrcpts}
4781The number of validated recipients for a single message.
4782Note: since recipient validation happens after
4783.i check_rcpt
4784has been called, the value in this ruleset
4785is one less than what might be expected.
4786.ip ${ntries}
4787The number of delivery attempts.
4788.ip ${opMode}
4789The current operation mode (from the
4790.b \-b
4791flag).
4792.ip ${queue_interval}
4793The queue run interval given by the
4794.b \-q
4795flag.
4796For example,
4797.b \-q30m
4798would set
4799.b ${queue_interval}
4800to
4801.q 00:30:00 .
4802.ip ${rcpt_addr}
4803The address part of the resolved triple of the address given for the
4804.sm "SMTP RCPT"
4805command.
4806Defined in the SMTP server only after a RCPT command.
4807.ip ${rcpt_host}
4808The host from the resolved triple of the address given for the
4809.sm "SMTP RCPT"
4810command.
4811Defined in the SMTP server only after a RCPT command.
4812.ip ${rcpt_mailer}
4813The mailer from the resolved triple of the address given for the
4814.sm "SMTP RCPT"
4815command.
4816Defined in the SMTP server only after a RCPT command.
4817.ip ${server_addr}
4818The address of the server of the current outgoing SMTP connection.
4819For LMTP delivery the macro is set to the name of the mailer.
4820.ip ${server_name}
4821The name of the server of the current outgoing SMTP or LMTP connection.
4822.ip ${tls_version}
4823The TLS/SSL version used for the connection, e.g., TLSv1, SSLv3, SSLv2;
4824defined after STARTTLS has been used.
4825.ip ${verify}
4826The result of the verification of the presented cert;
4827only defined after STARTTLS has been used.
4828Possible values are:
4829.(b
4830.ta 13n
4831OK verification succeeded.
4832NO no cert presented.
4833NOT no cert requested.
4834FAIL cert presented but could not be verified,
4835 e.g., the signing CA is missing.
4836NONE STARTTLS has not been performed.
4837TEMP temporary error occurred.
4838PROTOCOL some protocol error occurred.
4839SOFTWARE STARTTLS handshake failed,
4840 which is a fatal error for this session,
4841 the e-mail will be queued.
4842.)b
4843.pp
4844There are three types of dates that can be used.
4845The
4846.b $a
4847and
4848.b $b
4849macros are in RFC 822 format;
4850.b $a
4851is the time as extracted from the
4852.q Date:
4853line of the message
4854(if there was one),
4855and
4856.b $b
4857is the current date and time
4858(used for postmarks).
4859If no
4860.q Date:
4861line is found in the incoming message,
4862.b $a
4863is set to the current time also.
4864The
4865.b $d
4866macro is equivalent to the
4867.b $b
4868macro in UNIX
4869(ctime)
4870format.
4871.pp
4872The macros
4873.b $w ,
4874.b $j ,
4875and
4876.b $m
4877are set to the identity of this host.
4878.i Sendmail
4879tries to find the fully qualified name of the host
4880if at all possible;
4881it does this by calling
4882.i gethostname (2)
4883to get the current hostname
4884and then passing that to
4885.i gethostbyname (3)
4886which is supposed to return the canonical version of that host name.\**
4887.(f
4888\**For example, on some systems
4889.i gethostname
4890might return
4891.q foo
4892which would be mapped to
4893.q foo.bar.com
4894by
4895.i gethostbyname .
4896.)f
4897Assuming this is successful,
4898.b $j
4899is set to the fully qualified name
4900and
4901.b $m
4902is set to the domain part of the name
4903(everything after the first dot).
4904The
4905.b $w
4906macro is set to the first word
4907(everything before the first dot)
4908if you have a level 5 or higher configuration file;
4909otherwise, it is set to the same value as
4910.b $j .
4911If the canonification is not successful,
4912it is imperative that the config file set
4913.b $j
4914to the fully qualified domain name\**.
4915.(f
4916\**Older versions of sendmail didn't pre-define
4917.b $j
4918at all, so up until 8.6,
4919config files
4920.i always
4921had to define
4922.b $j .
4923.)f
4924.pp
4925The
4926.b $f
4927macro is the id of the sender
4928as originally determined;
4929when mailing to a specific host
4930the
4931.b $g
4932macro is set to the address of the sender
4933.ul
4934relative to the recipient.
4935For example,
4936if I send to
4937.q bollard@matisse.CS.Berkeley.EDU
4938from the machine
4939.q vangogh.CS.Berkeley.EDU
4940the
4941.b $f
4942macro will be
4943.q eric
4944and the
4945.b $g
4946macro will be
4947.q eric@vangogh.CS.Berkeley.EDU.
4948.pp
4949The
4950.b $x
4951macro is set to the full name of the sender.
4952This can be determined in several ways.
4953It can be passed as flag to
4954.i sendmail .
4955It can be defined in the
4956.sm NAME
4957environment variable.
4958The third choice is the value of the
4959.q Full-Name:
4960line in the header if it exists,
4961and the fourth choice is the comment field
4962of a
4963.q From:
4964line.
4965If all of these fail,
4966and if the message is being originated locally,
4967the full name is looked up in the
4968.i /etc/passwd
4969file.
4970.pp
4971When sending,
4972the
4973.b $h ,
4974.b $u ,
4975and
4976.b $z
4977macros get set to the host, user, and home directory
4978(if local)
4979of the recipient.
4980The first two are set from the
4981.b $@
4982and
4983.b $:
4984part of the rewriting rules, respectively.
4985.pp
4986The
4987.b $p
4988and
4989.b $t
4990macros are used to create unique strings
4991(e.g., for the
4992.q Message-Id:
4993field).
4994The
4995.b $i
4996macro is set to the queue id on this host;
4997if put into the timestamp line
4998it can be extremely useful for tracking messages.
4999The
5000.b $v
5001macro is set to be the version number of
5002.i sendmail ;
5003this is normally put in timestamps
5004and has been proven extremely useful for debugging.
5005.pp
5006The
5007.b $c
5008field is set to the
5009.q "hop count,"
5010i.e., the number of times this message has been processed.
5011This can be determined
5012by the
5013.b \-h
5014flag on the command line
5015or by counting the timestamps in the message.
5016.pp
5017The
5018.b $r
5019and
5020.b $s
5021fields are set to the protocol used to communicate with
5022.i sendmail
5023and the sending hostname.
5024They can be set together using the
5025.b \-p
5026command line flag or separately using the
5027.b \-M
5028or
5029.b \-oM
5030flags.
5031.pp
5032The
5033.b $_
5034is set to a validated sender host name.
5035If the sender is running an RFC 1413 compliant IDENT server
5036and the receiver has the IDENT protocol turned on,
5037it will include the user name on that host.
5038.pp
5039The
5040.b ${client_name} ,
5041.b ${client_addr} ,
5042and
5043.b ${client_port}
5044macros
5045are set to the name, address, and port number of the SMTP client
5046who is invoking
5047.i sendmail
5048as a server.
5049These can be used in the
5050.i check_*
5051rulesets (using the
5052.b $&
5053deferred evaluation form, of course!).
5054.sh 2 "C and F \*- Define Classes"
5055.pp
5056Classes of phrases may be defined
5057to match on the left hand side of rewriting rules,
5058where a
5059.q phrase
5060is a sequence of characters that does not contain space characters.
5061For example
5062a class of all local names for this site
5063might be created
5064so that attempts to send to oneself
5065can be eliminated.
5066These can either be defined directly in the configuration file
5067or read in from another file.
5068Classes are named as a single letter or a word in {braces}.
5069Class names beginning with lower case letters
5070and special characters are reserved for system use.
5071Classes defined in config files may be given names
5072from the set of upper case letters for short names
5073or beginning with an upper case letter for long names.
5074.pp
5075The syntax is:
5076.(b F
5077.b C \c
5078.i c\|phrase1
5079.i phrase2...
5080.br
5081.b F \c
5082.i c\|file
5083.br
5084.b F \c
5085.i c\||program
5086.br
5087.b F \c
5088.i c\|[mapkey]@mapclass:mapspec
5089.)b
5090The first form defines the class
5091.i c
5092to match any of the named words.
5093If
5094.i phrase1
5095or
5096.i phrase2
5097is another class,
5098e.g.,
5099.i $=S ,
5100the contents of class
5101.i S
5102are added to class
5103.i c .
5104It is permissible to split them among multiple lines;
5105for example, the two forms:
5106.(b
5107CHmonet ucbmonet
5108.)b
5109and
5110.(b
5111CHmonet
5112CHucbmonet
5113.)b
5114are equivalent.
5115The ``F'' forms
5116read the elements of the class
5117.i c
5118from the named
5119.i file ,
5120.i program ,
5121or
5122.i "map specification" .
5123Each element should be listed on a separate line.
5124To specify an optional file, use ``\-o'' between the class
5125name and the file name, e.g.,
5126.(b
5127Fc \-o /path/to/file
5128.)b
5129If the file can't be used,
5130.i sendmail
5131will not complain but silently ignore it.
5132The map form should be an optional map key, an at sign,
5133and a map class followed by the specification for that map.
5134Examples include:
5135.(b
5136F{VirtHosts}@ldap:\-k (&(objectClass=virtHosts)(host=*)) \-v host
5137F{MyClass}foo@hash:/etc/mail/classes
5138.)b
5139will fill the class
5140.b $={VirtHosts}
5141from an LDAP map lookup and
5142.b $={MyClass}
5143from a hash database map lookup of the
5144.b foo .
5145There is also a built-in schema that can be accessed by only specifying:
5146.(b
5147F{\c
5148.i ClassName }@LDAP
5149.)b
5150This will tell sendmail to use the default schema:
5151.(b
5152\-k (&(objectClass=sendmailMTAClass)
5153 (sendmailMTAClassName=\c
5154.i ClassName )
5155 (|(sendmailMTACluster=${sendmailMTACluster})
5156 (sendmailMTAHost=$j)))
5157\-v sendmailMTAClassValue
5158.)b
5159Note that the lookup is only done when sendmail is initially started.
5160.pp
5161Elements of classes can be accessed in rules using
5162.b $=
5163or
5164.b $~ .
5165The
5166.b $~
5167(match entries not in class)
5168only matches a single word;
5169multi-word entries in the class are ignored in this context.
5170.pp
5171Some classes have internal meaning to
5172.i sendmail :
5173.nr ii 0.5i
5174.\".ip $=b
5175.\"A set of Content-Types that will not have the newline character
5176.\"translated to CR-LF before encoding into base64 MIME.
5177.\"The class can have major times
5178.\"(e.g.,
5179.\".q image )
5180.\"or full types
5181.\"(such as
5182.\".q application/octet-stream ).
5183.\"The class is initialized with
5184.\".q application/octet-stream ,
5185.\".q image ,
5186.\".q audio ,
5187.\"and
5188.\".q video .
5189.ip $=e
5190contains the Content-Transfer-Encodings that can be 8\(->7 bit encoded.
5191It is predefined to contain
5192.q 7bit ,
5193.q 8bit ,
5194and
5195.q binary .
5196.ip $=k
5197set to be the same as
5198.b $k ,
5199that is, the UUCP node name.
5200.ip $=m
5201set to the set of domains by which this host is known,
5202initially just
5203.b $m .
5204.ip $=n
5205can be set to the set of MIME body types
5206that can never be eight to seven bit encoded.
5207It defaults to
5208.q multipart/signed .
5209Message types
5210.q message/*
5211and
5212.q multipart/*
5213are never encoded directly.
5214Multipart messages are always handled recursively.
5215The handling of message/* messages
5216are controlled by class
5217.b $=s .
5218.ip $=q
5219A set of Content-Types that will never be encoded as base64
5220(if they have to be encoded, they will be encoded as quoted-printable).
5221It can have primary types
5222(e.g.,
5223.q text )
5224or full types
5225(such as
5226.q text/plain ).
5227The class is initialized to have
5228.q text/plain
5229only.
5230.ip $=s
5231contains the set of subtypes of message that can be treated recursively.
5232By default it contains only
5233.q rfc822 .
5234Other
5235.q message/*
5236types cannot be 8\(->7 bit encoded.
5237If a message containing eight bit data is sent to a seven bit host,
5238and that message cannot be encoded into seven bits,
5239it will be stripped to 7 bits.
5240.ip $=t
5241set to the set of trusted users by the
5242.b T
5243configuration line.
5244If you want to read trusted users from a file, use
5245.b Ft \c
5246.i /file/name .
5247.ip $=w
5248set to be the set of all names
5249this host is known by.
5250This can be used to match local hostnames.
5251.ip $={persistentMacros}
5252set to the macros would should be saved across queue runs.
5253Care should be taken when adding macro names to this class.
5254.pp
5255.i Sendmail
5256can be compiled to allow a
5257.i scanf (3)
5258string on the
5259.b F
5260line.
5261This lets you do simplistic parsing of text files.
5262For example, to read all the user names in your system
5263.i /etc/passwd
5264file into a class, use
5265.(b
5266FL/etc/passwd %[^:]
5267.)b
5268which reads every line up to the first colon.
5269.sh 2 "M \*- Define Mailer"
5270.pp
5271Programs and interfaces to mailers
5272are defined in this line.
5273The format is:
5274.(b F
5275.b M \c
5276.i name ,
5277{\c
5278.i field =\c
5279.i value \|}*
5280.)b
5281where
5282.i name
5283is the name of the mailer
5284(used internally only)
5285and the
5286.q field=name
5287pairs define attributes of the mailer.
5288Fields are:
5289.(b
5290.ta 1i
5291Path The pathname of the mailer
5292Flags Special flags for this mailer
5293Sender Rewriting set(s) for sender addresses
5294Recipient Rewriting set(s) for recipient addresses
5295recipients Maximum number of recipients per connection
5296Argv An argument vector to pass to this mailer
5297Eol The end-of-line string for this mailer
5298Maxsize The maximum message length to this mailer
5299maxmessages The maximum message deliveries per connection
5300Linelimit The maximum line length in the message body
5301Directory The working directory for the mailer
5302Userid The default user and group id to run as
5303Nice The nice(2) increment for the mailer
5304Charset The default character set for 8-bit characters
5305Type Type information for DSN diagnostics
5306Wait The maximum time to wait for the mailer
5307Queuegroup The default queue group for the mailer
5308/ The root directory for the mailer
5309.)b
5310Only the first character of the field name is checked
5311(it's case-sensitive).
5312.pp
5313The following flags may be set in the mailer description.
5314Any other flags may be used freely
5315to conditionally assign headers to messages
5316destined for particular mailers.
5317Flags marked with \(dg
5318are not interpreted by the
5319.i sendmail
5320binary;
5321these are the conventionally used to correlate to the flags portion
5322of the
5323.b H
5324line.
5325Flags marked with \(dd
5326apply to the mailers for the sender address
5327rather than the usual recipient mailers.
5328.nr ii 4n
5329.ip a
5330Run Extended SMTP (ESMTP) protocol (defined in RFCs 1869, 1652, and 1870).
5331This flag defaults on if the SMTP greeting message includes the word
5332.q ESMTP .
5333.ip A
5334Look up the user part of the address in the alias database.
5335Normally this is only set for local mailers.
5336.ip b
5337Force a blank line on the end of a message.
5338This is intended to work around some stupid versions of
5339/bin/mail
5340that require a blank line, but do not provide it themselves.
5341It would not normally be used on network mail.
5342.ip c
5343Do not include comments in addresses.
5344This should only be used if you have to work around
5345a remote mailer that gets confused by comments.
5346This strips addresses of the form
5347.q "Phrase <address>"
5348or
5349.q "address (Comment)"
5350down to just
5351.q address .
5352.ip C\(dd
5353If mail is
5354.i received
5355from a mailer with this flag set,
5356any addresses in the header that do not have an at sign
5357(\c
5358.q @ )
5359after being rewritten by ruleset three
5360will have the
5361.q @domain
5362clause from the sender envelope address
5363tacked on.
5364This allows mail with headers of the form:
5365.(b
5366From: usera@hosta
5367To: userb@hostb, userc
5368.)b
5369to be rewritten as:
5370.(b
5371From: usera@hosta
5372To: userb@hostb, userc@hosta
5373.)b
5374automatically.
5375However, it doesn't really work reliably.
5376.ip d
5377Do not include angle brackets around route-address syntax addresses.
5378This is useful on mailers that are going to pass addresses to a shell
5379that might interpret angle brackets as I/O redirection.
5380However, it does not protect against other shell metacharacters.
5381Therefore, passing addresses to a shell should not be considered secure.
5382.ip D\(dg
5383This mailer wants a
5384.q Date:
5385header line.
5386.ip e
5387This mailer is expensive to connect to,
5388so try to avoid connecting normally;
5389any necessary connection will occur during a queue run.
5390See also option
5391.b HoldExpensive .
5392.ip E
5393Escape lines beginning with
5394.q From\0
5395in the message with a `>' sign.
5396.ip f
5397The mailer wants a
5398.b \-f
5399.i from
5400flag,
5401but only if this is a network forward operation
5402(i.e.,
5403the mailer will give an error
5404if the executing user
5405does not have special permissions).
5406.ip F\(dg
5407This mailer wants a
5408.q From:
5409header line.
5410.ip g
5411Normally,
5412.i sendmail
5413sends internally generated email (e.g., error messages)
5414using the null return address
5415as required by RFC 1123.
5416However, some mailers don't accept a null return address.
5417If necessary,
5418you can set the
5419.b g
5420flag to prevent
5421.i sendmail
5422from obeying the standards;
5423error messages will be sent as from the MAILER-DAEMON
5424(actually, the value of the
5425.b $n
5426macro).
5427.ip h
5428Upper case should be preserved in host names
5429(the $@ portion of the mailer triplet resolved from ruleset 0)
5430for this mailer.
5431.ip i
5432Do User Database rewriting on envelope sender address.
5433.ip I
5434This mailer will be speaking SMTP
5435to another
5436.i sendmail
5437\*-
5438as such it can use special protocol features.
5439This flag should not be used except for debugging purposes
5440because it uses
5441.b VERB
5442as SMTP command.
5443.ip j
5444Do User Database rewriting on recipients as well as senders.
5445.ip k
5446Normally when
5447.i sendmail
5448connects to a host via SMTP,
5449it checks to make sure that this isn't accidently the same host name
5450as might happen if
5451.i sendmail
5452is misconfigured or if a long-haul network interface is set in loopback mode.
5453This flag disables the loopback check.
5454It should only be used under very unusual circumstances.
5455.ip K
5456Currently unimplemented.
5457Reserved for chunking.
5458.ip l
5459This mailer is local
5460(i.e.,
5461final delivery will be performed).
5462.ip L
5463Limit the line lengths as specified in RFC 821.
5464This deprecated option should be replaced by the
5465.b L=
5466mail declaration.
5467For historic reasons, the
5468.b L
5469flag also sets the
5470.b 7
5471flag.
5472.ip m
5473This mailer can send to multiple users
5474on the same host
5475in one transaction.
5476When a
5477.b $u
5478macro occurs in the
5479.i argv
5480part of the mailer definition,
5481that field will be repeated as necessary
5482for all qualifying users.
5483Removing this flag can defeat duplicate supression on a remote site
5484as each recipient is sent in a separate transaction.
5485.ip M\(dg
5486This mailer wants a
5487.q Message-Id:
5488header line.
5489.ip n
5490Do not insert a UNIX-style
5491.q From
5492line on the front of the message.
5493.ip o
5494Always run as the owner of the recipient mailbox.
5495Normally
5496.i sendmail
5497runs as the sender for locally generated mail
5498or as
5499.q daemon
5500(actually, the user specified in the
5501.b u
5502option)
5503when delivering network mail.
5504The normal behavior is required by most local mailers,
5505which will not allow the envelope sender address
5506to be set unless the mailer is running as daemon.
5507This flag is ignored if the
5508.b S
5509flag is set.
5510.ip p
5511Use the route-addr style reverse-path in the SMTP
5512.q "MAIL FROM:"
5513command
5514rather than just the return address;
5515although this is required in RFC 821 section 3.1,
5516many hosts do not process reverse-paths properly.
5517Reverse-paths are officially discouraged by RFC 1123.
5518.ip P\(dg
5519This mailer wants a
5520.q Return-Path:
5521line.
5522.ip q
5523When an address that resolves to this mailer is verified
5524(SMTP VRFY command),
5525generate 250 responses instead of 252 responses.
5526This will imply that the address is local.
5527.ip r
5528Same as
5529.b f ,
5530but sends a
5531.b \-r
5532flag.
5533.ip R
5534Open SMTP connections from a
5535.q secure
5536port.
5537Secure ports aren't
5538(secure, that is)
5539except on UNIX machines,
5540so it is unclear that this adds anything.
5541.i sendmail
5542must be running as root to be able to use this flag.
5543.ip s
5544Strip quote characters (" and \e) off of the address
5545before calling the mailer.
5546.ip S
5547Don't reset the userid
5548before calling the mailer.
5549This would be used in a secure environment
5550where
5551.i sendmail
5552ran as root.
5553This could be used to avoid forged addresses.
5554If the
5555.b U=
5556field is also specified,
5557this flag causes the effective user id to be set to that user.
5558.ip u
5559Upper case should be preserved in user names for this mailer. Standards
5560require preservation of case in the local part of addresses, except for
5561those address for which your system accepts responsibility.
5562RFC 2142 provides a long list of addresses which should be case
5563insensitive.
5564If you use this flag, you may be violating RFC 2142.
5565Note that postmaster is always treated as a case insensitive address
5566regardless of this flag.
5567.ip U
5568This mailer wants UUCP-style
5569.q From
5570lines with the ugly
5571.q "remote from <host>"
5572on the end.
5573.ip w
5574The user must have a valid account on this machine,
5575i.e.,
5576.i getpwnam
5577must succeed.
5578If not, the mail is bounced.
5579See also the
5580.b MailBoxDatabase
5581option.
5582This is required to get
5583.q \&.forward
5584capability.
5585.ip x\(dg
5586This mailer wants a
5587.q Full-Name:
5588header line.
5589.ip X
5590This mailer wants to use the hidden dot algorithm as specified in RFC 821;
5591basically, any line beginning with a dot will have an extra dot prepended
5592(to be stripped at the other end).
5593This insures that lines in the message containing a dot
5594will not terminate the message prematurely.
5595.ip z
5596Run Local Mail Transfer Protocol (LMTP)
5597between
5598.i sendmail
5599and the local mailer.
5600This is a variant on SMTP
5601defined in RFC 2033
5602that is specifically designed for delivery to a local mailbox.
5603.ip Z
5604Apply DialDelay (if set) to this mailer.
5605.ip 0
5606Don't look up MX records for hosts sent via SMTP/LMTP.
5607Do not apply
5608.b FallbackMXhost
5609either.
5610.ip 1
5611Don't send null characters ('\\0') to this mailer.
5612.ip 2
5613Don't use ESMTP even if offered; this is useful for broken
5614systems that offer ESMTP but fail on EHLO (without recovering
5615when HELO is tried next).
5616.ip 3
5617Extend the list of characters converted to =XX notation
5618when converting to Quoted-Printable
5619to include those that don't map cleanly between ASCII and EBCDIC.
5620Useful if you have IBM mainframes on site.
5621.ip 5
5622If no aliases are found for this address,
5623pass the address through ruleset 5 for possible alternate resolution.
5624This is intended to forward the mail to an alternate delivery spot.
5625.ip 6
5626Strip headers to seven bits.
5627.ip 7
5628Strip all output to seven bits.
5629This is the default if the
5630.b L
5631flag is set.
5632Note that clearing this option is not
5633sufficient to get full eight bit data passed through
5634.i sendmail .
5635If the
5636.b 7
5637option is set, this is essentially always set,
5638since the eighth bit was stripped on input.
5639Note that this option will only impact messages
5640that didn't have 8\(->7 bit MIME conversions performed.
5641.ip 8
5642If set,
5643it is acceptable to send eight bit data to this mailer;
5644the usual attempt to do 8\(->7 bit MIME conversions will be bypassed.
5645.ip 9
5646If set,
5647do
5648.i limited
56497\(->8 bit MIME conversions.
5650These conversions are limited to text/plain data.
5651.ip :
5652Check addresses to see if they begin
5653.q :include: ;
5654if they do, convert them to the
5655.q *include*
5656mailer.
5657.ip |
5658Check addresses to see if they begin with a `|';
5659if they do, convert them to the
5660.q prog
5661mailer.
5662.ip /
5663Check addresses to see if they begin with a `/';
5664if they do, convert them to the
5665.q *file*
5666mailer.
5667.ip @
5668Look up addresses in the user database.
5669.ip %
5670Do not attempt delivery on initial recipient of a message
5671or on queue runs
5672unless the queued message is selected
5673using one of the -qI/-qR/-qS queue run modifiers
5674or an ETRN request.
5675.pp
5676Configuration files prior to level 6
5677assume the `A', `w', `5', `:', `|', `/', and `@' options
5678on the mailer named
5679.q local .
5680.pp
5681The mailer with the special name
5682.q error
5683can be used to generate a user error.
5684The (optional) host field is an exit status to be returned,
5685and the user field is a message to be printed.
5686The exit status may be numeric or one of the values
5687USAGE, NOUSER, NOHOST, UNAVAILABLE, SOFTWARE, TEMPFAIL, PROTOCOL, or CONFIG
5688to return the corresponding EX_ exit code,
5689or an enhanced error code as described in RFC 1893,
5690.ul
5691Enhanced Mail System Status Codes.
5692For example, the entry:
5693.(b
5694$#error $@ NOHOST $: Host unknown in this domain
5695.)b
5696on the RHS of a rule
5697will cause the specified error to be generated
5698and the
5699.q "Host unknown"
5700exit status to be returned
5701if the LHS matches.
5702This mailer is only functional in rulesets 0, 5,
5703or one of the check_* rulesets.
5704.pp
5705The mailer with the special name
5706.q discard
5707causes any mail sent to it to be discarded
5708but otherwise treated as though it were successfully delivered.
5709This mailer cannot be used in ruleset 0,
5710only in the various address checking rulesets.
5711.pp
5712The mailer named
5713.q local
5714.i must
5715be defined in every configuration file.
5716This is used to deliver local mail,
5717and is treated specially in several ways.
5718Additionally, three other mailers named
5719.q prog ,
5720.q *file* ,
5721and
5722.q *include*
5723may be defined to tune the delivery of messages to programs,
5724files,
5725and :include: lists respectively.
5726They default to:
5727.(b
5728Mprog, P=/bin/sh, F=lsoDq9, T=DNS/RFC822/X-Unix, A=sh \-c $u
5729M*file*, P=[FILE], F=lsDFMPEouq9, T=DNS/RFC822/X-Unix, A=FILE $u
5730M*include*, P=/dev/null, F=su, A=INCLUDE $u
5731.)b
5732.pp
5733Builtin pathnames are [FILE] and [IPC], the former is used for
5734delivery to files, the latter for delivery via interprocess communication.
5735For mailers that use [IPC] as pathname the argument vector (A=)
5736must start with TCP or FILE for delivery via a TCP or a Unix domain socket.
5737If TCP is used, the second argument must be the name of the host
5738to contact.
5739Optionally a third argument can be used to specify a port,
5740the default is smtp (port 25).
5741If FILE is used, the second argument must be the name of
5742the Unix domain socket.
5743.pp
5744If the argument vector does not contain $u then
5745.i sendmail
5746will speak SMTP (or LMTP if the mailer flag z is specified) to the mailer.
5747.pp
5748If no Eol field is defined, then the default is "\\r\\n" for
5749SMTP mailers and "\\n" of others.
5750.pp
5751The Sender and Recipient rewriting sets
5752may either be a simple ruleset id
5753or may be two ids separated by a slash;
5754if so, the first rewriting set is applied to envelope
5755addresses
5756and the second is applied to headers.
5757Setting any value to zero disables corresponding mailer-specific rewriting.
5758.pp
5759The Directory
5760is actually a colon-separated path of directories to try.
5761For example, the definition
5762.q D=$z:/
5763first tries to execute in the recipient's home directory;
5764if that is not available,
5765it tries to execute in the root of the filesystem.
5766This is intended to be used only on the
5767.q prog
5768mailer,
5769since some shells (such as
5770.i csh )
5771refuse to execute if they cannot read the current directory.
5772Since the queue directory is not normally readable by unprivileged users
5773.i csh
5774scripts as recipients can fail.
5775.pp
5776The Userid
5777specifies the default user and group id to run as,
5778overriding the
5779.b DefaultUser
5780option (q.v.).
5781If the
5782.b S
5783mailer flag is also specified,
5784this user and group will be set as the
5785effective uid and gid for the process.
5786This may be given as
5787.i user:group
5788to set both the user and group id;
5789either may be an integer or a symbolic name to be looked up
5790in the
5791.i passwd
5792and
5793.i group
5794files respectively.
5795If only a symbolic user name is specified,
5796the group id in the
5797.i passwd
5798file for that user is used as the group id.
5799.pp
5800The Charset field
5801is used when converting a message to MIME;
5802this is the character set used in the
5803Content-Type: header.
5804If this is not set, the
5805.b DefaultCharset
5806option is used,
5807and if that is not set, the value
5808.q unknown-8bit
5809is used.
5810.b WARNING:
5811this field applies to the sender's mailer,
5812not the recipient's mailer.
5813For example, if the envelope sender address
5814lists an address on the local network
5815and the recipient is on an external network,
5816the character set will be set from the Charset= field
5817for the local network mailer,
5818not that of the external network mailer.
5819.pp
5820The Type= field
5821sets the type information
5822used in MIME error messages
5823as defined by
5824RFC 1894.
5825It is actually three values separated by slashes:
5826the MTA-type (that is, the description of how hosts are named),
5827the address type (the description of e-mail addresses),
5828and the diagnostic type (the description of error diagnostic codes).
5829Each of these must be a registered value
5830or begin with
5831.q X\- .
5832The default is
5833.q dns/rfc822/smtp .
5834.pp
5835The m= field specifies the maximum number of messages
5836to attempt to deliver on a single SMTP or LMTP connection.
5837The default is infinite.
5838.pp
5839The r= field specifies the maximum number of recipients
5840to attempt to deliver in a single envelope.
5841It defaults to 100.
5842.pp
5843The /= field specifies a new root directory for the mailer. The path is
5844macro expanded and then passed to the
5845.q chroot
5846system call. The root directory is changed before the Directory field is
5847consulted or the uid is changed.
5848.pp
5849The Wait= field specifies the maximum time to wait for the
5850mailer to return after sending all data to it.
5851This applies to mailers that have been forked by
5852.i sendmail .
5853.pp
5854The Queuegroup= field specifies the default queue group in which
5855received mail should be queued.
5856This can be overridden by other means as explained in section
5857``Queue Groups and Queue Directories''.
5858.sh 2 "H \*- Define Header"
5859.pp
5860The format of the header lines that
5861.i sendmail
5862inserts into the message
5863are defined by the
5864.b H
5865line.
5866The syntax of this line is one of the following:
5867.(b F
5868.b H \c
5869.i hname \c
5870.b :
5871.i htemplate
5872.)b
5873.(b F
5874.b H [\c
5875.b ? \c
5876.i mflags \c
5877.b ? \c
5878.b ]\c
5879.i hname \c
5880.b :
5881.i htemplate
5882.)b
5883.(b F
5884.b H [\c
5885.b ?$ \c
5886.i {macro} \c
5887.b ? \c
5888.b ]\c
5889.i hname \c
5890.b :
5891.i htemplate
5892.)b
5893Continuation lines in this spec
5894are reflected directly into the outgoing message.
5895The
5896.i htemplate
5897is macro-expanded before insertion into the message.
5898If the
5899.i mflags
5900(surrounded by question marks)
5901are specified,
5902at least one of the specified flags
5903must be stated in the mailer definition
5904for this header to be automatically output.
5905If a
5906.i ${macro}
5907(surrounded by question marks)
5908is specified,
5909the header will be automatically output
5910if the macro is set.
5911The macro may be set using any of the normal methods,
5912including using the
5913.b macro
5914storage map in a ruleset.
5915If one of these headers is in the input
5916it is reflected to the output
5917regardless of these flags or macros.
5918Notice:
5919If a
5920.i ${macro}
5921is used to set a header, then it is useful to add that macro to class
5922.i $={persistentMacros}
5923which consists of the macros that should be saved across queue runs.
5924.pp
5925Some headers have special semantics
5926that will be described later.
5927.pp
5928A secondary syntax allows validation of headers as they are being read.
5929To enable validation, use:
5930.(b
5931.b H \c
5932.i Header \c
5933.b ": $>" \c
5934.i Ruleset
5935.b H \c
5936.i Header \c
5937.b ": $>+" \c
5938.i Ruleset
5939.)b
5940The indicated
5941.i Ruleset
5942is called for the specified
5943.i Header ,
5944and can return
5945.b $#error
5946to reject the message or
5947.b $#discard
5948to discard the message
5949(as with the other
5950.b check_ *
5951rulesets).
5952The ruleset receives the header field-body as argument,
5953i.e., not the header field-name; see also
5954${hdr_name} and ${currHeader}.
5955The header is treated as a structured field,
5956that is,
5957text in parentheses is deleted before processing,
5958unless the second form
5959.b $>+
5960is used.
5961Note: only one ruleset can be associated with a header;
5962.i sendmail
5963will silently ignore multiple entries.
5964.pp
5965For example, the configuration lines:
5966.(b
5967HMessage-Id: $>CheckMessageId
5968
5969SCheckMessageId
5970R< $+ @ $+ > $@ OK
5971R$* $#error $: Illegal Message-Id header
5972.)b
5973would refuse any message that had a Message-Id: header of any of the
5974following forms:
5975.(b
5976Message-Id: <>
5977Message-Id: some text
5978Message-Id: <legal text@domain> extra crud
5979.)b
5980A default ruleset that is called for headers which don't have a
5981specific ruleset defined for them can be specified by:
5982.(b
5983.b H \c
5984.i * \c
5985.b ": $>" \c
5986.i Ruleset
5987.)b
5988or
5989.(b
5990.b H \c
5991.i * \c
5992.b ": $>+" \c
5993.i Ruleset
5994.)b
5995.sh 2 "O \*- Set Option"
5996.pp
5997There are a number of global options that
5998can be set from a configuration file.
5999Options are represented by full words;
6000some are also representable as single characters for back compatibility.
6001The syntax of this line is:
6002.(b F
6003.b O \0
6004.i option \c
6005.b = \c
6006.i value
6007.)b
6008This sets option
6009.i option
6010to be
6011.i value .
6012Note that there
6013.i must
6014be a space between the letter `O' and the name of the option.
6015An older version is:
6016.(b F
6017.b O \c
6018.i o\|value
6019.)b
6020where the option
6021.i o
6022is a single character.
6023Depending on the option,
6024.i value
6025may be a string, an integer,
6026a boolean
6027(with legal values
6028.q t ,
6029.q T ,
6030.q f ,
6031or
6032.q F ;
6033the default is TRUE),
6034or
6035a time interval.
6036.pp
6037All filenames used in options should be absolute paths,
6038i.e., starting with '/'.
6039Relative filenames most likely cause surprises during operation
6040(unless otherwise noted).
6041.pp
6042The options supported (with the old, one character names in brackets) are:
6043.nr ii 1i
6044.ip "AliasFile=\fIspec, spec, ...\fP"
6045[A]
6046Specify possible alias file(s).
6047Each
6048.i spec
6049should be in the format
6050``\c
6051.i class \c
6052.b :
6053.i info ''
6054where
6055.i class \c
6056.b :
6057is optional and defaults to ``implicit''.
6058Note that
6059.i info
6060is required for all
6061.i class es
6062except
6063.q ldap .
6064For the
6065.q ldap
6066class,
6067if
6068.i info
6069is not specified,
6070a default
6071.i info
6072value is used as follows:
6073.(b
6074\-k (&(objectClass=sendmailMTAAliasObject)
6075 (sendmailMTAAliasName=aliases)
6076 (|(sendmailMTACluster=${sendmailMTACluster})
6077 (sendmailMTAHost=$j))
6078 (sendmailMTAKey=%0))
6079\-v sendmailMTAAliasValue
6080.)b
6081Depending on how
6082.i sendmail
6083is compiled, valid classes are
6084.q implicit
6085(search through a compiled-in list of alias file types,
6086for back compatibility),
6087.q hash
6088(if
6089.sm NEWDB
6090is specified),
6091.q btree
6092(if
6093.sm NEWDB
6094is specified),
6095.q dbm
6096(if
6097.sm NDBM
6098is specified),
6099.q stab
6100(internal symbol table \*- not normally used
6101unless you have no other database lookup),
6102.q sequence
6103(use a sequence of maps
6104previously declared),
6105.q ldap
6106(if
6107.sm LDAPMAP
6108is specified),
6109or
6110.q nis
6111(if
6112.sm NIS
6113is specified).
6114If a list of
6115.i spec s
6116are provided,
6117.i sendmail
6118searches them in order.
6119.ip AliasWait=\fItimeout\fP
6120[a]
6121If set,
6122wait up to
6123.i timeout
6124(units default to minutes)
6125for an
6126.q @:@
6127entry to exist in the alias database
6128before starting up.
6129If it does not appear in the
6130.i timeout
6131interval issue a warning.
6132.ip AllowBogusHELO
6133[no short name]
6134If set, allow HELO SMTP commands that don't include a host name.
6135Setting this violates RFC 1123 section 5.2.5,
6136but is necessary to interoperate with several SMTP clients.
6137If there is a value, it is still checked for legitimacy.
6138.ip AuthMaxBits=\fIN\fP
6139[no short name]
6140Limit the maximum encryption strength for the security layer in
6141SMTP AUTH (SASL). Default is essentially unlimited.
6142This allows to turn off additional encryption in SASL if
6143STARTTLS is already encrypting the communication, because the
6144existing encryption strength is taken into account when choosing
6145an algorithm for the security layer.
6146For example, if STARTTLS is used and the symmetric cipher is 3DES,
6147then the the keylength (in bits) is 168.
6148Hence setting
6149.b AuthMaxBits
6150to 168 will disable any encryption in SASL.
6151.ip AuthMechanisms
6152[no short name]
6153List of authentication mechanisms for AUTH (separated by spaces).
6154The advertised list of authentication mechanisms will be the
6155intersection of this list and the list of available mechanisms as
6156determined by the Cyrus SASL library.
6157If STARTTLS is active, EXTERNAL will be added to this list.
6158In that case, the value of {cert_subject} is used as authentication id.
6159.ip AuthOptions
6160[no short name]
6161List of options for SMTP AUTH consisting of single characters
6162with intervening white space or commas.
6163.(b
6164.ta 4n
6165A Use the AUTH= parameter for the MAIL FROM
6166 command only when authentication succeeded.
6167 This can be used as a workaround for broken
6168 MTAs that do not implement RFC 2554 correctly.
6169a protection from active (non-dictionary) attacks
6170 during authentication exchange.
6171c require mechanisms which pass client credentials,
6172 and allow mechanisms which can pass credentials
6173 to do so.
6174d don't permit mechanisms susceptible to passive
6175 dictionary attack.
6176f require forward secrecy between sessions
6177 (breaking one won't help break next).
6178p don't permit mechanisms susceptible to simple
6179 passive attack (e.g., PLAIN, LOGIN).
6180y don't permit mechanisms that allow anonymous login.
6181.)b
6182The first option applies to sendmail as a client, the others to a server.
6183Example:
6184.(b
6185O AuthOptions=p,y
6186.)b
6187would disallow ANONYMOUS as AUTH mechanism and would
6188allow PLAIN only if a security layer (e.g.,
6189provided by STARTTLS) is already active.
6190The options 'a', 'c', 'd', 'f', 'p', and 'y' refer to properties of the
6191selected SASL mechanisms.
6192Explanations of these properties can be found in the Cyrus SASL documentation.
6193.ip BadRcptThrottle=\fIN\fP
6194[no short name]
6195If set and more than the specified number of recipients in a single SMTP
6196envelope are rejected, sleep for one second after each rejected RCPT command.
6197.ip BlankSub=\fIc\fP
6198[B]
6199Set the blank substitution character to
6200.i c .
6201Unquoted spaces in addresses are replaced by this character.
6202Defaults to space (i.e., no change is made).
6203.ip CACERTPath
6204[no short name]
6205Path to directory with certificates of CAs.
6206This directory directory must contain the hashes of each CA certificate
6207as filenames (or as links to them).
6208.ip CACERTFile
6209[no short name]
6210File containing one or more CA certificates;
6211see section about STARTTLS for more information.
6212.ip CheckAliases
6213[n]
6214Validate the RHS of aliases when rebuilding the alias database.
6215.ip CheckpointInterval=\fIN\fP
6216[C]
6217Checkpoints the queue every
6218.i N
6219(default 10)
6220addresses sent.
6221If your system crashes during delivery to a large list,
6222this prevents retransmission to any but the last
6223.i N
6224recipients.
6225.ip ClassFactor=\fIfact\fP
6226[z]
6227The indicated
6228.i fact or
6229is multiplied by the message class
6230(determined by the Precedence: field in the user header
6231and the
6232.b P
6233lines in the configuration file)
6234and subtracted from the priority.
6235Thus, messages with a higher Priority: will be favored.
6236Defaults to 1800.
6237.ip ClientCertFile
6238[no short name]
6239File containing the certificate of the client, i.e., this certificate
6240is used when
6241.i sendmail
6242acts as client (for STARTTLS).
6243.ip ClientKeyFile
6244[no short name]
6245File containing the private key belonging to the client certificate
6246(for STARTTLS if
6247.i sendmail
6248runs as client).
6249.ip ClientPortOptions=\fIoptions\fP
6250[O]
6251Set client SMTP options.
6252The options are
6253.i key=value
6254pairs separated by commas.
6255Known keys are:
6256.(b
6257.ta 1i
6258Port Name/number of source port for connection (defaults to any free port)
6259Addr Address mask (defaults INADDR_ANY)
6260Family Address family (defaults to INET)
6261SndBufSize Size of TCP send buffer
6262RcvBufSize Size of TCP receive buffer
6263Modifier Options (flags) for the daemon
6264.)b
6265The
6266.i Addr ess
6267mask may be a numeric address in dot notation
6268or a network name.
6269.i Modifier
6270can be the following character:
6271.(b
6272.ta 1i
6273h use name of interface for HELO command
6274A don't use AUTH when sending e-mail
6275S don't use STARTTLS when sending e-mail
6276.)b
6277If ``h'' is set, the name corresponding to the outgoing interface
6278address (whether chosen via the Connection parameter or
6279the default) is used for the HELO/EHLO command.
6280However, the name must not start with a square bracket
6281and it must contain at least one dot.
6282This is a simple test whether the name is not
6283an IP address (in square brackets) but a qualified hostname.
6284Note that multiple ClientPortOptions settings are allowed
6285in order to give settings for each protocol family
6286(e.g., one for Family=inet and one for Family=inet6).
6287A restriction placed on one family only affects
6288outgoing connections on that particular family.
6289.ip ColonOkInAddr
6290[no short name]
6291If set, colons are acceptable in e-mail addresses
6292(e.g.,
6293.q host:user ).
6294If not set, colons indicate the beginning of a RFC 822 group construct
6295(\c
6296.q "groupname: member1, member2, ... memberN;" ).
6297Doubled colons are always acceptable
6298(\c
6299.q nodename::user )
6300and proper route-addr nesting is understood
6301(\c
6302.q <@relay:user@host> ).
6303Furthermore, this option defaults on if the configuration version level
6304is less than 6 (for back compatibility).
6305However, it must be off for full compatibility with RFC 822.
6306.ip ConnectionCacheSize=\fIN\fP
6307[k]
6308The maximum number of open connections that will be cached at a time.
6309The default is one.
6310This delays closing the current connection until
6311either this invocation of
6312.i sendmail
6313needs to connect to another host
6314or it terminates.
6315Setting it to zero defaults to the old behavior,
6316that is, connections are closed immediately.
6317Since this consumes file descriptors,
6318the connection cache should be kept small:
63194 is probably a practical maximum.
6320.ip ConnectionCacheTimeout=\fItimeout\fP
6321[K]
6322The maximum amount of time a cached connection will be permitted to idle
6323without activity.
6324If this time is exceeded,
6325the connection is immediately closed.
6326This value should be small (on the order of ten minutes).
6327Before
6328.i sendmail
6329uses a cached connection,
6330it always sends a RSET command
6331to check the connection;
6332if this fails, it reopens the connection.
6333This keeps your end from failing if the other end times out.
6334The point of this option is to be a good network neighbor
6335and avoid using up excessive resources
6336on the other end.
6337The default is five minutes.
6338.ip ConnectOnlyTo=\fIaddress\fP
6339[no short name]
6340This can be used to
6341override the connection address (for testing purposes).
6342.ip ConnectionRateThrottle=\fIN\fP
6343[no short name]
6344If set to a positive value,
6345allow no more than
6346.i N
6347incoming connections in a one second period per daemon.
6348This is intended to flatten out peaks
6349and allow the load average checking to cut in.
6350Defaults to zero (no limits).
6351.ip ControlSocketName=\fIname\fP
6352[no short name]
6353Name of the control socket for daemon management.
6354A running
6355.i sendmail
6356daemon can be controlled through this named socket.
6357Available commands are:
6358.i help,
6359.i restart,
6360.i shutdown,
6361and
6362.i status.
6363The
6364.i status
6365command returns the current number of daemon children,
6366the maximum number of daemon children,
6367the free disk space (in blocks) of the queue directory,
6368and the load average of the machine expressed as an integer.
6369If not set, no control socket will be available.
6370Solaris and pre-4.4BSD kernel users should see the note in sendmail/README .
6371.ip DHParameters
6372File with DH parameters for STARTTLS.
6373This is only required if a ciphersuite containing DSA/DH is used.
6374This is only for people with a good knowledge of TLS, all others
6375can ignore this option.
6376.ip DaemonPortOptions=\fIoptions\fP
6377[O]
6378Set server SMTP options.
6379Each instance of DaemonPortOptions leads to an additional incoming socket.
6380The options are
6381.i key=value
6382pairs.
6383Known keys are:
6384.(b
6385.ta 1i
6386Name User-definable name for the daemon (defaults to "Daemon#")
6387Port Name/number of listening port (defaults to "smtp")
6388Addr Address mask (defaults INADDR_ANY)
6389Family Address family (defaults to INET)
6390Listen Size of listen queue (defaults to 10)
6391Modifier Options (flags) for the daemon
6392SndBufSize Size of TCP send buffer
6393RcvBufSize Size of TCP receive buffer
6394.)b
6395The
6396.i Name
6397field is used for error messages and logging.
6398The
6399.i Addr ess
6400mask may be a numeric address in dot notation
6401or a network name.
6402The
6403.i Family
6404key defaults to INET (IPv4).
6405IPv6 users who wish to also accept IPv6 connections
6406should add additional Family=inet6 DaemonPortOptions lines.
6407.i Modifier
6408can be a sequence (without any delimiters)
6409of the following characters:
6410.(b
6411.ta 1i
6412a always require authentication
6413b bind to interface through which mail has been received
6414c perform hostname canonification (.cf)
6415f require fully qualified hostname (.cf)
6416u allow unqualified addresses (.cf)
6417A disable AUTH (overrides 'a' modifier)
6418C don't perform hostname canonification
6419E disallow ETRN (see RFC 2476)
6420O optional; if opening the socket fails ignore it
6421S don't offer STARTTLS
6422.)b
6423That is, one way to specify a message submission agent (MSA) that
6424always requires authentication is:
6425.(b
6426O DaemonPortOptions=Name=MSA, Port=587, M=Ea
6427.)b
6428The modifiers that are marked with "(.cf)" have only
6429effect in the standard configuration file, in which
6430they are available via
6431.b ${daemon_flags} .
6432Notice: Do
6433.b not
6434use the ``a'' modifier on a public accessible MTA!
6435It should only be used for a MSA that is accessed by authorized
6436users for initial mail submission.
6437Users must authenticate to use a MSA which has this option turned on.
6438The flags ``c'' and ``C'' can change the default for
6439hostname canonification in the
6440.i sendmail.cf
6441file.
6442See the relevant documentation for
6443.sm FEATURE(nocanonify) .
6444The modifier ``f'' disallows addresses of the form
6445.b user@host
6446unless they are submitted directly.
6447The flag ``u'' allows unqualified sender addresses,
6448i.e., those without @host.
6449``b'' forces sendmail to bind to the interface
6450through which the e-mail has been
6451received for the outgoing connection.
6452.b WARNING:
6453Use ``b''
6454only if outgoing mail can be routed through the incoming connection's
6455interface to its destination. No attempt is made to catch problems due to a
6456misconfiguration of this parameter, use it only for virtual hosting
6457where each virtual interface can connect to every possible location.
6458This will also override possible settings via
6459.b ClientPortOptions.
6460Note,
6461.i sendmail
6462will listen on a new socket
6463for each occurence of the DaemonPortOptions option
6464in a configuration file.
6465The modifier ``O'' causes sendmail to ignore a socket
6466if it can't be opened.
6467This applies to failures from the socket(2) and bind(2) calls.
6468.ip DefaultAuthInfo
6469[no short name]
6470Filename that contains default authentication information for outgoing
6471connections. This file must contain the user id, the authorization id,
6472the password (plain text), the realm and the list of mechanisms to use
6473on separate lines and must be readable by
6474root (or the trusted user) only.
6475If no realm is specified,
6476.b $j
6477is used.
6478If no mechanisms are specified, the list given by
6479.b AuthMechanisms
6480is used.
6481Notice: this option is deprecated and will be removed in future versions.
6482Moreover, it doesn't work for the MSP since it can't read the file
6483(the file must not be group/world-readable otherwise
6484.i sendmail
6485will complain).
6486Use the authinfo ruleset instead which provides more control over
6487the usage of the data anyway.
6488.ip DefaultCharSet=\fIcharset\fP
6489[no short name]
6490When a message that has 8-bit characters but is not in MIME format
6491is converted to MIME
6492(see the EightBitMode option)
6493a character set must be included in the Content-Type: header.
6494This character set is normally set from the Charset= field
6495of the mailer descriptor.
6496If that is not set, the value of this option is used.
6497If this option is not set, the value
6498.q unknown-8bit
6499is used.
6500.ip DataFileBufferSize=\fIthreshold\fP
6501[no short name]
6502Set the
6503.i threshold ,
6504in bytes,
6505before a memory-based
6506queue data file
6507becomes disk-based.
6508The default is 4096 bytes.
6509.ip DeadLetterDrop=\fIfile\fP
6510[no short name]
6511Defines the location of the system-wide dead.letter file,
6512formerly hardcoded to /usr/tmp/dead.letter.
6513If this option is not set (the default),
6514sendmail will not attempt to save to a system-wide dead.letter file
6515in the event
6516it cannot bounce the mail to the user or postmaster.
6517Instead, it will rename the qf file
6518as it has in the past
6519when the dead.letter file could not be opened.
6520.ip DefaultUser=\fIuser:group\fP
6521[u]
6522Set the default userid for mailers to
6523.i user:group .
6524If
6525.i group
6526is omitted and
6527.i user
6528is a user name
6529(as opposed to a numeric user id)
6530the default group listed in the /etc/passwd file for that user is used
6531as the default group.
6532Both
6533.i user
6534and
6535.i group
6536may be numeric.
6537Mailers without the
6538.i S
6539flag in the mailer definition
6540will run as this user.
6541Defaults to 1:1.
6542The value can also be given as a symbolic user name.\**
6543.(f
6544\**The old
6545.b g
6546option has been combined into the
6547.b DefaultUser
6548option.
6549.)f
6550.ip DelayLA=\fILA\fP
6551[no short name]
6552When the system load average exceeds
6553.i LA ,
6554.i sendmail
6555will sleep for one second on most SMTP commands and
6556before accepting connections.
6557.ip DeliverByMin=\fItime\fP
6558[0]
6559Set minimum time for Deliver By SMTP Service Extension (RFC 2852).
6560If 0, no time is listed, if less than 0, the extension is not offered,
6561if greater than 0, it is listed as minimum time
6562for the EHLO keyword DELIVERBY.
6563.ip DeliveryMode=\fIx\fP
6564[d]
6565Deliver in mode
6566.i x .
6567Legal modes are:
6568.(b
6569.ta 4n
6570i Deliver interactively (synchronously)
6571b Deliver in background (asynchronously)
6572q Just queue the message (deliver during queue run)
6573d Defer delivery and all map lookups (deliver during queue run)
6574.)b
6575Defaults to ``b'' if no option is specified,
6576``i'' if it is specified but given no argument
6577(i.e., ``Od'' is equivalent to ``Odi'').
6578The
6579.b \-v
6580command line flag sets this to
6581.b i .
6582.ip DialDelay=\fIsleeptime\fP
6583[no short name]
6584Dial-on-demand network connections can see timeouts
6585if a connection is opened before the call is set up.
6586If this is set to an interval and a connection times out
6587on the first connection being attempted
6588.i sendmail
6589will sleep for this amount of time and try again.
6590This should give your system time to establish the connection
6591to your service provider.
6592Units default to seconds, so
6593.q DialDelay=5
6594uses a five second delay.
6595Defaults to zero
6596(no retry).
6597This delay only applies to mailers which have the
6598Z flag set.
6599.ip DirectSubmissionModifiers=\fImodifiers\fP
6600Defines
6601.b ${daemon_flags}
6602for direct (command line) submissions.
6603If not set,
6604.b ${daemon_flags}
6605is either "CC f" if the option
6606.b \-G
6607is used or "c u" otherwise.
6608Note that only the the "CC", "c", "f", and "u" flags are checked.
6609.ip DontBlameSendmail=\fIoption,option,...\fP
6610[no short name]
6611In order to avoid possible cracking attempts
6612caused by world- and group-writable files and directories,
6613.i sendmail
6614does paranoid checking when opening most of its support files.
6615If for some reason you absolutely must run with,
6616for example,
6617a group-writable
6618.i /etc
6619directory,
6620then you will have to turn off this checking
6621(at the cost of making your system more vulnerable to attack).
6622The possible arguments have been described earlier.
6623The details of these flags are described above.
6624.\"XXX should have more here!!! XXX
6625.b "Use of this option is not recommended."
6626.ip DontExpandCnames
6627[no short name]
6628The standards say that all host addresses used in a mail message
6629must be fully canonical.
6630For example, if your host is named
6631.q Cruft.Foo.ORG
6632and also has an alias of
6633.q FTP.Foo.ORG ,
6634the former name must be used at all times.
6635This is enforced during host name canonification
6636($[ ... $] lookups).
6637If this option is set, the protocols are ignored and the
6638.q wrong
6639thing is done.
6640However, the IETF is moving toward changing this standard,
6641so the behavior may become acceptable.
6642Please note that hosts downstream may still rewrite the address
6643to be the true canonical name however.
6644.ip DontInitGroups
6645[no short name]
6646If set,
6647.i sendmail
6648will avoid using the initgroups(3) call.
6649If you are running NIS,
6650this causes a sequential scan of the groups.byname map,
6651which can cause your NIS server to be badly overloaded in a large domain.
6652The cost of this is that the only group found for users
6653will be their primary group (the one in the password file),
6654which will make file access permissions somewhat more restrictive.
6655Has no effect on systems that don't have group lists.
6656.ip DontProbeInterfaces
6657[no short name]
6658.i Sendmail
6659normally finds the names of all interfaces active on your machine
6660when it starts up
6661and adds their name to the
6662.b $=w
6663class of known host aliases.
6664If you have a large number of virtual interfaces
6665or if your DNS inverse lookups are slow
6666this can be time consuming.
6667This option turns off that probing.
6668However, you will need to be certain to include all variant names
6669in the
6670.b $=w
6671class by some other mechanism.
6672If set to
6673.b loopback ,
6674loopback interfaces (e.g., lo0) will not be probed.
6675.ip DontPruneRoutes
6676[R]
6677Normally,
6678.i sendmail
6679tries to eliminate any unnecessary explicit routes
6680when sending an error message
6681(as discussed in RFC 1123 \(sc 5.2.6).
6682For example,
6683when sending an error message to
6684.(b
6685<@known1,@known2,@known3:user@unknown>
6686.)b
6687.i sendmail
6688will strip off the
6689.q @known1,@known2
6690in order to make the route as direct as possible.
6691However, if the
6692.b R
6693option is set, this will be disabled,
6694and the mail will be sent to the first address in the route,
6695even if later addresses are known.
6696This may be useful if you are caught behind a firewall.
6697.ip DoubleBounceAddress=\fIerror-address\fP
6698[no short name]
6699If an error occurs when sending an error message,
6700send the error report
6701(termed a
6702.q "double bounce"
6703because it is an error
6704.q bounce
6705that occurs when trying to send another error
6706.q bounce )
6707to the indicated address.
6708The address is macro expanded
6709at the time of delivery.
6710If not set, defaults to
6711.q postmaster .
6712If set to an empty string, double bounces are dropped.
6713.ip EightBitMode=\fIaction\fP
6714[8]
6715Set handling of eight-bit data.
6716There are two kinds of eight-bit data:
6717that declared as such using the
6718.b BODY=8BITMIME
6719ESMTP declaration or the
6720.b \-B8BITMIME
6721command line flag,
6722and undeclared 8-bit data, that is,
6723input that just happens to be eight bits.
6724There are three basic operations that can happen:
6725undeclared 8-bit data can be automatically converted to 8BITMIME,
6726undeclared 8-bit data can be passed as-is without conversion to MIME
6727(``just send 8''),
6728and declared 8-bit data can be converted to 7-bits
6729for transmission to a non-8BITMIME mailer.
6730The possible
6731.i action s
6732are:
6733.(b
6734.\" r Reject undeclared 8-bit data;
6735.\" don't convert 8BITMIME\(->7BIT (``reject'')
6736 s Reject undeclared 8-bit data (``strict'')
6737.\" do convert 8BITMIME\(->7BIT (``strict'')
6738.\" c Convert undeclared 8-bit data to MIME;
6739.\" don't convert 8BITMIME\(->7BIT (``convert'')
6740 m Convert undeclared 8-bit data to MIME (``mime'')
6741.\" do convert 8BITMIME\(->7BIT (``mime'')
6742.\" j Pass undeclared 8-bit data;
6743.\" don't convert 8BITMIME\(->7BIT (``just send 8'')
6744 p Pass undeclared 8-bit data (``pass'')
6745.\" do convert 8BITMIME\(->7BIT (``pass'')
6746.\" a Adaptive algorithm: see below
6747.)b
6748.\"The adaptive algorithm is to accept 8-bit data,
6749.\"converting it to 8BITMIME only if the receiver understands that,
6750.\"otherwise just passing it as undeclared 8-bit data;
6751.\"8BITMIME\(->7BIT conversions are done.
6752In all cases properly declared 8BITMIME data will be converted to 7BIT
6753as needed.
6754.ip ErrorHeader=\fIfile-or-message\fP
6755[E]
6756Prepend error messages with the indicated message.
6757If it begins with a slash,
6758it is assumed to be the pathname of a file
6759containing a message (this is the recommended setting).
6760Otherwise, it is a literal message.
6761The error file might contain the name, email address, and/or phone number
6762of a local postmaster who could provide assistance
6763to end users.
6764If the option is missing or null,
6765or if it names a file which does not exist or which is not readable,
6766no message is printed.
6767.ip ErrorMode=\fIx\fP
6768[e]
6769Dispose of errors using mode
6770.i x .
6771The values for
6772.i x
6773are:
6774.(b
6775p Print error messages (default)
6776q No messages, just give exit status
6777m Mail back errors
6778w Write back errors (mail if user not logged in)
|
6772e Mail back errors and give zero exit stat always
| 6779e Mail back errors (when applicable) and give zero exit stat always
|
6773.)b
| 6780.)b
|
| 6781Note that the last mode,
6782.q e ,
6783is for Berknet error processing and
6784should not be used in normal circumstances.
|
6774.ip FallbackMXhost=\fIfallbackhost\fP
6775[V]
6776If specified, the
6777.i fallbackhost
6778acts like a very low priority MX
6779on every host.
6780MX records will be looked up for this host,
6781unless the name is surrounded by square brackets.
6782This is intended to be used by sites with poor network connectivity.
6783Messages which are undeliverable due to temporary address failures
6784(e.g., DNS failure)
6785also go to the FallbackMXhost.
6786.ip FastSplit
6787[no short name]
6788If set to a value greater than zero (the default is one),
6789it suppresses the MX lookups on addresses
6790when they are initially sorted, i.e., for the first delivery attempt.
6791This usually results in faster envelope splitting unless the MX records
6792are readily available in a local DNS cache.
6793To enforce initial sorting based on MX records set
6794.b FastSplit
6795to zero.
6796If the mail is submitted directly from the command line, then
6797the value also limits the number of processes to deliver the envelopes;
6798if more envelopes are created they are only queued up
6799and must be taken care of by a queue run.
6800Since the default submission method is via SMTP (either from a MUA
6801or via the MSP), the value of
6802.b FastSplit
6803is seldom used to limit the number of processes to deliver the envelopes.
6804.ip ForkEachJob
6805[Y]
6806If set,
6807deliver each job that is run from the queue in a separate process.
6808.ip ForwardPath=\fIpath\fP
6809[J]
6810Set the path for searching for users' .forward files.
6811The default is
6812.q $z/.forward .
6813Some sites that use the automounter may prefer to change this to
6814.q /var/forward/$u
6815to search a file with the same name as the user in a system directory.
6816It can also be set to a sequence of paths separated by colons;
6817.i sendmail
6818stops at the first file it can successfully and safely open.
6819For example,
6820.q /var/forward/$u:$z/.forward
6821will search first in /var/forward/\c
6822.i username
6823and then in
6824.i ~username /.forward
6825(but only if the first file does not exist).
6826.ip HelpFile=\fIfile\fP
6827[H]
6828Specify the help file
6829for SMTP.
6830If no file name is specified, "helpfile" is used.
6831.ip HoldExpensive
6832[c]
6833If an outgoing mailer is marked as being expensive,
6834don't connect immediately.
6835This requires that queueing be compiled in,
6836since it will depend on a queue run process to
6837actually send the mail.
6838.ip HostsFile=\fIpath\fP
6839[no short name]
6840The path to the hosts database,
6841normally
6842.q /etc/hosts .
6843This option is only consulted when sendmail
6844is canonifying addresses,
6845and then only when
6846.q files
6847is in the
6848.q hosts
6849service switch entry.
6850In particular, this file is
6851.i never
6852used when looking up host addresses;
6853that is under the control of the system
6854.i gethostbyname (3)
6855routine.
6856.ip HostStatusDirectory=\fIpath\fP
6857[no short name]
6858The location of the long term host status information.
6859When set,
6860information about the status of hosts
6861(e.g., host down or not accepting connections)
6862will be shared between all
6863.i sendmail
6864processes;
6865normally, this information is only held within a single queue run.
6866This option requires a connection cache of at least 1 to function.
6867If the option begins with a leading `/',
6868it is an absolute pathname;
6869otherwise,
6870it is relative to the mail queue directory.
6871A suggested value for sites desiring persistent host status is
6872.q \&.hoststat
6873(i.e., a subdirectory of the queue directory).
6874.ip IgnoreDots
6875[i]
6876Ignore dots in incoming messages.
6877This is always disabled (that is, dots are always accepted)
6878when reading SMTP mail.
6879.ip InputMailFilters=\fIname,name,...\fP
6880A comma separated list of filters which determines which filters
6881(see the "X \*- Mail Filter (Milter) Definitions" section)
6882and the invocation sequence are contacted for incoming SMTP messages.
6883If none are set, no filters will be contacted.
6884.ip LDAPDefaultSpec=\fIspec\fP
6885[no short name]
6886Sets a default map specification for LDAP maps.
6887The value should only contain LDAP specific settings
6888such as
6889.q "-h host -p port -d bindDN" .
6890The settings will be used for all LDAP maps
6891unless the individual map specification overrides a setting.
6892This option should be set before any LDAP maps are defined.
6893.ip LogLevel=\fIn\fP
6894[L]
6895Set the log level to
6896.i n .
6897Defaults to 9.
6898.ip M\fIx\|value\fP
6899[no long version]
6900Set the macro
6901.i x
6902to
6903.i value .
6904This is intended only for use from the command line.
6905The
6906.b \-M
6907flag is preferred.
6908.ip MailboxDatabase
6909[no short name]
6910Type of lookup to find information about local mailboxes,
6911defaults to ``pw'' which uses
6912.i getpwnam .
6913Other types can be introduced by adding them to the source code,
6914see libsm/mbdb.c for details.
6915.ip UseMSP
6916[no short name]
6917Use as mail submission program, i.e.,
6918allow group writable queue files
6919if the group is the same as that of a set-group-ID sendmail binary.
6920See the file
6921.b sendmail/SECURITY
6922in the distribution tarball.
6923.ip MatchGECOS
6924[G]
6925Allow fuzzy matching on the GECOS field.
6926If this flag is set,
6927and the usual user name lookups fail
6928(that is, there is no alias with this name and a
6929.i getpwnam
6930fails),
6931sequentially search the password file
6932for a matching entry in the GECOS field.
6933This also requires that MATCHGECOS
6934be turned on during compilation.
6935This option is not recommended.
6936.ip MaxAliasRecursion=\fIN\fP
6937[no short name]
6938The maximum depth of alias recursion (default: 10).
6939.ip MaxDaemonChildren=\fIN\fP
6940[no short name]
6941If set,
6942.i sendmail
6943will refuse connections when it has more than
6944.i N
6945children processing incoming mail or automatic queue runs.
6946This does not limit the number of outgoing connections.
6947If not set, there is no limit to the number of children --
6948that is, the system load averaging controls this.
6949.ip MaxHeadersLength=\fIN\fP
6950[no short name]
6951The maximum length of the sum of all headers.
6952This can be used to prevent a denial of service attack.
6953The default is no limit.
6954.ip MaxHopCount=\fIN\fP
6955[h]
6956The maximum hop count.
6957Messages that have been processed more than
6958.i N
6959times are assumed to be in a loop and are rejected.
6960Defaults to 25.
6961.ip MaxMessageSize=\fIN\fP
6962[no short name]
6963Specify the maximum message size
6964to be advertised in the ESMTP EHLO response.
6965Messages larger than this will be rejected.
6966.ip MaxMimeHeaderLength=\fIN[/M]\fP
6967[no short name]
6968Sets the maximum length of certain MIME header field values to
6969.i N
6970characters.
6971These MIME header fields are determined by being a member of
6972class {checkMIMETextHeaders}, which currently contains only
6973the header Content-Description.
6974For some of these headers which take parameters,
6975the maximum length of each parameter is set to
6976.i M
6977if specified. If
6978.i /M
6979is not specified, one half of
6980.i N
6981will be used.
6982By default,
6983these values are 0, meaning no checks are done.
6984.ip MaxQueueChildren=\fIN\fP
6985[no short name]
6986When set, this limits the number of concurrent queue runner processes to
6987.i N.
6988This helps to control the amount of system resources used when processing
6989the queue. When there are multiple queue groups defined and the total number
6990of queue runners for these queue groups would exceed
6991.i MaxQueueChildren
6992then the queue groups will not all run concurrently. That is, some portion
6993of the queue groups will run concurrently such that
6994.i MaxQueueChildren
6995will not be exceeded, while the remaining queue groups will be run later (in
6996round robin order). See also
6997.i MaxRunnersPerQueue
6998and the section \fBQueue Group Declaration\fP.
| 6785.ip FallbackMXhost=\fIfallbackhost\fP
6786[V]
6787If specified, the
6788.i fallbackhost
6789acts like a very low priority MX
6790on every host.
6791MX records will be looked up for this host,
6792unless the name is surrounded by square brackets.
6793This is intended to be used by sites with poor network connectivity.
6794Messages which are undeliverable due to temporary address failures
6795(e.g., DNS failure)
6796also go to the FallbackMXhost.
6797.ip FastSplit
6798[no short name]
6799If set to a value greater than zero (the default is one),
6800it suppresses the MX lookups on addresses
6801when they are initially sorted, i.e., for the first delivery attempt.
6802This usually results in faster envelope splitting unless the MX records
6803are readily available in a local DNS cache.
6804To enforce initial sorting based on MX records set
6805.b FastSplit
6806to zero.
6807If the mail is submitted directly from the command line, then
6808the value also limits the number of processes to deliver the envelopes;
6809if more envelopes are created they are only queued up
6810and must be taken care of by a queue run.
6811Since the default submission method is via SMTP (either from a MUA
6812or via the MSP), the value of
6813.b FastSplit
6814is seldom used to limit the number of processes to deliver the envelopes.
6815.ip ForkEachJob
6816[Y]
6817If set,
6818deliver each job that is run from the queue in a separate process.
6819.ip ForwardPath=\fIpath\fP
6820[J]
6821Set the path for searching for users' .forward files.
6822The default is
6823.q $z/.forward .
6824Some sites that use the automounter may prefer to change this to
6825.q /var/forward/$u
6826to search a file with the same name as the user in a system directory.
6827It can also be set to a sequence of paths separated by colons;
6828.i sendmail
6829stops at the first file it can successfully and safely open.
6830For example,
6831.q /var/forward/$u:$z/.forward
6832will search first in /var/forward/\c
6833.i username
6834and then in
6835.i ~username /.forward
6836(but only if the first file does not exist).
6837.ip HelpFile=\fIfile\fP
6838[H]
6839Specify the help file
6840for SMTP.
6841If no file name is specified, "helpfile" is used.
6842.ip HoldExpensive
6843[c]
6844If an outgoing mailer is marked as being expensive,
6845don't connect immediately.
6846This requires that queueing be compiled in,
6847since it will depend on a queue run process to
6848actually send the mail.
6849.ip HostsFile=\fIpath\fP
6850[no short name]
6851The path to the hosts database,
6852normally
6853.q /etc/hosts .
6854This option is only consulted when sendmail
6855is canonifying addresses,
6856and then only when
6857.q files
6858is in the
6859.q hosts
6860service switch entry.
6861In particular, this file is
6862.i never
6863used when looking up host addresses;
6864that is under the control of the system
6865.i gethostbyname (3)
6866routine.
6867.ip HostStatusDirectory=\fIpath\fP
6868[no short name]
6869The location of the long term host status information.
6870When set,
6871information about the status of hosts
6872(e.g., host down or not accepting connections)
6873will be shared between all
6874.i sendmail
6875processes;
6876normally, this information is only held within a single queue run.
6877This option requires a connection cache of at least 1 to function.
6878If the option begins with a leading `/',
6879it is an absolute pathname;
6880otherwise,
6881it is relative to the mail queue directory.
6882A suggested value for sites desiring persistent host status is
6883.q \&.hoststat
6884(i.e., a subdirectory of the queue directory).
6885.ip IgnoreDots
6886[i]
6887Ignore dots in incoming messages.
6888This is always disabled (that is, dots are always accepted)
6889when reading SMTP mail.
6890.ip InputMailFilters=\fIname,name,...\fP
6891A comma separated list of filters which determines which filters
6892(see the "X \*- Mail Filter (Milter) Definitions" section)
6893and the invocation sequence are contacted for incoming SMTP messages.
6894If none are set, no filters will be contacted.
6895.ip LDAPDefaultSpec=\fIspec\fP
6896[no short name]
6897Sets a default map specification for LDAP maps.
6898The value should only contain LDAP specific settings
6899such as
6900.q "-h host -p port -d bindDN" .
6901The settings will be used for all LDAP maps
6902unless the individual map specification overrides a setting.
6903This option should be set before any LDAP maps are defined.
6904.ip LogLevel=\fIn\fP
6905[L]
6906Set the log level to
6907.i n .
6908Defaults to 9.
6909.ip M\fIx\|value\fP
6910[no long version]
6911Set the macro
6912.i x
6913to
6914.i value .
6915This is intended only for use from the command line.
6916The
6917.b \-M
6918flag is preferred.
6919.ip MailboxDatabase
6920[no short name]
6921Type of lookup to find information about local mailboxes,
6922defaults to ``pw'' which uses
6923.i getpwnam .
6924Other types can be introduced by adding them to the source code,
6925see libsm/mbdb.c for details.
6926.ip UseMSP
6927[no short name]
6928Use as mail submission program, i.e.,
6929allow group writable queue files
6930if the group is the same as that of a set-group-ID sendmail binary.
6931See the file
6932.b sendmail/SECURITY
6933in the distribution tarball.
6934.ip MatchGECOS
6935[G]
6936Allow fuzzy matching on the GECOS field.
6937If this flag is set,
6938and the usual user name lookups fail
6939(that is, there is no alias with this name and a
6940.i getpwnam
6941fails),
6942sequentially search the password file
6943for a matching entry in the GECOS field.
6944This also requires that MATCHGECOS
6945be turned on during compilation.
6946This option is not recommended.
6947.ip MaxAliasRecursion=\fIN\fP
6948[no short name]
6949The maximum depth of alias recursion (default: 10).
6950.ip MaxDaemonChildren=\fIN\fP
6951[no short name]
6952If set,
6953.i sendmail
6954will refuse connections when it has more than
6955.i N
6956children processing incoming mail or automatic queue runs.
6957This does not limit the number of outgoing connections.
6958If not set, there is no limit to the number of children --
6959that is, the system load averaging controls this.
6960.ip MaxHeadersLength=\fIN\fP
6961[no short name]
6962The maximum length of the sum of all headers.
6963This can be used to prevent a denial of service attack.
6964The default is no limit.
6965.ip MaxHopCount=\fIN\fP
6966[h]
6967The maximum hop count.
6968Messages that have been processed more than
6969.i N
6970times are assumed to be in a loop and are rejected.
6971Defaults to 25.
6972.ip MaxMessageSize=\fIN\fP
6973[no short name]
6974Specify the maximum message size
6975to be advertised in the ESMTP EHLO response.
6976Messages larger than this will be rejected.
6977.ip MaxMimeHeaderLength=\fIN[/M]\fP
6978[no short name]
6979Sets the maximum length of certain MIME header field values to
6980.i N
6981characters.
6982These MIME header fields are determined by being a member of
6983class {checkMIMETextHeaders}, which currently contains only
6984the header Content-Description.
6985For some of these headers which take parameters,
6986the maximum length of each parameter is set to
6987.i M
6988if specified. If
6989.i /M
6990is not specified, one half of
6991.i N
6992will be used.
6993By default,
6994these values are 0, meaning no checks are done.
6995.ip MaxQueueChildren=\fIN\fP
6996[no short name]
6997When set, this limits the number of concurrent queue runner processes to
6998.i N.
6999This helps to control the amount of system resources used when processing
7000the queue. When there are multiple queue groups defined and the total number
7001of queue runners for these queue groups would exceed
7002.i MaxQueueChildren
7003then the queue groups will not all run concurrently. That is, some portion
7004of the queue groups will run concurrently such that
7005.i MaxQueueChildren
7006will not be exceeded, while the remaining queue groups will be run later (in
7007round robin order). See also
7008.i MaxRunnersPerQueue
7009and the section \fBQueue Group Declaration\fP.
|
| 7010Notice:
7011.i sendmail
7012does not count individual queue runners, but only sets of processes
7013that act on a workgroup.
7014Hence the actual number of queue runners may be lower than the limit
7015imposed by
7016.i MaxQueueChildren .
7017This discrepancy can be large if some queue runners have to wait
7018for a slow server and if short intervals are used.
|
6999.ip MaxQueueRunSize=\fIN\fP
7000[no short name]
7001The maximum number of jobs that will be processed
7002in a single queue run.
7003If not set, there is no limit on the size.
7004If you have very large queues or a very short queue run interval
7005this could be unstable.
7006However, since the first
7007.i N
7008jobs in queue directory order are run (rather than the
7009.i N
7010highest priority jobs)
7011this should be set as high as possible to avoid
7012.q losing
7013jobs that happen to fall late in the queue directory.
7014.ip MaxRecipientsPerMessage=\fIN\fP
7015[no short name]
7016The maximum number of recipients that will be accepted per message
7017in an SMTP transaction.
7018Note: setting this too low can interfere with sending mail from
7019MUAs that use SMTP for initial submission.
7020If not set, there is no limit on the number of recipients per envelope.
7021.ip MaxRunnersPerQueue=\fIN\fP
7022[no short name]
7023This sets the default maximum number of queue runners for queue groups.
7024Up to
7025.i N
7026queue runners will work in parallel on a queue group's messages.
7027This is useful where the processing of a message in the queue might
7028delay the processing of subsequent messages. Such a delay may be the result
7029of non-erroneous situations such as a low bandwidth connection.
7030May be overridden on a per queue group basis by setting the
7031.i Runners
7032option; see the section \fBQueue Group Declaration\fP.
7033The default is 1 when not set.
7034.ip MeToo
7035[m]
7036Send to me too,
7037even if I am in an alias expansion.
7038This option is deprecated
7039and will be removed from a future version.
7040.ip Milter
7041[no short name]
7042This option has several sub(sub)options.
7043The names of the suboptions are separated by dots.
7044At the first level the following options are available:
7045.(b
7046.ta \w'LogLevel'u+3n
7047LogLevel Log level for input mail filter actions, defaults to LogLevel.
7048macros Specifies list of macro to transmit to filters.
7049 See list below.
7050.)b
7051The ``macros'' option has the following suboptions
7052which specify the list of macro to transmit to milters
7053after a certain event occurred.
7054.(b
7055.ta \w'envfrom'u+3n
7056connect After session connection start
7057helo After HELO command
7058envfrom After MAIL FROM command
7059envrcpt After RCPT TO command
7060.)b
7061By default the lists of macros are empty.
7062Example:
7063.(b
7064O Milter.LogLevel=12
7065O Milter.macros.connect=j, _, {daemon_name}
7066.)b
7067.ip MinFreeBlocks=\fIN\fP
7068[b]
7069Insist on at least
7070.i N
7071blocks free on the filesystem that holds the queue files
7072before accepting email via SMTP.
7073If there is insufficient space
7074.i sendmail
7075gives a 452 response
7076to the MAIL command.
7077This invites the sender to try again later.
7078.ip MinQueueAge=\fIage\fP
7079[no short name]
7080Don't process any queued jobs
7081that have been in the queue less than the indicated time interval.
7082This is intended to allow you to get responsiveness
7083by processing the queue fairly frequently
7084without thrashing your system by trying jobs too often.
7085The default units are minutes.
7086.ip MustQuoteChars=\fIs\fP
7087[no short name]
7088Sets the list of characters that must be quoted if used in a full name
7089that is in the phrase part of a ``phrase <address>'' syntax.
7090The default is ``\'.''.
7091The characters ``@,;:\e()[]'' are always added to this list.
7092.ip NiceQueueRun
7093[no short name]
7094The priority of queue runners (nice(3)).
7095This value must be greater or equal zero.
7096.ip NoRecipientAction
7097[no short name]
7098The action to take when you receive a message that has no valid
7099recipient headers (To:, Cc:, Bcc:, or Apparently-To: \(em
7100the last included for back compatibility with old
7101.i sendmail s).
7102It can be
7103.b None
7104to pass the message on unmodified,
7105which violates the protocol,
7106.b Add-To
7107to add a To: header with any recipients it can find in the envelope
7108(which might expose Bcc: recipients),
7109.b Add-Apparently-To
7110to add an Apparently-To: header
7111(this is only for back-compatibility
7112and is officially deprecated),
7113.b Add-To-Undisclosed
7114to add a header
7115.q "To: undisclosed-recipients:;"
7116to make the header legal without disclosing anything,
7117or
7118.b Add-Bcc
7119to add an empty Bcc: header.
7120.ip OldStyleHeaders
7121[o]
7122Assume that the headers may be in old format,
7123i.e.,
7124spaces delimit names.
7125This actually turns on
7126an adaptive algorithm:
7127if any recipient address contains a comma, parenthesis,
7128or angle bracket,
7129it will be assumed that commas already exist.
7130If this flag is not on,
7131only commas delimit names.
7132Headers are always output with commas between the names.
7133Defaults to off.
7134.ip OperatorChars=\fIcharlist\fP
7135[$o macro]
7136The list of characters that are considered to be
7137.q operators ,
7138that is, characters that delimit tokens.
7139All operator characters are tokens by themselves;
7140sequences of non-operator characters are also tokens.
7141White space characters separate tokens
7142but are not tokens themselves \(em for example,
7143.q AAA.BBB
7144has three tokens, but
7145.q "AAA BBB"
7146has two.
7147If not set, OperatorChars defaults to
7148.q \&.\|:\|@\|[\|] ;
7149additionally, the characters
7150.q (\|)\|<\|>\|,\|;
7151are always operators.
7152Note that OperatorChars must be set in the
7153configuration file before any rulesets.
7154.ip PidFile=\fIfilename\fP
7155[no short name]
7156Filename of the pid file.
7157(default is _PATH_SENDMAILPID).
7158The
7159.i filename
7160is macro-expanded before it is opened.
7161.ip PostmasterCopy=\fIpostmaster\fP
7162[P]
7163If set,
7164copies of error messages will be sent to the named
7165.i postmaster .
7166Only the header of the failed message is sent.
7167Errors resulting from messages with a negative precedence will not be sent.
7168Since most errors are user problems,
7169this is probably not a good idea on large sites,
7170and arguably contains all sorts of privacy violations,
7171but it seems to be popular with certain operating systems vendors.
7172The address is macro expanded
7173at the time of delivery.
7174Defaults to no postmaster copies.
7175.ip PrivacyOptions=\fI\|opt,opt,...\fP
7176[p]
7177Set the privacy
7178.i opt ions.
7179``Privacy'' is really a misnomer;
7180many of these are just a way of insisting on stricter adherence
7181to the SMTP protocol.
7182The
7183.i opt ions
7184can be selected from:
7185.(b
7186.ta \w'needvrfyhelo'u+3n
7187public Allow open access
7188needmailhelo Insist on HELO or EHLO command before MAIL
7189needexpnhelo Insist on HELO or EHLO command before EXPN
7190noexpn Disallow EXPN entirely, implies noverb.
7191needvrfyhelo Insist on HELO or EHLO command before VRFY
7192novrfy Disallow VRFY entirely
7193noetrn Disallow ETRN entirely
7194noverb Disallow VERB entirely
7195restrictmailq Restrict mailq command
7196restrictqrun Restrict \-q command line flag
7197restrictexpand Restrict \-bv and \-v command line flags
7198noreceipts Don't return success DSNs\**
7199nobodyreturn Don't return the body of a message with DSNs
7200goaway Disallow essentially all SMTP status queries
7201authwarnings Put X-Authentication-Warning: headers in messages
7202 and log warnings
7203.)b
7204.(f
7205\**N.B.:
7206the
7207.b noreceipts
7208flag turns off support for RFC 1891
7209(Delivery Status Notification).
7210.)f
7211The
7212.q goaway
7213pseudo-flag sets all flags except
7214.q noreceipts ,
7215.q restrictmailq ,
7216.q restrictqrun ,
7217.q restrictexpand ,
7218.q noetrn ,
7219and
7220.q nobodyreturn .
7221If mailq is restricted,
7222only people in the same group as the queue directory
7223can print the queue.
7224If queue runs are restricted,
7225only root and the owner of the queue directory
7226can run the queue.
7227The
7228.q restrictexpand
7229pseudo-flag instructs
7230.i sendmail
7231to drop privileges when the
7232.b \-bv
7233option is given by users who are neither root nor the TrustedUser
7234so users cannot read private aliases, forwards, or :include: files.
7235It will add the
7236.q NonRootSafeAddr
7237to the
7238.q DontBlameSendmail
7239option to prevent misleading unsafe address warnings.
7240It also overrides the
7241.b \-v
7242(verbose) command line option to prevent information leakage.
7243Authentication Warnings add warnings about various conditions
7244that may indicate attempts to spoof the mail system,
7245such as using a non-standard queue directory.
7246.ip ProcessTitlePrefix=\fIstring\fP
7247[no short name]
7248Prefix the process title shown on 'ps' listings with
7249.i string .
7250The
7251.i string
7252will be macro processed.
7253.ip QueueDirectory=\fIdir\fP
7254[Q]
7255The QueueDirectory option serves two purposes.
7256First, it specifies the directory or set of directories that comprise
7257the default queue group.
7258Second, it specifies the directory D which is the ancestor of all queue
7259directories, and which sendmail uses as its current working directory.
7260When sendmail dumps core, it leaves its core files in D.
7261There are two cases.
7262If \fIdir\fR ends with an asterisk (eg, \fI/var/spool/mqueue/qd*\fR),
7263then all of the directories or symbolic links to directories
7264beginning with `qd' in
7265.i /var/spool/mqueue
7266will be used as queue directories of the default queue group,
7267and
7268.i /var/spool/mqueue
7269will be used as the working directory D.
7270Otherwise,
7271\fIdir\fR must name a directory (usually \fI/var/spool/mqueue\fR):
7272the default queue group consists of the single queue directory \fIdir\fR,
7273and the working directory D is set to \fIdir\fR.
7274To define additional groups of queue directories,
7275use the configuration file `Q' command.
7276Do not change the queue directory structure
7277while sendmail is running.
7278.ip QueueFactor=\fIfactor\fP
7279[q]
7280Use
7281.i factor
7282as the multiplier in the map function
7283to decide when to just queue up jobs rather than run them.
7284This value is divided by the difference between the current load average
7285and the load average limit
7286(\c
7287.b QueueLA
7288option)
7289to determine the maximum message priority
7290that will be sent.
7291Defaults to 600000.
7292.ip QueueLA=\fILA\fP
7293[x]
7294When the system load average exceeds
7295.i LA
7296and the
7297.b QueueFactor
7298(\c
7299.b q )
7300option divided by the difference in the current load average and the
7301.b QueueLA
7302option plus one
| 7019.ip MaxQueueRunSize=\fIN\fP
7020[no short name]
7021The maximum number of jobs that will be processed
7022in a single queue run.
7023If not set, there is no limit on the size.
7024If you have very large queues or a very short queue run interval
7025this could be unstable.
7026However, since the first
7027.i N
7028jobs in queue directory order are run (rather than the
7029.i N
7030highest priority jobs)
7031this should be set as high as possible to avoid
7032.q losing
7033jobs that happen to fall late in the queue directory.
7034.ip MaxRecipientsPerMessage=\fIN\fP
7035[no short name]
7036The maximum number of recipients that will be accepted per message
7037in an SMTP transaction.
7038Note: setting this too low can interfere with sending mail from
7039MUAs that use SMTP for initial submission.
7040If not set, there is no limit on the number of recipients per envelope.
7041.ip MaxRunnersPerQueue=\fIN\fP
7042[no short name]
7043This sets the default maximum number of queue runners for queue groups.
7044Up to
7045.i N
7046queue runners will work in parallel on a queue group's messages.
7047This is useful where the processing of a message in the queue might
7048delay the processing of subsequent messages. Such a delay may be the result
7049of non-erroneous situations such as a low bandwidth connection.
7050May be overridden on a per queue group basis by setting the
7051.i Runners
7052option; see the section \fBQueue Group Declaration\fP.
7053The default is 1 when not set.
7054.ip MeToo
7055[m]
7056Send to me too,
7057even if I am in an alias expansion.
7058This option is deprecated
7059and will be removed from a future version.
7060.ip Milter
7061[no short name]
7062This option has several sub(sub)options.
7063The names of the suboptions are separated by dots.
7064At the first level the following options are available:
7065.(b
7066.ta \w'LogLevel'u+3n
7067LogLevel Log level for input mail filter actions, defaults to LogLevel.
7068macros Specifies list of macro to transmit to filters.
7069 See list below.
7070.)b
7071The ``macros'' option has the following suboptions
7072which specify the list of macro to transmit to milters
7073after a certain event occurred.
7074.(b
7075.ta \w'envfrom'u+3n
7076connect After session connection start
7077helo After HELO command
7078envfrom After MAIL FROM command
7079envrcpt After RCPT TO command
7080.)b
7081By default the lists of macros are empty.
7082Example:
7083.(b
7084O Milter.LogLevel=12
7085O Milter.macros.connect=j, _, {daemon_name}
7086.)b
7087.ip MinFreeBlocks=\fIN\fP
7088[b]
7089Insist on at least
7090.i N
7091blocks free on the filesystem that holds the queue files
7092before accepting email via SMTP.
7093If there is insufficient space
7094.i sendmail
7095gives a 452 response
7096to the MAIL command.
7097This invites the sender to try again later.
7098.ip MinQueueAge=\fIage\fP
7099[no short name]
7100Don't process any queued jobs
7101that have been in the queue less than the indicated time interval.
7102This is intended to allow you to get responsiveness
7103by processing the queue fairly frequently
7104without thrashing your system by trying jobs too often.
7105The default units are minutes.
7106.ip MustQuoteChars=\fIs\fP
7107[no short name]
7108Sets the list of characters that must be quoted if used in a full name
7109that is in the phrase part of a ``phrase <address>'' syntax.
7110The default is ``\'.''.
7111The characters ``@,;:\e()[]'' are always added to this list.
7112.ip NiceQueueRun
7113[no short name]
7114The priority of queue runners (nice(3)).
7115This value must be greater or equal zero.
7116.ip NoRecipientAction
7117[no short name]
7118The action to take when you receive a message that has no valid
7119recipient headers (To:, Cc:, Bcc:, or Apparently-To: \(em
7120the last included for back compatibility with old
7121.i sendmail s).
7122It can be
7123.b None
7124to pass the message on unmodified,
7125which violates the protocol,
7126.b Add-To
7127to add a To: header with any recipients it can find in the envelope
7128(which might expose Bcc: recipients),
7129.b Add-Apparently-To
7130to add an Apparently-To: header
7131(this is only for back-compatibility
7132and is officially deprecated),
7133.b Add-To-Undisclosed
7134to add a header
7135.q "To: undisclosed-recipients:;"
7136to make the header legal without disclosing anything,
7137or
7138.b Add-Bcc
7139to add an empty Bcc: header.
7140.ip OldStyleHeaders
7141[o]
7142Assume that the headers may be in old format,
7143i.e.,
7144spaces delimit names.
7145This actually turns on
7146an adaptive algorithm:
7147if any recipient address contains a comma, parenthesis,
7148or angle bracket,
7149it will be assumed that commas already exist.
7150If this flag is not on,
7151only commas delimit names.
7152Headers are always output with commas between the names.
7153Defaults to off.
7154.ip OperatorChars=\fIcharlist\fP
7155[$o macro]
7156The list of characters that are considered to be
7157.q operators ,
7158that is, characters that delimit tokens.
7159All operator characters are tokens by themselves;
7160sequences of non-operator characters are also tokens.
7161White space characters separate tokens
7162but are not tokens themselves \(em for example,
7163.q AAA.BBB
7164has three tokens, but
7165.q "AAA BBB"
7166has two.
7167If not set, OperatorChars defaults to
7168.q \&.\|:\|@\|[\|] ;
7169additionally, the characters
7170.q (\|)\|<\|>\|,\|;
7171are always operators.
7172Note that OperatorChars must be set in the
7173configuration file before any rulesets.
7174.ip PidFile=\fIfilename\fP
7175[no short name]
7176Filename of the pid file.
7177(default is _PATH_SENDMAILPID).
7178The
7179.i filename
7180is macro-expanded before it is opened.
7181.ip PostmasterCopy=\fIpostmaster\fP
7182[P]
7183If set,
7184copies of error messages will be sent to the named
7185.i postmaster .
7186Only the header of the failed message is sent.
7187Errors resulting from messages with a negative precedence will not be sent.
7188Since most errors are user problems,
7189this is probably not a good idea on large sites,
7190and arguably contains all sorts of privacy violations,
7191but it seems to be popular with certain operating systems vendors.
7192The address is macro expanded
7193at the time of delivery.
7194Defaults to no postmaster copies.
7195.ip PrivacyOptions=\fI\|opt,opt,...\fP
7196[p]
7197Set the privacy
7198.i opt ions.
7199``Privacy'' is really a misnomer;
7200many of these are just a way of insisting on stricter adherence
7201to the SMTP protocol.
7202The
7203.i opt ions
7204can be selected from:
7205.(b
7206.ta \w'needvrfyhelo'u+3n
7207public Allow open access
7208needmailhelo Insist on HELO or EHLO command before MAIL
7209needexpnhelo Insist on HELO or EHLO command before EXPN
7210noexpn Disallow EXPN entirely, implies noverb.
7211needvrfyhelo Insist on HELO or EHLO command before VRFY
7212novrfy Disallow VRFY entirely
7213noetrn Disallow ETRN entirely
7214noverb Disallow VERB entirely
7215restrictmailq Restrict mailq command
7216restrictqrun Restrict \-q command line flag
7217restrictexpand Restrict \-bv and \-v command line flags
7218noreceipts Don't return success DSNs\**
7219nobodyreturn Don't return the body of a message with DSNs
7220goaway Disallow essentially all SMTP status queries
7221authwarnings Put X-Authentication-Warning: headers in messages
7222 and log warnings
7223.)b
7224.(f
7225\**N.B.:
7226the
7227.b noreceipts
7228flag turns off support for RFC 1891
7229(Delivery Status Notification).
7230.)f
7231The
7232.q goaway
7233pseudo-flag sets all flags except
7234.q noreceipts ,
7235.q restrictmailq ,
7236.q restrictqrun ,
7237.q restrictexpand ,
7238.q noetrn ,
7239and
7240.q nobodyreturn .
7241If mailq is restricted,
7242only people in the same group as the queue directory
7243can print the queue.
7244If queue runs are restricted,
7245only root and the owner of the queue directory
7246can run the queue.
7247The
7248.q restrictexpand
7249pseudo-flag instructs
7250.i sendmail
7251to drop privileges when the
7252.b \-bv
7253option is given by users who are neither root nor the TrustedUser
7254so users cannot read private aliases, forwards, or :include: files.
7255It will add the
7256.q NonRootSafeAddr
7257to the
7258.q DontBlameSendmail
7259option to prevent misleading unsafe address warnings.
7260It also overrides the
7261.b \-v
7262(verbose) command line option to prevent information leakage.
7263Authentication Warnings add warnings about various conditions
7264that may indicate attempts to spoof the mail system,
7265such as using a non-standard queue directory.
7266.ip ProcessTitlePrefix=\fIstring\fP
7267[no short name]
7268Prefix the process title shown on 'ps' listings with
7269.i string .
7270The
7271.i string
7272will be macro processed.
7273.ip QueueDirectory=\fIdir\fP
7274[Q]
7275The QueueDirectory option serves two purposes.
7276First, it specifies the directory or set of directories that comprise
7277the default queue group.
7278Second, it specifies the directory D which is the ancestor of all queue
7279directories, and which sendmail uses as its current working directory.
7280When sendmail dumps core, it leaves its core files in D.
7281There are two cases.
7282If \fIdir\fR ends with an asterisk (eg, \fI/var/spool/mqueue/qd*\fR),
7283then all of the directories or symbolic links to directories
7284beginning with `qd' in
7285.i /var/spool/mqueue
7286will be used as queue directories of the default queue group,
7287and
7288.i /var/spool/mqueue
7289will be used as the working directory D.
7290Otherwise,
7291\fIdir\fR must name a directory (usually \fI/var/spool/mqueue\fR):
7292the default queue group consists of the single queue directory \fIdir\fR,
7293and the working directory D is set to \fIdir\fR.
7294To define additional groups of queue directories,
7295use the configuration file `Q' command.
7296Do not change the queue directory structure
7297while sendmail is running.
7298.ip QueueFactor=\fIfactor\fP
7299[q]
7300Use
7301.i factor
7302as the multiplier in the map function
7303to decide when to just queue up jobs rather than run them.
7304This value is divided by the difference between the current load average
7305and the load average limit
7306(\c
7307.b QueueLA
7308option)
7309to determine the maximum message priority
7310that will be sent.
7311Defaults to 600000.
7312.ip QueueLA=\fILA\fP
7313[x]
7314When the system load average exceeds
7315.i LA
7316and the
7317.b QueueFactor
7318(\c
7319.b q )
7320option divided by the difference in the current load average and the
7321.b QueueLA
7322option plus one
|
7303is less than the priority of the message,
| 7323is less than the priority of the message,
|
7304just queue messages
7305(i.e., don't try to send them).
7306Defaults to 8 multiplied by
7307the number of processors online on the system
7308(if that can be determined).
7309.ip QueueFileMode=\fImode\fP
7310[no short name]
7311Default permissions for queue files (octal).
7312If not set, sendmail uses 0600 unless its real
7313and effective uid are different in which case it uses 0644.
7314.ip QueueSortOrder=\fIalgorithm\fP
7315[no short name]
7316Sets the
7317.i algorithm
7318used for sorting the queue.
7319Only the first character of the value is used.
7320Legal values are
7321.q host
7322(to order by the name of the first host name of the first recipient),
7323.q filename
7324(to order by the name of the queue file name),
7325.q time
7326(to order by the submission/creation time),
7327.q random
7328(to order randomly),
7329.q modification
7330(to order by the modification time of the qf file (older entries first)),
7331and
7332.q priority
7333(to order by message priority).
7334Host ordering makes better use of the connection cache,
7335but may tend to process low priority messages
7336that go to a single host
7337over high priority messages that go to several hosts;
7338it probably shouldn't be used on slow network links.
7339Filename and modification time ordering saves the overhead of
7340reading all of the queued items
7341before starting the queue run.
7342Creation (submission) time ordering is almost always a bad idea,
7343since it allows large, bulk mail to go out
7344before smaller, personal mail,
7345but may have applicability on some hosts with very fast connections.
7346Random is useful if several queue runners are started by hand
7347which try to drain the same queue since odds are they will be working
7348on different parts of the queue at the same time.
7349Priority ordering is the default.
7350.ip QueueTimeout=\fItimeout\fP
7351[T]
7352A synonym for
7353.q Timeout.queuereturn .
7354Use that form instead of the
7355.q QueueTimeout
7356form.
7357.ip RandFile
7358[no short name]
7359Name of file containing random data or the name of the UNIX socket
7360if EGD is used.
7361A (required) prefix "egd:" or "file:" specifies the type.
7362STARTTLS requires this filename if the compile flag HASURANDOMDEV is not set
7363(see sendmail/README).
7364.ip ResolverOptions=\fIoptions\fP
7365[I]
7366Set resolver options.
7367Values can be set using
7368.b + \c
7369.i flag
7370and cleared using
7371.b \- \c
7372.i flag ;
7373the
7374.i flag s
7375can be
7376.q debug ,
7377.q aaonly ,
7378.q usevc ,
7379.q primary ,
7380.q igntc ,
7381.q recurse ,
7382.q defnames ,
7383.q stayopen ,
7384.q use_inet6 ,
7385or
7386.q dnsrch .
7387The string
7388.q HasWildcardMX
7389(without a
7390.b +
7391or
7392.b \- )
7393can be specified to turn off matching against MX records
7394when doing name canonifications.
7395The string
7396.q WorkAroundBrokenAAAA
7397(without a
7398.b +
7399or
7400.b \- )
7401can be specified to work around some broken nameservers
7402which return SERVFAIL (a temporary failure) on T_AAAA (IPv6) lookups.
7403Notice: it might be necessary to apply the same (or similar) options to
7404.i submit.cf
7405too.
7406.ip RrtImpliesDsn
7407[R]
7408If this option is set, a
7409.q Return-Receipt-To:
7410header causes the request of a DSN, which is sent to
7411the envelope sender as required by RFC 1891,
7412not to the address given in the header.
7413.ip RunAsUser=\fIuser\fP
7414[no short name]
7415The
7416.i user
7417parameter may be a user name
7418(looked up in
7419.i /etc/passwd )
7420or a numeric user id;
7421either form can have
7422.q ":group"
7423attached
7424(where group can be numeric or symbolic).
7425If set to a non-zero (non-root) value,
7426.i sendmail
7427will change to this user id shortly after startup\**.
7428.(f
7429\**When running as a daemon,
7430it changes to this user after accepting a connection
7431but before reading any
7432.sm SMTP
7433commands.
7434.)f
7435This avoids a certain class of security problems.
7436However, this means that all
7437.q \&.forward
7438and
7439.q :include:
7440files must be readable by the indicated
7441.i user
7442and all files to be written must be writable by
7443.i user
7444Also, all file and program deliveries will be marked unsafe
7445unless the option
7446.b DontBlameSendmail=NonRootSafeAddr
7447is set,
7448in which case the delivery will be done as
7449.i user .
7450It is also incompatible with the
7451.b SafeFileEnvironment
7452option.
7453In other words, it may not actually add much to security on an average system,
7454and may in fact detract from security
7455(because other file permissions must be loosened).
7456However, it should be useful on firewalls and other
7457places where users don't have accounts and the aliases file is
7458well constrained.
7459.ip RecipientFactor=\fIfact\fP
7460[y]
7461The indicated
7462.i fact or
7463is added to the priority (thus
7464.i lowering
7465the priority of the job)
7466for each recipient,
7467i.e., this value penalizes jobs with large numbers of recipients.
7468Defaults to 30000.
7469.ip RefuseLA=\fILA\fP
7470[X]
7471When the system load average exceeds
7472.i LA ,
7473refuse incoming SMTP connections.
7474Defaults to 12 multiplied by
7475the number of processors online on the system
7476(if that can be determined).
7477.ip RetryFactor=\fIfact\fP
7478[Z]
7479The
7480.i fact or
7481is added to the priority
7482every time a job is processed.
7483Thus,
7484each time a job is processed,
7485its priority will be decreased by the indicated value.
7486In most environments this should be positive,
7487since hosts that are down are all too often down for a long time.
7488Defaults to 90000.
7489.ip SafeFileEnvironment=\fIdir\fP
7490[no short name]
7491If this option is set,
7492.i sendmail
7493will do a
7494.i chroot (2)
7495call into the indicated
7496.i dir ectory
7497before doing any file writes.
7498If the file name specified by the user begins with
7499.i dir ,
7500that partial path name will be stripped off before writing,
7501so (for example)
7502if the SafeFileEnvironment variable is set to
7503.q /safe
7504then aliases of
7505.q /safe/logs/file
7506and
7507.q /logs/file
7508actually indicate the same file.
7509Additionally, if this option is set,
7510.i sendmail
7511refuses to deliver to symbolic links.
7512.ip SaveFromLine
7513[f]
7514Save
7515UNIX-style
7516.q From
7517lines at the front of headers.
7518Normally they are assumed redundant
7519and discarded.
7520.ip SharedMemoryKey
7521[no short name]
7522Key to use for shared memory segment;
7523if not set (or 0), shared memory will not be used.
7524Requires support for shared memory to be compiled into
7525.i sendmail .
7526If this option is set,
7527.i sendmail
7528can share some data between different instances.
7529For example, the number of entries in a queue directory
7530or the available space in a file system.
7531This allows for more efficient program execution, since only
7532one process needs to update the data instead of each individual
7533process gathering the data each time it is required.
7534.ip SendMimeErrors
7535[j]
7536If set, send error messages in MIME format
7537(see RFC 2045 and RFC 1344 for details).
7538If disabled,
7539.i sendmail
7540will not return the DSN keyword in response to an EHLO
7541and will not do Delivery Status Notification processing as described in
7542RFC 1891.
7543.ip ServerCertFile
7544[no short name]
7545File containing the certificate of the server, i.e., this certificate
7546is used when sendmail acts as server
7547(used for STARTTLS).
7548.ip ServerKeyFile
7549[no short name]
7550File containing the private key belonging to the server certificate
7551(used for STARTTLS).
7552.ip ServiceSwitchFile=\fIfilename\fP
7553[no short name]
7554If your host operating system has a service switch abstraction
7555(e.g., /etc/nsswitch.conf on Solaris
7556or /etc/svc.conf on Ultrix and DEC OSF/1)
7557that service will be consulted and this option is ignored.
7558Otherwise, this is the name of a file
7559that provides the list of methods used to implement particular services.
7560The syntax is a series of lines,
7561each of which is a sequence of words.
7562The first word is the service name,
7563and following words are service types.
7564The services that
7565.i sendmail
7566consults directly are
7567.q aliases
7568and
7569.q hosts.
7570Service types can be
7571.q dns ,
7572.q nis ,
7573.q nisplus ,
7574or
7575.q files
7576(with the caveat that the appropriate support
7577must be compiled in
7578before the service can be referenced).
7579If ServiceSwitchFile is not specified, it defaults to
7580/etc/mail/service.switch.
7581If that file does not exist, the default switch is:
7582.(b
7583aliases files
7584hosts dns nis files
7585.)b
7586The default file is
7587.q /etc/mail/service.switch .
7588.ip SevenBitInput
7589[7]
7590Strip input to seven bits for compatibility with old systems.
7591This shouldn't be necessary.
7592.ip SingleLineFromHeader
7593[no short name]
7594If set, From: lines that have embedded newlines are unwrapped
7595onto one line.
7596This is to get around a botch in Lotus Notes
7597that apparently cannot understand legally wrapped RFC 822 headers.
7598.ip SingleThreadDelivery
7599[no short name]
7600If set, a client machine will never try to open two SMTP connections
7601to a single server machine at the same time,
7602even in different processes.
7603That is, if another
7604.i sendmail
7605is already talking to some host a new
7606.i sendmail
7607will not open another connection.
7608This property is of mixed value;
7609although this reduces the load on the other machine,
7610it can cause mail to be delayed
7611(for example, if one
7612.i sendmail
7613is delivering a huge message, other
7614.i sendmail s
7615won't be able to send even small messages).
7616Also, it requires another file descriptor
7617(for the lock file)
7618per connection, so you may have to reduce the
7619.b ConnectionCacheSize
7620option to avoid running out of per-process file descriptors.
7621Requires the
7622.b HostStatusDirectory
7623option.
7624.ip SmtpGreetingMessage=\fImessage\fP
7625[$e macro]
7626The message printed when the SMTP server starts up.
7627Defaults to
7628.q "$j Sendmail $v ready at $b".
7629.ip StatusFile=\fIfile\fP
7630[S]
7631Log summary statistics in the named
7632.i file .
7633If no file name is specified, "statistics" is used.
7634If not set,
7635no summary statistics are saved.
7636This file does not grow in size.
7637It can be printed using the
7638.i mailstats (8)
7639program.
7640.ip SuperSafe
7641[s]
7642This option can be set to True, False, or Interactive.
7643If set to True,
7644.i sendmail
7645will be super-safe when running things,
7646i.e., always instantiate the queue file,
7647even if you are going to attempt immediate delivery.
7648.i Sendmail
7649always instantiates the queue file
7650before returning control to the client
7651under any circumstances.
7652This should really
7653.i always
7654be set to True.
7655The Interactive value has been introduced in 8.12 and can
7656be used together with
7657.b DeliveryMode=i .
7658It skips some synchronization calls which are effectively
7659doubled in the code execution path for this mode.
7660.ip TLSSrvOptions
7661[no short name]
7662List of options for SMTP STARTTLS for the server
7663consisting of single characters
7664with intervening white space or commas.
7665The flag ``V'' disables client verification, and hence
7666it is not possible to use a client certificate for relaying.
7667Currently there are no other flags available.
7668.ip TempFileMode=\fImode\fP
7669[F]
7670The file mode for transcript files, files to which
7671.i sendmail
7672delivers directly, files in the
7673.b HostStatusDirectory ,
7674and
7675.b StatusFile .
7676It is interpreted in octal by default.
7677Defaults to 0600.
7678.ip Timeout.\fItype\fP=\|\fItimeout\fP
7679[r; subsumes old T option as well]
7680Set timeout values.
7681For more information,
7682see section
7683.\" XREF
76844.1.
7685.ip TimeZoneSpec=\fItzinfo\fP
7686[t]
7687Set the local time zone info to
7688.i tzinfo
7689\*- for example,
7690.q PST8PDT .
7691Actually, if this is not set,
7692the TZ environment variable is cleared (so the system default is used);
7693if set but null, the user's TZ variable is used,
7694and if set and non-null the TZ variable is set to this value.
7695.ip TrustedUser=\fIuser\fP
7696[no short name]
7697The
7698.i user
7699parameter may be a user name
7700(looked up in
7701.i /etc/passwd )
7702or a numeric user id.
7703Trusted user for file ownership and starting the daemon. If set, generated
7704alias databases and the control socket (if configured) will automatically
7705be owned by this user.
7706.ip TryNullMXList
7707[w]
7708If this system is the
7709.q best
7710(that is, lowest preference)
7711MX for a given host,
7712its configuration rules should normally detect this situation
7713and treat that condition specially
7714by forwarding the mail to a UUCP feed,
7715treating it as local,
7716or whatever.
7717However, in some cases (such as Internet firewalls)
7718you may want to try to connect directly to that host
7719as though it had no MX records at all.
7720Setting this option causes
7721.i sendmail
7722to try this.
7723The downside is that errors in your configuration
7724are likely to be diagnosed as
7725.q "host unknown"
7726or
7727.q "message timed out"
7728instead of something more meaningful.
7729This option is disrecommended.
7730.ip UnixFromLine=\fIfromline\fP
7731[$l macro]
7732Defines the format used when
7733.i sendmail
7734must add a UNIX-style From_ line
7735(that is, a line beginning
7736.q From<space>user ).
7737Defaults to
7738.q "From $g $d" .
7739Don't change this unless your system uses a different UNIX mailbox format
7740(very unlikely).
7741.ip UnsafeGroupWrites
7742[no short name]
7743If set (default),
7744:include: and .forward files that are group writable are considered
7745.q unsafe ,
7746that is,
7747they cannot reference programs or write directly to files.
7748World writable :include: and .forward files
7749are always unsafe.
7750Note: use
7751.b DontBlameSendmail
7752instead; this option is deprecated.
7753.ip UseErrorsTo
7754[l]
7755If there is an
7756.q Errors-To:
7757header, send error messages to the addresses listed there.
7758They normally go to the envelope sender.
7759Use of this option causes
7760.i sendmail
7761to violate RFC 1123.
7762This option is disrecommended and deprecated.
7763.ip UserDatabaseSpec=\fIudbspec\fP
7764[U]
7765The user database specification.
7766.ip Verbose
7767[v]
7768Run in verbose mode.
7769If this is set,
7770.i sendmail
7771adjusts options
7772.b HoldExpensive
7773(old
7774.b c )
7775and
7776.b DeliveryMode
7777(old
7778.b d )
7779so that all mail is delivered completely
7780in a single job
7781so that you can see the entire delivery process.
7782Option
7783.b Verbose
7784should
7785.i never
7786be set in the configuration file;
7787it is intended for command line use only.
7788.ip XscriptFileBufferSize=\fIthreshold\fP
7789[no short name]
7790Set the
7791.i threshold ,
7792in bytes,
7793before a memory-based
7794queue transcript file
7795becomes disk-based.
7796The default is 4096 bytes.
7797.lp
7798All options can be specified on the command line using the
7799\-O or \-o flag,
7800but most will cause
7801.i sendmail
7802to relinquish its set-user-ID permissions.
7803The options that will not cause this are
7804SevenBitInput [7],
7805EightBitMode [8],
7806MinFreeBlocks [b],
7807CheckpointInterval [C],
7808DeliveryMode [d],
7809ErrorMode [e],
7810IgnoreDots [i],
7811SendMimeErrors [j],
7812LogLevel [L],
7813MeToo [m],
7814OldStyleHeaders [o],
7815PrivacyOptions [p],
7816SuperSafe [s],
7817Verbose [v],
7818QueueSortOrder,
7819MinQueueAge,
7820DefaultCharSet,
7821Dial Delay,
7822NoRecipientAction,
7823ColonOkInAddr,
7824MaxQueueRunSize,
7825SingleLineFromHeader,
7826and
7827AllowBogusHELO.
7828Actually, PrivacyOptions [p] given on the command line
7829are added to those already specified in the
7830.i sendmail.cf
7831file, i.e., they can't be reset.
7832Also, M (define macro) when defining the r or s macros
7833is also considered
7834.q safe .
7835.sh 2 "P \*- Precedence Definitions"
7836.pp
7837Values for the
7838.q "Precedence:"
7839field may be defined using the
7840.b P
7841control line.
7842The syntax of this field is:
7843.(b
7844\fBP\fP\fIname\fP\fB=\fP\fInum\fP
7845.)b
7846When the
7847.i name
7848is found in a
7849.q Precedence:
7850field,
7851the message class is set to
7852.i num .
7853Higher numbers mean higher precedence.
7854Numbers less than zero
7855have the special property
7856that if an error occurs during processing
7857the body of the message will not be returned;
7858this is expected to be used for
7859.q "bulk"
7860mail such as through mailing lists.
7861The default precedence is zero.
7862For example,
7863our list of precedences is:
7864.(b
7865Pfirst-class=0
7866Pspecial-delivery=100
7867Plist=\-30
7868Pbulk=\-60
7869Pjunk=\-100
7870.)b
7871People writing mailing list exploders
7872are encouraged to use
7873.q "Precedence: list" .
7874Older versions of
7875.i sendmail
7876(which discarded all error returns for negative precedences)
7877didn't recognize this name, giving it a default precedence of zero.
7878This allows list maintainers to see error returns
7879on both old and new versions of
7880.i sendmail .
7881.sh 2 "V \*- Configuration Version Level"
7882.pp
7883To provide compatibility with old configuration files,
7884the
7885.b V
7886line has been added to define some very basic semantics
7887of the configuration file.
7888These are not intended to be long term supports;
7889rather, they describe compatibility features
7890which will probably be removed in future releases.
7891.pp
7892.b N.B.:
7893these version
7894.i levels
7895have nothing
7896to do with the version
7897.i number
7898on the files.
7899For example,
7900as of this writing
7901version 10 config files
7902(specifically, 8.10)
7903used version level 9 configurations.
7904.pp
7905.q Old
7906configuration files are defined as version level one.
7907Version level two files make the following changes:
7908.np
7909Host name canonification ($[ ... $])
7910appends a dot if the name is recognized;
7911this gives the config file a way of finding out if anything matched.
7912(Actually, this just initializes the
7913.q host
7914map with the
7915.q \-a.
7916flag \*- you can reset it to anything you prefer
7917by declaring the map explicitly.)
7918.np
7919Default host name extension is consistent throughout processing;
7920version level one configurations turned off domain extension
7921(that is, adding the local domain name)
7922during certain points in processing.
7923Version level two configurations are expected to include a trailing dot
7924to indicate that the name is already canonical.
7925.np
7926Local names that are not aliases
7927are passed through a new distinguished ruleset five;
7928this can be used to append a local relay.
7929This behavior can be prevented by resolving the local name
7930with an initial `@'.
7931That is, something that resolves to a local mailer and a user name of
7932.q vikki
7933will be passed through ruleset five,
7934but a user name of
7935.q @vikki
7936will have the `@' stripped,
7937will not be passed through ruleset five,
7938but will otherwise be treated the same as the prior example.
7939The expectation is that this might be used to implement a policy
7940where mail sent to
7941.q vikki
7942was handled by a central hub,
7943but mail sent to
7944.q vikki@localhost
7945was delivered directly.
7946.pp
7947Version level three files
7948allow # initiated comments on all lines.
7949Exceptions are backslash escaped # marks
7950and the $# syntax.
7951.pp
7952Version level four configurations
7953are completely equivalent to level three
7954for historical reasons.
7955.pp
7956Version level five configuration files
7957change the default definition of
7958.b $w
7959to be just the first component of the hostname.
7960.pp
7961Version level six configuration files
7962change many of the local processing options
7963(such as aliasing and matching the beginning of the address for
7964`|' characters)
7965to be mailer flags;
7966this allows fine-grained control over the special local processing.
7967Level six configuration files may also use long option names.
7968The
7969.b ColonOkInAddr
7970option (to allow colons in the local-part of addresses)
7971defaults
7972.b on
7973for lower numbered configuration files;
7974the configuration file requires some additional intelligence
7975to properly handle the RFC 822 group construct.
7976.pp
7977Version level seven configuration files
7978used new option names to replace old macros
7979(\c
7980.b $e
7981became
7982.b SmtpGreetingMessage ,
7983.b $l
7984became
7985.b UnixFromLine ,
7986and
7987.b $o
7988became
7989.b OperatorChars .
7990Also, prior to version seven,
7991the
7992.b F=q
7993flag (use 250 instead of 252 return value for
7994.sm "SMTP VRFY"
7995commands)
7996was assumed.
7997.pp
7998Version level eight configuration files allow
7999.b $#
8000on the left hand side of ruleset lines.
8001.pp
8002Version level nine configuration files allow
8003parentheses in rulesets, i.e. they are not treated
8004as comments and hence removed.
8005.pp
8006Version level ten configuration files allow
8007queue group definitions.
8008.pp
8009The
8010.b V
8011line may have an optional
8012.b / \c
8013.i vendor
8014to indicate that this configuration file uses modifications
8015specific to a particular vendor\**.
8016.(f
8017\**And of course, vendors are encouraged to add themselves
8018to the list of recognized vendors by editing the routine
8019.i setvendor
8020in
8021.i conf.c .
8022Please send e-mail to sendmail@Sendmail.ORG
8023to register your vendor dialect.
8024.)f
8025You may use
8026.q /Berkeley
8027to emphasize that this configuration file
8028uses the Berkeley dialect of
8029.i sendmail .
8030.sh 2 "K \*- Key File Declaration"
8031.pp
8032Special maps can be defined using the line:
8033.(b
8034Kmapname mapclass arguments
8035.)b
8036The
8037.i mapname
8038is the handle by which this map is referenced in the rewriting rules.
8039The
8040.i mapclass
8041is the name of a type of map;
8042these are compiled in to
8043.i sendmail .
8044The
8045.i arguments
8046are interpreted depending on the class;
8047typically,
8048there would be a single argument naming the file containing the map.
8049.pp
8050Maps are referenced using the syntax:
8051.(b
8052$( \fImap\fP \fIkey\fP $@ \fIarguments\fP $: \fIdefault\fP $)
8053.)b
8054where either or both of the
8055.i arguments
8056or
8057.i default
8058portion may be omitted.
8059The
8060.i "$@ arguments"
8061may appear more than once.
8062The indicated
8063.i key
8064and
8065.i arguments
8066are passed to the appropriate mapping function.
8067If it returns a value, it replaces the input.
8068If it does not return a value and the
8069.i default
8070is specified, the
8071.i default
8072replaces the input.
8073Otherwise, the input is unchanged.
8074.pp
8075The
8076.i arguments
8077are passed to the map for arbitrary use.
8078Most map classes can interpolate these arguments
8079into their values using the syntax
8080.q %\fIn\fP
8081(where
8082.i n
8083is a digit)
8084to indicate the corresponding
8085.i argument .
8086Argument
8087.q %0
8088indicates the database key.
8089For example, the rule
8090.(b
8091.ta 1.5i
8092R$\- ! $+ $: $(uucp $1 $@ $2 $: $2 @ $1 . UUCP $)
8093.)b
8094Looks up the UUCP name in a (user defined) UUCP map;
8095if not found it turns it into
8096.q \&.UUCP
8097form.
8098The database might contain records like:
8099.(b
8100decvax %1@%0.DEC.COM
8101research %1@%0.ATT.COM
8102.)b
8103Note that
8104.i default
8105clauses never do this mapping.
8106.pp
8107The built-in map with both name and class
8108.q host
8109is the host name canonicalization lookup.
8110Thus,
8111the syntax:
8112.(b
8113$(host \fIhostname\fP$)
8114.)b
8115is equivalent to:
8116.(b
8117$[\fIhostname\fP$]
8118.)b
8119.pp
8120There are many defined classes.
8121.ip dbm
8122Database lookups using the ndbm(3) library.
8123.i Sendmail
8124must be compiled with
8125.b NDBM
8126defined.
8127.ip btree
8128Database lookups using the btree interface to the Berkeley DB
8129library.
8130.i Sendmail
8131must be compiled with
8132.b NEWDB
8133defined.
8134.ip hash
8135Database lookups using the hash interface to the Berkeley DB
8136library.
8137.i Sendmail
8138must be compiled with
8139.b NEWDB
8140defined.
8141.ip nis
8142NIS lookups.
8143.i Sendmail
8144must be compiled with
8145.b NIS
8146defined.
8147.ip nisplus
8148NIS+ lookups.
8149.i Sendmail
8150must be compiled with
8151.b NISPLUS
8152defined.
8153The argument is the name of the table to use for lookups,
8154and the
8155.b \-k
8156and
8157.b \-v
8158flags may be used to set the key and value columns respectively.
8159.ip hesiod
8160Hesiod lookups.
8161.i Sendmail
8162must be compiled with
8163.b HESIOD
8164defined.
8165.ip ldap
8166LDAP X500 directory lookups.
8167.i Sendmail
8168must be compiled with
8169.b LDAPMAP
8170defined.
8171The map supports most of the standard arguments
8172and most of the command line arguments of the
8173.i ldapsearch
8174program.
8175Note that,
8176by default,
8177if a single query matches multiple values,
8178only the first value will be returned
8179unless the
8180.b \-z
8181(value separator)
8182map flag is set.
8183Also, the
8184.b \-1
8185map flag will treat a multiple value return
8186as if there were no matches.
8187.ip netinfo
8188NeXT NetInfo lookups.
8189.i Sendmail
8190must be compiled with
8191.b NETINFO
8192defined.
8193.ip text
8194Text file lookups.
8195The format of the text file is defined by the
8196.b \-k
8197(key field number),
8198.b \-v
8199(value field number),
8200and
8201.b \-z
8202(field delimiter)
8203flags.
8204.ip ph
8205PH query map.
8206Contributed and supported by
8207Mark Roth, roth@uiuc.edu.
8208For more information,
8209consult the web site
8210.q http://www-dev.cso.uiuc.edu/sendmail/ .
8211.ip nsd
8212nsd map for IRIX 6.5 and later.
8213Contributed and supported by Bob Mende of SGI,
8214mende@sgi.com.
8215.ip stab
8216Internal symbol table lookups.
8217Used internally for aliasing.
8218.ip implicit
8219Really should be called
8220.q alias
8221\(em this is used to get the default lookups
8222for alias files,
8223and is the default if no class is specified for alias files.
8224.ip user
8225Looks up users using
8226.i getpwnam (3).
8227The
8228.b \-v
8229flag can be used to specify the name of the field to return
8230(although this is normally used only to check the existence
8231of a user).
8232.ip host
8233Canonifies host domain names.
8234Given a host name it calls the name server
8235to find the canonical name for that host.
8236.ip bestmx
8237Returns the best MX record for a host name given as the key.
8238The current machine is always preferred \*-
8239that is, if the current machine is one of the hosts listed as a
8240lowest-preference MX record, then it will be guaranteed to be returned.
8241This can be used to find out if this machine is the target for an MX record,
8242and mail can be accepted on that basis.
8243If the
8244.b \-z
8245flag is given, then all MX names are returned,
8246separated by the given delimiter.
8247.ip dns
8248This map requires the option -R to specify the DNS resource record
8249type to lookup. The following types are supported:
8250A, AAAA, AFSDB, CNAME, MX, NS, PTR, SRV, and TXT.
8251A map lookup will return only one record.
8252Hence for some types, e.g., MX records, the return value might be a random
8253element of the list due to randomizing in the DNS resolver.
8254.ip sequence
8255The arguments on the `K' line are a list of maps;
8256the resulting map searches the argument maps in order
8257until it finds a match for the indicated key.
8258For example, if the key definition is:
8259.(b
8260Kmap1 ...
8261Kmap2 ...
8262Kseqmap sequence map1 map2
8263.)b
8264then a lookup against
8265.q seqmap
8266first does a lookup in map1.
8267If that is found, it returns immediately.
8268Otherwise, the same key is used for map2.
8269.ip syslog
8270the key is logged via
8271.i syslogd \|(8).
8272The lookup returns the empty string.
8273.ip switch
8274Much like the
8275.q sequence
8276map except that the order of maps is determined by the service switch.
8277The argument is the name of the service to be looked up;
8278the values from the service switch are appended to the map name
8279to create new map names.
8280For example, consider the key definition:
8281.(b
8282Kali switch aliases
8283.)b
8284together with the service switch entry:
8285.(b
8286aliases nis files
8287.)b
8288This causes a query against the map
8289.q ali
8290to search maps named
8291.q ali.nis
8292and
8293.q ali.files
8294in that order.
8295.ip dequote
8296Strip double quotes (") from a name.
8297It does not strip backslashes,
8298and will not strip quotes if the resulting string
8299would contain unscannable syntax
8300(that is, basic errors like unbalanced angle brackets;
8301more sophisticated errors such as unknown hosts are not checked).
8302The intent is for use when trying to accept mail from systems such as
8303DECnet
8304that routinely quote odd syntax such as
8305.(b
8306"49ers::ubell"
8307.)b
8308A typical usage is probably something like:
8309.(b
8310Kdequote dequote
8311
8312\&...
8313
8314R$\- $: $(dequote $1 $)
8315R$\- $+ $: $>3 $1 $2
8316.)b
8317Care must be taken to prevent unexpected results;
8318for example,
8319.(b
8320"|someprogram < input > output"
8321.)b
8322will have quotes stripped,
8323but the result is probably not what you had in mind.
8324Fortunately these cases are rare.
8325.ip regex
8326The map definition on the
8327.b K
8328line contains a regular expression.
8329Any key input is compared to that expression using the
8330POSIX regular expressions routines regcomp(), regerr(), and regexec().
8331Refer to the documentation for those routines for more information
8332about the regular expression matching.
8333No rewriting of the key is done if the
8334.b \-m
8335flag is used. Without it, the key is discarded or if
8336.b \-s
8337if used, it is substituted by the substring matches, delimited by
8338.b $|
8339or the string specified with the the
8340.b \-d
8341flag. The flags available for the map are
8342.(b
8343.ta 4n
8344-n not
8345-f case sensitive
8346-b basic regular expressions (default is extended)
8347-s substring match
8348-d set the delimiter used for -s
8349-a append string to key
8350-m match only, do not replace/discard value
8351-D perform no lookup in deferred delivery mode.
8352.)b
8353The
8354.b \-s
8355flag can include an optional parameter which can be used
8356to select the substrings in the result of the lookup. For example,
8357.(b
8358-s1,3,4
8359.)b
8360Notes: to match a
8361.b $
8362in a string,
8363\\$$
8364must be used.
8365If the pattern contains spaces, they must be replaced
8366with the blank substitution character, unless it is
8367space itself.
8368.ip program
8369The arguments on the
8370.b K
8371line are the pathname to a program and any initial parameters to be passed.
8372When the map is called,
8373the key is added to the initial parameters
8374and the program is invoked
8375as the default user/group id.
8376The first line of standard output is returned as the value of the lookup.
8377This has many potential security problems,
8378and has terrible performance;
8379it should be used only when absolutely necessary.
8380.ip macro
8381Set or clear a macro value.
8382To set a macro,
8383pass the value as the first argument in the map lookup.
8384To clear a macro,
8385do not pass an argument in the map lookup.
8386The map always returns the empty string.
8387Example of typical usage include:
8388.(b
8389Kstorage macro
8390
8391\&...
8392
8393# set macro ${MyMacro} to the ruleset match
8394R$+ $: $(storage {MyMacro} $@ $1 $) $1
8395# set macro ${MyMacro} to an empty string
8396R$* $: $(storage {MyMacro} $@ $) $1
8397# clear macro ${MyMacro}
8398R$\- $: $(storage {MyMacro} $) $1
8399.)b
8400.ip arith
8401Perform simple arithmetic operations.
8402The operation is given as key, currently +, -, *, /, %,
8403|, & (bitwise OR, AND),
8404l (for less than), and = are supported.
8405The two operands are given as arguments.
8406The lookup returns the result of the computation,
8407i.e.
8408.sm TRUE
8409or
8410.sm FALSE
8411for comparisons, integer values otherwise.
8412All options which are possible for maps are ignored.
8413A simple example is:
8414.(b
8415Kcomp arith
8416
8417\&...
8418
8419Scheck_etrn
8420R$* $: $(comp l $@ $&{load_avg} $@ 7 $) $1
8421RFALSE $# error \&...
8422.)b
8423.pp
8424Most of these accept as arguments the same optional flags
8425and a filename
8426(or a mapname for NIS;
8427the filename is the root of the database path,
8428so that
8429.q .db
8430or some other extension appropriate for the database type
8431will be added to get the actual database name).
8432Known flags are:
8433.ip "\-o"
8434Indicates that this map is optional \*- that is,
8435if it cannot be opened,
8436no error is produced,
8437and
8438.i sendmail
8439will behave as if the map existed but was empty.
8440.ip "\-N, \-O"
8441If neither
8442.b \-N
8443or
8444.b \-O
8445are specified,
8446.i sendmail
8447uses an adaptive algorithm to decide whether or not to look for null bytes
8448on the end of keys.
8449It starts by trying both;
8450if it finds any key with a null byte it never tries again without a null byte
8451and vice versa.
8452If
8453.b \-N
8454is specified it never tries without a null byte and
8455if
8456.b \-O
8457is specified it never tries with a null byte.
8458Setting one of
8459these can speed matches but are never necessary.
8460If both
8461.b \-N
8462and
8463.b \-O
8464are specified,
8465.i sendmail
8466will never try any matches at all \(em
8467that is, everything will appear to fail.
8468.ip "\-a\fIx\fP"
8469Append the string
8470.i x
8471on successful matches.
8472For example, the default
8473.i host
8474map appends a dot on successful matches.
8475.ip "\-T\fIx\fP"
8476Append the string
8477.i x
8478on temporary failures.
8479For example,
8480.i x
8481would be appended if a DNS lookup returned
8482.q "server failed"
8483or an NIS lookup could not locate a server.
8484See also the
8485.b \-t
8486flag.
8487.ip "\-f"
8488Do not fold upper to lower case before looking up the key.
8489.ip "\-m"
8490Match only (without replacing the value).
8491If you only care about the existence of a key and not the value
8492(as you might when searching the NIS map
8493.q hosts.byname
8494for example),
8495this flag prevents the map from substituting the value.
8496However,
8497The \-a argument is still appended on a match,
8498and the default is still taken if the match fails.
8499.ip "\-k\fIkeycol\fP"
8500The key column name (for NIS+) or number
8501(for text lookups).
8502For LDAP maps this is an LDAP filter string
8503in which %s is replaced with the literal contents of the lookup key
8504and %0 is replaced with the LDAP escaped contents of the lookup key
8505according to RFC 2254.
8506.ip "\-v\fIvalcol\fP"
8507The value column name (for NIS+) or number
8508(for text lookups).
8509For LDAP maps this is the name of one or more
8510attributes to be returned;
8511multiple attributes can be separated by commas.
8512If not specified, all attributes found in the match
8513will be returned.
8514.ip "\-z\fIdelim\fP"
8515The column delimiter (for text lookups).
8516It can be a single character or one of the special strings
8517.q \|\en
8518or
8519.q \|\et
8520to indicate newline or tab respectively.
8521If omitted entirely,
8522the column separator is any sequence of white space.
8523For LDAP maps this is the separator character
8524to combine multiple values
8525into a single return string.
8526If not set,
8527the LDAP lookup will only return the first match found.
8528.ip "\-t"
8529Normally, when a map attempts to do a lookup
8530and the server fails
8531(e.g.,
8532.i sendmail
8533couldn't contact any name server;
8534this is
8535.i not
8536the same as an entry not being found in the map),
8537the message being processed is queued for future processing.
8538The
8539.b \-t
8540flag turns off this behavior,
8541letting the temporary failure (server down)
8542act as though it were a permanent failure (entry not found).
8543It is particularly useful for DNS lookups,
8544where someone else's misconfigured name server can cause problems
8545on your machine.
8546However, care must be taken to ensure that you don't bounce mail
8547that would be resolved correctly if you tried again.
8548A common strategy is to forward such mail
8549to another, possibly better connected, mail server.
8550.ip "\-D"
8551Perform no lookup in deferred delivery mode.
8552This flag is set by default for the
8553.i host
8554map.
8555.ip "\-S\fIspacesub\fP
8556The character to use to replace space characters
8557after a successful map lookup (esp. useful for regex
8558and syslog maps).
8559.ip "\-s\fIspacesub\fP
8560For the dequote map only,
8561the character to use to replace space characters
8562after a successful dequote.
8563.ip "\-q"
8564Don't dequote the key before lookup.
8565.ip "\-L\fIlevel\fP
8566For the syslog map only, it specifies the level
8567to use for the syslog call.
8568.ip "\-A"
8569When rebuilding an alias file,
8570the
8571.b \-A
8572flag causes duplicate entries in the text version
8573to be merged.
8574For example, two entries:
8575.(b
8576list: user1, user2
8577list: user3
8578.)b
8579would be treated as though it were the single entry
8580.(b
8581list: user1, user2, user3
8582.)b
8583in the presence of the
8584.b \-A
8585flag.
8586.pp
8587Some additional flags are available for the host and dns maps:
8588.ip "\-d"
8589delay: specify the resolver's retransmission time interval (in seconds).
8590.ip "\-r"
8591retry: specify the number of times to retransmit a resolver query.
8592.pp
8593The following additional flags are present in the ldap map only:
8594.ip "\-R"
8595Do not auto chase referrals. sendmail must be compiled with
8596.b \-DLDAP_REFERRALS
8597to use this flag.
8598.ip "\-n"
8599Retrieve attribute names only.
8600.ip "\-V\fIsep\fP"
8601Retrieve both attributes name and value(s),
8602separated by
8603.i sep .
8604.ip "\-r\fIderef\fP"
8605Set the alias dereference option to one of never, always, search, or find.
8606.ip "\-s\fIscope\fP"
8607Set search scope to one of base, one (one level), or sub (subtree).
8608.ip "\-h\fIhost\fP"
8609LDAP server hostname.
8610Some LDAP libraries allow you to specify multiple, space-separated hosts for
8611redundancy.
8612In addition, each of the hosts listed can be followed by a colon and a port
8613number to override the default LDAP port.
8614.ip "\-b\fIbase\fP"
8615LDAP search base.
8616.ip "\-p\fIport\fP"
8617LDAP service port.
8618.ip "\-l\fItimelimit\fP"
8619Time limit for LDAP queries.
8620.ip "\-Z\fIsizelimit\fP"
8621Size (number of matches) limit for LDAP queries.
8622.ip "\-d\fIdistinguished_name\fP"
8623The distinguished name to use to login to the LDAP server.
8624.ip "\-M\fImethod\fP"
8625The method to authenticate to the LDAP server.
8626Should be one of
8627.b LDAP_AUTH_NONE ,
8628.b LDAP_AUTH_SIMPLE ,
8629or
8630.b LDAP_AUTH_KRBV4 .
8631.ip "\-P\fIpasswordfile\fP"
8632The file containing the secret key for the
8633.b LDAP_AUTH_SIMPLE
8634authentication method
8635or the name of the Kerberos ticket file for
8636.b LDAP_AUTH_KRBV4 .
8637.ip "\-1"
8638Force LDAP searches to only succeed if a single match is found.
8639If multiple values are found,
8640the search is treated as if no match was found.
8641.pp
8642The
8643.i dbm
8644map appends the strings
8645.q \&.pag
8646and
8647.q \&.dir
8648to the given filename;
8649the
8650.i hash
8651and
8652.i btree
8653maps append
8654.q \&.db .
8655For example, the map specification
8656.(b
8657Kuucp dbm \-o \-N /etc/mail/uucpmap
8658.)b
8659specifies an optional map named
8660.q uucp
8661of class
8662.q dbm ;
8663it always has null bytes at the end of every string,
8664and the data is located in
8665/etc/mail/uucpmap.{dir,pag}.
8666.pp
8667The program
8668.i makemap (8)
8669can be used to build any of the three database-oriented maps.
8670It takes the following flags:
8671.ip \-f
8672Do not fold upper to lower case in the map.
8673.ip \-N
8674Include null bytes in keys.
8675.ip \-o
8676Append to an existing (old) file.
8677.ip \-r
8678Allow replacement of existing keys;
8679normally, re-inserting an existing key is an error.
8680.ip \-v
8681Print what is happening.
8682.lp
8683The
8684.i sendmail
8685daemon does not have to be restarted to read the new maps
8686as long as you change them in place;
8687file locking is used so that the maps won't be read
8688while they are being updated.
8689.pp
8690New classes can be added in the routine
8691.b setupmaps
8692in file
8693.b conf.c .
8694.sh 2 "Q \*- Queue Group Declaration"
8695.pp
8696In addition to the option
8697.i QueueDirectory,
8698queue groups can be declared that define a (group of) queue directories
8699under a common name.
8700The syntax is as follows:
8701.(b F
8702.b Q \c
8703.i name
8704{, \c
8705.i field =\c
8706.i value \|}+
8707.)b
8708where
8709.i name
8710is the symbolic name of the queue group under which
8711it can be referenced in various places
8712and the
8713.q field=name
8714pairs define attributes of the queue group.
8715Fields are:
8716.ip Flags
8717Flags for this queue group.
8718.ip Nice
8719The nice(2) increment for the queue group.
8720This value must be greater or equal zero.
8721.ip Interval
8722The time between two queue runs.
8723.ip Path
8724The queue directory of the group (required).
8725.ip Runners
8726The number of parallel runners processing the queue.
8727.ip Jobs
8728The maximum number of jobs (messages delivered) per queue run.
8729.ip recipients
8730The maximum number of recipients per envelope.
8731Envelopes with more than this number of recipients will be split
8732into multiple envelopes in the same queue directory.
8733The default value 0 means no limit.
8734.lp
8735Only the first character of the field name is checked.
8736.pp
8737By default, a queue group named
8738.i mqueue
8739is defined that uses the value of the
8740.i QueueDirectory
8741option as path.
8742Notice: all paths that are used for queue groups must
8743be subdirectories of
8744.i QueueDirectory .
8745Since they can be symbolic links, this isn't a real restriction,
8746If
8747.i QueueDirectory
8748uses a wildcard, then the directory one level up is considered
8749the ``base'' directory which all other queue directories must share.
8750Please make sure that the queue directories do not overlap,
8751e.g., do not specify
8752.(b
8753O QueueDirectory=/var/spool/mqueue/*
8754Qone, P=/var/spool/mqueue/dir1
8755Qtwo, P=/var/spool/mqueue/dir2
8756.)b
8757because this also includes
8758.q dir1
8759and
8760.q dir2
8761in the default queue group.
8762However,
8763.(b
8764O QueueDirectory=/var/spool/mqueue/main*
8765Qone, P=/var/spool/mqueue/dir
8766Qtwo, P=/var/spool/mqueue/other*
8767.)b
8768is a valid queue group specification.
8769.pp
8770Options listed in the ``Flags'' field can be used to modify
8771the behavior of a queue group.
8772The ``f'' flag must be set if multiple queue runners are
8773supposed to work on the entries in a queue group.
8774Otherwise
8775.i sendmail
8776will work on the entries strictly sequentially.
8777.pp
8778The ``Interval'' field sets the time between queue runs.
8779If no queue group specific interval is set, then the parameter of the
8780.b -q
8781option from the command line is used.
8782.pp
8783To control the overall number of concurrently active queue runners
8784the option
8785.b MaxQueueChildren
8786can be set.
8787This limits the number of processes used for running the queues to
8788.b MaxQueueChildren ,
8789though at any one time fewer processes may be active
8790as a result of queue options, completed queue runs, system load, etc.
8791.pp
8792The maximum number of queue runners for an individual queue group can be
8793controlled via the
8794.b Runners
8795option.
8796If set to 0, entries in the queue will not be processed, which
8797is useful to ``quarantine'' queue files.
8798The number of runners per queue group may also be set with the option
8799.b MaxRunnersPerQueue ,
8800which applies to queue groups that have no individual limit.
8801That is, the default value for
8802.b Runners
8803is
8804.b MaxRunnersPerQueue
8805if set, otherwise 1.
8806.pp
8807The field Jobs describes the maximum number of jobs
8808(messages delivered) per queue run, which is the queue group specific
8809value of
8810.b MaxQueueRunSize .
8811.pp
8812Notice: queue groups should be declared after all queue related options
8813have been set because queue groups take their defaults from those options.
8814If an option is set after a queue group declaration, the values of
8815options in the queue group are set to the defaults of
8816.i sendmail
8817unless explicitly set in the declaration.
8818.pp
8819Each envelope is assigned to a queue group based on the algorithm
8820described in section
8821``Queue Groups and Queue Directories''.
8822.sh 2 "X \*- Mail Filter (Milter) Definitions"
8823.pp
8824The
8825.i sendmail
8826Mail Filter API (Milter) is designed to allow third-party programs access
8827to mail messages as they are being processed in order to filter
8828meta-information and content.
8829They are declared in the configuration file as:
8830.(b F
8831.b X \c
8832.i name
8833{, \c
8834.i field =\c
8835.i value \|}*
8836.)b
8837where
8838.i name
8839is the name of the filter
8840(used internally only)
8841and the
8842.q field=name
8843pairs define attributes of the filter.
8844Also see the documentation for the
8845.b InputMailFilters
8846option for more information.
8847.pp
8848Fields are:
8849.(b
8850.ta 1i
8851Socket The socket specification
8852Flags Special flags for this filter
8853Timeouts Timeouts for this filter
8854.)b
8855Only the first character of the field name is checked
8856(it's case-sensitive).
8857.pp
8858The socket specification is one of the following forms:
8859.(b F
8860.b S= \c
8861.b inet \c
8862.b :
8863.i port
8864.b @
8865.i host
8866.)b
8867.(b F
8868.b S= \c
8869.b inet6 \c
8870.b :
8871.i port
8872.b @
8873.i host
8874.)b
8875.(b F
8876.b S= \c
8877.b local \c
8878.b :
8879.i path
8880.)b
8881The first two describe an IPv4 or IPv6 socket listening on a certain
8882.i port
8883at a given
8884.i host
8885or IP address.
8886The final form describes a named socket on the filesystem at the given
8887.i path .
8888.pp
8889The following flags may be set in the filter description.
8890.nr ii 4n
8891.ip R
8892Reject connection if filter unavailable.
8893.ip T
8894Temporary fail connection if filter unavailable.
8895.pp
8896The timeouts can be set using the four fields inside of the
8897.b T=
8898equate:
8899.nr ii 4n
8900.ip C
8901Timeout for connecting to a filter.
8902If set to 0, the system's
8903.i connect()
8904timeout will be used.
8905.ip S
8906Timeout for sending information from the MTA to a filter.
8907.ip R
8908Timeout for reading reply from the filter.
8909.ip E
8910Overall timeout between sending end-of-message to filter and waiting for
8911the final acknowledgment.
8912.pp
8913Note the separator between each timeout field is a
8914.b ';' .
8915The default values (if not set) are:
8916.b T=C:5m;S:10s;R:10s;E:5m
8917where
8918.b s
8919is seconds and
8920.b m
8921is minutes.
8922.pp
8923Examples:
8924.(b
8925Xfilter1, S=local:/var/run/f1.sock, F=R
8926Xfilter2, S=inet6:999@localhost, F=T, T=S:1s;R:1s;E:5m
8927Xfilter3, S=inet:3333@localhost, T=C:2m
8928.)b
8929.sh 2 "The User Database"
8930.pp
8931The user database is deprecated in favor of ``virtusertable''
8932and ``genericstable'' as explained in the file
8933.b cf/README .
8934If you have a version of
8935.i sendmail
8936with the user database package
8937compiled in,
8938the handling of sender and recipient addresses
8939is modified.
8940.pp
8941The location of this database is controlled with the
8942.b UserDatabaseSpec
8943option.
8944.sh 3 "Structure of the user database"
8945.pp
8946The database is a sorted (BTree-based) structure.
8947User records are stored with the key:
8948.(b
8949\fIuser-name\fP\fB:\fP\fIfield-name\fP
8950.)b
8951The sorted database format ensures that user records are clustered together.
8952Meta-information is always stored with a leading colon.
8953.pp
8954Field names define both the syntax and semantics of the value.
8955Defined fields include:
8956.nr ii 1i
8957.ip maildrop
8958The delivery address for this user.
8959There may be multiple values of this record.
8960In particular,
8961mailing lists will have one
8962.i maildrop
8963record for each user on the list.
8964.ip "mailname"
8965The outgoing mailname for this user.
8966For each outgoing name,
8967there should be an appropriate
8968.i maildrop
8969record for that name to allow return mail.
8970See also
8971.i :default:mailname .
8972.ip mailsender
8973Changes any mail sent to this address to have the indicated envelope sender.
8974This is intended for mailing lists,
8975and will normally be the name of an appropriate -request address.
8976It is very similar to the owner-\c
8977.i list
8978syntax in the alias file.
8979.ip fullname
8980The full name of the user.
8981.ip office-address
8982The office address for this user.
8983.ip office-phone
8984The office phone number for this user.
8985.ip office-fax
8986The office FAX number for this user.
8987.ip home-address
8988The home address for this user.
8989.ip home-phone
8990The home phone number for this user.
8991.ip home-fax
8992The home FAX number for this user.
8993.ip project
8994A (short) description of the project this person is affiliated with.
8995In the University this is often just the name of their graduate advisor.
8996.ip plan
8997A pointer to a file from which plan information can be gathered.
8998.pp
8999As of this writing,
9000only a few of these fields are actually being used by
9001.i sendmail :
9002.i maildrop
9003and
9004.i mailname .
9005A
9006.i finger
9007program that uses the other fields is planned.
9008.sh 3 "User database semantics"
9009.pp
9010When the rewriting rules submit an address to the local mailer,
9011the user name is passed through the alias file.
9012If no alias is found (or if the alias points back to the same address),
9013the name (with
9014.q :maildrop
9015appended)
9016is then used as a key in the user database.
9017If no match occurs (or if the maildrop points at the same address),
9018forwarding is tried.
9019.pp
9020If the first token of the user name returned by ruleset 0
9021is an
9022.q @
9023sign, the user database lookup is skipped.
9024The intent is that the user database will act as a set of defaults
9025for a cluster (in our case, the Computer Science Division);
9026mail sent to a specific machine should ignore these defaults.
9027.pp
9028When mail is sent,
9029the name of the sending user is looked up in the database.
9030If that user has a
9031.q mailname
9032record,
9033the value of that record is used as their outgoing name.
9034For example, I might have a record:
9035.(b
9036eric:mailname Eric.Allman@CS.Berkeley.EDU
9037.)b
9038This would cause my outgoing mail to be sent as Eric.Allman.
9039.pp
9040If a
9041.q maildrop
9042is found for the user,
9043but no corresponding
9044.q mailname
9045record exists,
9046the record
9047.q :default:mailname
9048is consulted.
9049If present, this is the name of a host to override the local host.
9050For example, in our case we would set it to
9051.q CS.Berkeley.EDU .
9052The effect is that anyone known in the database
9053gets their outgoing mail stamped as
9054.q user@CS.Berkeley.EDU ,
9055but people not listed in the database use the local hostname.
9056.sh 3 "Creating the database\**"
9057.(f
9058\**These instructions are known to be incomplete.
9059Other features are available which provide similar functionality,
9060e.g., virtual hosting and mapping local addresses into a
9061generic form as explained in cf/README.
9062.)f
9063.pp
9064The user database is built from a text file
9065using the
9066.i makemap
9067utility
9068(in the distribution in the makemap subdirectory).
9069The text file is a series of lines corresponding to userdb records;
9070each line has a key and a value separated by white space.
9071The key is always in the format described above \*-
9072for example:
9073.(b
9074eric:maildrop
9075.)b
9076This file is normally installed in a system directory;
9077for example, it might be called
9078.i /etc/mail/userdb .
9079To make the database version of the map, run the program:
9080.(b
9081makemap btree /etc/mail/userdb < /etc/mail/userdb
9082.)b
9083Then create a config file that uses this.
9084For example, using the V8 M4 configuration, include the
9085following line in your .mc file:
9086.(b
9087define(\`confUSERDB_SPEC\', /etc/mail/userdb.db)
9088.)b
9089.sh 1 "OTHER CONFIGURATION"
9090.pp
9091There are some configuration changes that can be made by
9092recompiling
9093.i sendmail .
9094This section describes what changes can be made
9095and what has to be modified to make them.
9096In most cases this should be unnecessary
9097unless you are porting
9098.i sendmail
9099to a new environment.
9100.sh 2 "Parameters in devtools/OS/$oscf"
9101.pp
9102These parameters are intended to describe the compilation environment,
9103not site policy,
9104and should normally be defined in the operating system
9105configuration file.
9106.b "This section needs a complete rewrite."
9107.ip NDBM
9108If set,
9109the new version of the DBM library
9110that allows multiple databases will be used.
9111If neither NDBM nor NEWDB are set,
9112a much less efficient method of alias lookup is used.
9113.ip NEWDB
9114If set, use the new database package from Berkeley (from 4.4BSD).
9115This package is substantially faster than DBM or NDBM.
9116If NEWDB and NDBM are both set,
9117.i sendmail
9118will read DBM files,
9119but will create and use NEWDB files.
9120.ip NIS
9121Include support for NIS.
9122If set together with
9123.i both
9124NEWDB and NDBM,
9125.i sendmail
9126will create both DBM and NEWDB files if and only if
9127an alias file includes the substring
9128.q /yp/
9129in the name.
9130This is intended for compatibility with Sun Microsystems'
9131.i mkalias
9132program used on YP masters.
9133.ip NISPLUS
9134Compile in support for NIS+.
9135.ip NETINFO
9136Compile in support for NetInfo (NeXT stations).
9137.ip LDAPMAP
9138Compile in support for LDAP X500 queries.
9139Requires libldap and liblber
9140from the Umich LDAP 3.2 or 3.3 release
9141or equivalent libraries for other LDAP libraries
9142such as OpenLDAP.
9143.ip HESIOD
9144Compile in support for Hesiod.
9145.ip MAP_NSD
9146Compile in support for IRIX NSD lookups.
9147.ip MAP_REGEX
9148Compile in support for regular expression matching.
9149.ip DNSMAP
9150Compile in support for DNS map lookups in the
9151.i sendmail.cf
9152file.
9153.ip PH_MAP
9154Compile in support for ph lookups.
9155.ip SASL
9156Compile in support for SASL,
9157a required component for SMTP Authentication support.
9158.ip STARTTLS
9159Compile in support for STARTTLS.
9160.ip EGD
9161Compile in support for the "Entropy Gathering Daemon"
9162to provide better random data for TLS.
9163.ip TCPWRAPPERS
9164Compile in support for TCP Wrappers.
9165.ip _PATH_SENDMAILCF
9166The pathname of the sendmail.cf file.
9167.ip _PATH_SENDMAILPID
9168The pathname of the sendmail.pid file.
9169.ip SM_CONF_SHM
9170Compile in support for shared memory, see section about
9171"/var/spool/mqueue".
9172.ip MILTER
9173Compile in support for contacting external mail filters built with the
9174Milter API.
9175.pp
9176There are also several compilation flags to indicate the environment
9177such as
9178.q _AIX3
9179and
9180.q _SCO_unix_ .
9181See the sendmail/README
9182file for the latest scoop on these flags.
9183.sh 2 "Parameters in sendmail/conf.h"
9184.pp
9185Parameters and compilation options
9186are defined in conf.h.
9187Most of these need not normally be tweaked;
9188common parameters are all in sendmail.cf.
9189However, the sizes of certain primitive vectors, etc.,
9190are included in this file.
9191The numbers following the parameters
9192are their default value.
9193.pp
9194This document is not the best source of information
9195for compilation flags in conf.h \(em
9196see sendmail/README or sendmail/conf.h itself.
9197.nr ii 1.2i
9198.ip "MAXLINE [2048]"
9199The maximum line length of any input line.
9200If message lines exceed this length
9201they will still be processed correctly;
9202however, header lines,
9203configuration file lines,
9204alias lines,
9205etc.,
9206must fit within this limit.
9207.ip "MAXNAME [256]"
9208The maximum length of any name,
9209such as a host or a user name.
9210.ip "MAXPV [256]"
9211The maximum number of parameters to any mailer.
9212This limits the number of recipients that may be passed in one transaction.
9213It can be set to any arbitrary number above about 10,
9214since
9215.i sendmail
9216will break up a delivery into smaller batches as needed.
9217A higher number may reduce load on your system, however.
9218.ip "MAXQUEUEGROUPS [50]"
9219The maximum number of queue groups.
9220.ip "MAXATOM [1000]"
9221The maximum number of atoms
9222(tokens)
9223in a single address.
9224For example,
9225the address
9226.q "eric@CS.Berkeley.EDU"
9227is seven atoms.
9228.ip "MAXMAILERS [25]"
9229The maximum number of mailers that may be defined
9230in the configuration file.
9231This value is defined in include/sendmail/sendmail.h.
9232.ip "MAXRWSETS [200]"
9233The maximum number of rewriting sets
9234that may be defined.
9235The first half of these are reserved for numeric specification
9236(e.g., ``S92''),
9237while the upper half are reserved for auto-numbering
9238(e.g., ``Sfoo'').
9239Thus, with a value of 200 an attempt to use ``S99'' will succeed,
9240but ``S100'' will fail.
9241.ip "MAXPRIORITIES [25]"
9242The maximum number of values for the
9243.q Precedence:
9244field that may be defined
9245(using the
9246.b P
9247line in sendmail.cf).
9248.ip "MAXUSERENVIRON [100]"
9249The maximum number of items in the user environment
9250that will be passed to subordinate mailers.
9251.ip "MAXMXHOSTS [100]"
9252The maximum number of MX records we will accept for any single host.
9253.ip "MAXMAPSTACK [12]"
9254The maximum number of maps that may be "stacked" in a
9255.b sequence
9256class map.
9257.ip "MAXMIMEARGS [20]"
9258The maximum number of arguments in a MIME Content-Type: header;
9259additional arguments will be ignored.
9260.ip "MAXMIMENESTING [20]"
9261The maximum depth to which MIME messages may be nested
9262(that is, nested Message or Multipart documents;
9263this does not limit the number of components in a single Multipart document).
9264.ip "MAXDAEMONS [10]"
9265The maximum number of sockets sendmail will open for accepting connections
9266on different ports.
9267.ip "MAXMACNAMELEN [25]"
9268The maximum length of a macro name.
9269.lp
9270A number of other compilation options exist.
9271These specify whether or not specific code should be compiled in.
9272Ones marked with \(dg
9273are 0/1 valued.
9274.nr ii 1.2i
9275.ip NETINET\(dg
9276If set,
9277support for Internet protocol networking is compiled in.
9278Previous versions of
9279.i sendmail
9280referred to this as
9281.sm DAEMON ;
9282this old usage is now incorrect.
9283Defaults on;
9284turn it off in the Makefile
9285if your system doesn't support the Internet protocols.
9286.ip NETINET6\(dg
9287If set,
9288support for IPv6 networking is compiled in.
9289It must be separately enabled by adding DaemonPortOptions settings.
9290.ip NETISO\(dg
9291If set,
9292support for ISO protocol networking is compiled in
9293(it may be appropriate to #define this in the Makefile instead of conf.h).
9294.ip NETUNIX\(dg
9295If set,
9296support for UNIX domain sockets is compiled in.
9297This is used for control socket support.
9298.ip LOG
9299If set,
9300the
9301.i syslog
9302routine in use at some sites is used.
9303This makes an informational log record
9304for each message processed,
9305and makes a higher priority log record
9306for internal system errors.
9307.b "STRONGLY RECOMMENDED"
9308\(em if you want no logging, turn it off in the configuration file.
9309.ip MATCHGECOS\(dg
9310Compile in the code to do ``fuzzy matching'' on the GECOS field
9311in /etc/passwd.
9312This also requires that the
9313.b MatchGECOS
9314option be turned on.
9315.ip NAMED_BIND\(dg
9316Compile in code to use the
9317Berkeley Internet Name Domain (BIND) server
9318to resolve TCP/IP host names.
9319.ip NOTUNIX
9320If you are using a non-UNIX mail format,
9321you can set this flag to turn off special processing
9322of UNIX-style
9323.q "From "
9324lines.
9325.ip USERDB\(dg
9326Include the
9327.b experimental
9328Berkeley user information database package.
9329This adds a new level of local name expansion
9330between aliasing and forwarding.
9331It also uses the NEWDB package.
9332This may change in future releases.
9333.lp
9334The following options are normally turned on
9335in per-operating-system clauses in conf.h.
9336.ip IDENTPROTO\(dg
9337Compile in the IDENT protocol as defined in RFC 1413.
9338This defaults on for all systems except Ultrix,
9339which apparently has the interesting
9340.q feature
9341that when it receives a
9342.q "host unreachable"
9343message it closes all open connections to that host.
9344Since some firewall gateways send this error code
9345when you access an unauthorized port (such as 113, used by IDENT),
9346Ultrix cannot receive email from such hosts.
9347.ip SYSTEM5
9348Set all of the compilation parameters appropriate for System V.
9349.ip HASFLOCK\(dg
9350Use Berkeley-style
9351.b flock
9352instead of System V
9353.b lockf
9354to do file locking.
9355Due to the highly unusual semantics of locks
9356across forks in
9357.b lockf ,
9358this should always be used if at all possible.
9359.ip HASINITGROUPS
9360Set this if your system has the
9361.i initgroups()
9362call
9363(if you have multiple group support).
9364This is the default if SYSTEM5 is
9365.i not
9366defined or if you are on HPUX.
9367.ip HASUNAME
9368Set this if you have the
9369.i uname (2)
9370system call (or corresponding library routine).
9371Set by default if
9372SYSTEM5
9373is set.
9374.ip HASGETDTABLESIZE
9375Set this if you have the
9376.i getdtablesize (2)
9377system call.
9378.ip HASWAITPID
9379Set this if you have the
9380.i haswaitpid (2)
9381system call.
9382.ip FAST_PID_RECYCLE
9383Set this if your system can possibly
9384reuse the same pid in the same second of time.
9385.ip SFS_TYPE
9386The mechanism that can be used to get file system capacity information.
9387The values can be one of
9388SFS_USTAT (use the ustat(2) syscall),
9389SFS_4ARGS (use the four argument statfs(2) syscall),
9390SFS_VFS (use the two argument statfs(2) syscall including <sys/vfs.h>),
9391SFS_MOUNT (use the two argument statfs(2) syscall including <sys/mount.h>),
9392SFS_STATFS (use the two argument statfs(2) syscall including <sys/statfs.h>),
9393SFS_STATVFS (use the two argument statfs(2) syscall including <sys/statvfs.h>),
9394or
9395SFS_NONE (no way to get this information).
9396.ip LA_TYPE
9397The load average type.
9398Details are described below.
9399.lp
9400The are several built-in ways of computing the load average.
9401.i Sendmail
9402tries to auto-configure them based on imperfect guesses;
9403you can select one using the
9404.i cc
9405option
9406.b \-DLA_TYPE= \c
9407.i type ,
9408where
9409.i type
9410is:
9411.ip LA_INT
9412The kernel stores the load average in the kernel as an array of long integers.
9413The actual values are scaled by a factor FSCALE
9414(default 256).
9415.ip LA_SHORT
9416The kernel stores the load average in the kernel as an array of short integers.
9417The actual values are scaled by a factor FSCALE
9418(default 256).
9419.ip LA_FLOAT
9420The kernel stores the load average in the kernel as an array of
9421double precision floats.
9422.ip LA_MACH
9423Use MACH-style load averages.
9424.ip LA_SUBR
9425Call the
9426.i getloadavg
9427routine to get the load average as an array of doubles.
9428.ip LA_ZERO
9429Always return zero as the load average.
9430This is the fallback case.
9431.lp
9432If type
9433.sm LA_INT ,
9434.sm LA_SHORT ,
9435or
9436.sm LA_FLOAT
9437is specified,
9438you may also need to specify
9439.sm _PATH_UNIX
9440(the path to your system binary)
9441and
9442.sm LA_AVENRUN
9443(the name of the variable containing the load average in the kernel;
9444usually
9445.q _avenrun
9446or
9447.q avenrun ).
9448.sh 2 "Configuration in sendmail/conf.c"
9449.pp
9450The following changes can be made in conf.c.
9451.sh 3 "Built-in Header Semantics"
9452.pp
9453Not all header semantics are defined in the configuration file.
9454Header lines that should only be included by certain mailers
9455(as well as other more obscure semantics)
9456must be specified in the
9457.i HdrInfo
9458table in
9459.i conf.c .
9460This table contains the header name
9461(which should be in all lower case)
9462and a set of header control flags (described below),
9463The flags are:
9464.ip H_ACHECK
9465Normally when the check is made to see if a header line is compatible
9466with a mailer,
9467.i sendmail
9468will not delete an existing line.
9469If this flag is set,
9470.i sendmail
9471will delete
9472even existing header lines.
9473That is,
9474if this bit is set and the mailer does not have flag bits set
9475that intersect with the required mailer flags
9476in the header definition in
9477sendmail.cf,
9478the header line is
9479.i always
9480deleted.
9481.ip H_EOH
9482If this header field is set,
9483treat it like a blank line,
9484i.e.,
9485it will signal the end of the header
9486and the beginning of the message text.
9487.ip H_FORCE
9488Add this header entry
9489even if one existed in the message before.
9490If a header entry does not have this bit set,
9491.i sendmail
9492will not add another header line if a header line
9493of this name already existed.
9494This would normally be used to stamp the message
9495by everyone who handled it.
9496.ip H_TRACE
9497If set,
9498this is a timestamp
9499(trace)
9500field.
9501If the number of trace fields in a message
9502exceeds a preset amount
9503the message is returned
9504on the assumption that it has an aliasing loop.
9505.ip H_RCPT
9506If set,
9507this field contains recipient addresses.
9508This is used by the
9509.b \-t
9510flag to determine who to send to
9511when it is collecting recipients from the message.
9512.ip H_FROM
9513This flag indicates that this field
9514specifies a sender.
9515The order of these fields in the
9516.i HdrInfo
9517table specifies
9518.i sendmail 's
9519preference
9520for which field to return error messages to.
9521.ip H_ERRORSTO
9522Addresses in this header should receive error messages.
9523.ip H_CTE
9524This header is a Content-Transfer-Encoding header.
9525.ip H_CTYPE
9526This header is a Content-Type header.
9527.ip H_STRIPVAL
9528Strip the value from the header (for Bcc:).
9529.nr ii 5n
9530.lp
9531Let's look at a sample
9532.i HdrInfo
9533specification:
9534.(b
9535.ta 4n +\w'"content-transfer-encoding", 'u
9536struct hdrinfo HdrInfo[] =
9537\&{
9538 /* originator fields, most to least significant */
9539 "resent-sender", H_FROM,
9540 "resent-from", H_FROM,
9541 "sender", H_FROM,
9542 "from", H_FROM,
9543 "full-name", H_ACHECK,
9544 "errors-to", H_FROM\^|\^H_ERRORSTO,
9545 /* destination fields */
9546 "to", H_RCPT,
9547 "resent-to", H_RCPT,
9548 "cc", H_RCPT,
9549 "bcc", H_RCPT\^|\^H_STRIPVAL,
9550 /* message identification and control */
9551 "message", H_EOH,
9552 "text", H_EOH,
9553 /* trace fields */
9554 "received", H_TRACE\^|\^H_FORCE,
9555 /* miscellaneous fields */
9556 "content-transfer-encoding", H_CTE,
9557 "content-type", H_CTYPE,
9558
9559 NULL, 0,
9560};
9561.)b
9562This structure indicates that the
9563.q To: ,
9564.q Resent-To: ,
9565and
9566.q Cc:
9567fields
9568all specify recipient addresses.
9569Any
9570.q Full-Name:
9571field will be deleted unless the required mailer flag
9572(indicated in the configuration file)
9573is specified.
9574The
9575.q Message:
9576and
9577.q Text:
9578fields will terminate the header;
9579these are used by random dissenters around the network world.
9580The
9581.q Received:
9582field will always be added,
9583and can be used to trace messages.
9584.pp
9585There are a number of important points here.
9586First,
9587header fields are not added automatically just because they are in the
9588.i HdrInfo
9589structure;
9590they must be specified in the configuration file
9591in order to be added to the message.
9592Any header fields mentioned in the configuration file but not
9593mentioned in the
9594.i HdrInfo
9595structure have default processing performed;
9596that is,
9597they are added unless they were in the message already.
9598Second,
9599the
9600.i HdrInfo
9601structure only specifies cliched processing;
9602certain headers are processed specially by ad hoc code
9603regardless of the status specified in
9604.i HdrInfo .
9605For example,
9606the
9607.q Sender:
9608and
9609.q From:
9610fields are always scanned on ARPANET mail
9611to determine the sender\**;
9612.(f
9613\**Actually, this is no longer true in SMTP;
9614this information is contained in the envelope.
9615The older ARPANET protocols did not completely distinguish
9616envelope from header.
9617.)f
9618this is used to perform the
9619.q "return to sender"
9620function.
9621The
9622.q "From:"
9623and
9624.q "Full-Name:"
9625fields are used to determine the full name of the sender
9626if possible;
9627this is stored in the macro
9628.b $x
9629and used in a number of ways.
9630.sh 3 "Restricting Use of Email"
9631.pp
9632If it is necessary to restrict mail through a relay,
9633the
9634.i checkcompat
9635routine can be modified.
9636This routine is called for every recipient address.
9637It returns an exit status
9638indicating the status of the message.
9639The status
9640.sm EX_OK
9641accepts the address,
9642.sm EX_TEMPFAIL
9643queues the message for a later try,
9644and other values
9645(commonly
9646.sm EX_UNAVAILABLE )
9647reject the message.
9648It is up to
9649.i checkcompat
9650to print an error message
9651(using
9652.i usrerr )
9653if the message is rejected.
9654For example,
9655.i checkcompat
9656could read:
9657.(b
9658.re
9659.sz -1
9660.ta 4n +4n +4n +4n +4n +4n +4n
9661int
9662checkcompat(to, e)
9663 register ADDRESS *to;
9664 register ENVELOPE *e;
9665\&{
9666 register STAB *s;
9667
9668 s = stab("private", ST_MAILER, ST_FIND);
9669 if (s != NULL && e\->e_from.q_mailer != LocalMailer &&
9670 to->q_mailer == s->s_mailer)
9671 {
9672 usrerr("No private net mail allowed through this machine");
9673 return (EX_UNAVAILABLE);
9674 }
9675 if (MsgSize > 50000 && bitnset(M_LOCALMAILER, to\->q_mailer))
9676 {
9677 usrerr("Message too large for non-local delivery");
9678 e\->e_flags |= EF_NORETURN;
9679 return (EX_UNAVAILABLE);
9680 }
9681 return (EX_OK);
9682}
9683.sz
9684.)b
9685This would reject messages greater than 50000 bytes
9686unless they were local.
9687The
9688.i EF_NORETURN
9689flag can be set in
9690.i e\(->e_flags
9691to suppress the return of the actual body
9692of the message in the error return.
9693The actual use of this routine is highly dependent on the
9694implementation,
9695and use should be limited.
9696.sh 3 "New Database Map Classes"
9697.pp
9698New key maps can be added by creating a class initialization function
9699and a lookup function.
9700These are then added to the routine
9701.i setupmaps.
9702.pp
9703The initialization function is called as
9704.(b
9705\fIxxx\fP_map_init(MAP *map, char *args)
9706.)b
9707The
9708.i map
9709is an internal data structure.
9710The
9711.i args
9712is a pointer to the portion of the configuration file line
9713following the map class name;
9714flags and filenames can be extracted from this line.
9715The initialization function must return
9716.sm true
9717if it successfully opened the map,
9718.sm false
9719otherwise.
9720.pp
9721The lookup function is called as
9722.(b
9723\fIxxx\fP_map_lookup(MAP *map, char buf[], char **av, int *statp)
9724.)b
9725The
9726.i map
9727defines the map internally.
9728The
9729.i buf
9730has the input key.
9731This may be (and often is) used destructively.
9732The
9733.i av
9734is a list of arguments passed in from the rewrite line.
9735The lookup function should return a pointer to the new value.
9736If the map lookup fails,
9737.i *statp
9738should be set to an exit status code;
9739in particular, it should be set to
9740.sm EX_TEMPFAIL
9741if recovery is to be attempted by the higher level code.
9742.sh 3 "Queueing Function"
9743.pp
9744The routine
9745.i shouldqueue
9746is called to decide if a message should be queued
9747or processed immediately.
9748Typically this compares the message priority to the current load average.
9749The default definition is:
9750.(b
9751bool
9752shouldqueue(pri, ctime)
9753 long pri;
9754 time_t ctime;
9755{
9756 if (CurrentLA < QueueLA)
9757 return false;
9758 return (pri > (QueueFactor / (CurrentLA \- QueueLA + 1)));
9759}
9760.)b
9761If the current load average
9762(global variable
9763.i CurrentLA ,
9764which is set before this function is called)
9765is less than the low threshold load average
9766(option
9767.b x ,
9768variable
9769.i QueueLA ),
9770.i shouldqueue
9771returns
9772.sm false
9773immediately
9774(that is, it should
9775.i not
9776queue).
9777If the current load average exceeds the high threshold load average
9778(option
9779.b X ,
9780variable
9781.i RefuseLA ),
9782.i shouldqueue
9783returns
9784.sm true
9785immediately.
9786Otherwise, it computes the function based on the message priority,
9787the queue factor
9788(option
9789.b q ,
9790global variable
9791.i QueueFactor ),
9792and the current and threshold load averages.
9793.pp
9794An implementation wishing to take the actual age of the message into account
9795can also use the
9796.i ctime
9797parameter,
9798which is the time that the message was first submitted to
9799.i sendmail .
9800Note that the
9801.i pri
9802parameter is already weighted
9803by the number of times the message has been tried
9804(although this tends to lower the priority of the message with time);
9805the expectation is that the
9806.i ctime
9807would be used as an
9808.q "escape clause"
9809to ensure that messages are eventually processed.
9810.sh 3 "Refusing Incoming SMTP Connections"
9811.pp
9812The function
9813.i refuseconnections
9814returns
9815.sm true
9816if incoming SMTP connections should be refused.
9817The current implementation is based exclusively on the current load average
9818and the refuse load average option
9819(option
9820.b X ,
9821global variable
9822.i RefuseLA ):
9823.(b
9824bool
9825refuseconnections()
9826{
9827 return (RefuseLA > 0 && CurrentLA >= RefuseLA);
9828}
9829.)b
9830A more clever implementation
9831could look at more system resources.
9832.sh 3 "Load Average Computation"
9833.pp
9834The routine
9835.i getla
9836returns the current load average (as a rounded integer).
9837The distribution includes several possible implementations.
9838If you are porting to a new environment
9839you may need to add some new tweaks.\**
9840.(f
9841\**If you do, please send updates to
9842sendmail@Sendmail.ORG.
9843.)f
9844.sh 2 "Configuration in sendmail/daemon.c"
9845.pp
9846The file
9847.i sendmail/daemon.c
9848contains a number of routines that are dependent
9849on the local networking environment.
9850The version supplied assumes you have BSD style sockets.
9851.pp
9852In previous releases,
9853we recommended that you modify the routine
9854.i maphostname
9855if you wanted to generalize
9856.b $[
9857\&...\&
9858.b $]
9859lookups.
9860We now recommend that you create a new keyed map instead.
9861.sh 2 "STARTTLS"
9862.pp
9863In this section we assume that
9864.i sendmail
9865has been compiled with support for STARTTLS.
9866To properly understand the use of STARTTLS in
9867.i sendmail ,
9868it is necessary to understand at least some basics about X.509 certificates
9869and public key cryptography.
9870This information can be found in books about SSL/TLS
9871or on WWW sites, e.g.,
9872.q http://www.OpenSSL.org/ .
9873.sh 3 "Certificates for STARTTLS"
9874.pp
9875When acting as a server,
9876.i sendmail
9877requires X.509 certificates to support STARTTLS:
9878one as certificate for the server (ServerCertFile and corresponding
9879private ServerKeyFile)
9880at least one root CA (CACERTFile),
9881i.e., a certificate that is used to sign other certificates,
9882and a path to a directory which contains other CAs (CACERTPath).
9883The file specified via
9884CACERTFile
9885can contain several certificates of CAs.
9886The DNs of these certificates are sent
9887to the client during the TLS handshake (as part of the
9888CertificateRequest) as the list of acceptable CAs.
9889However, do not list too many root CAs in that file, otherwise
9890the TLS handshake may fail; e.g.,
9891.(b
9892error:14094417:SSL routines:SSL3_READ_BYTES:
9893sslv3 alert illegal parameter:s3_pkt.c:964:SSL alert number 47
9894.)b
9895You should probably put only the CA cert into that file
9896that signed your own cert(s), or at least only those you trust.
9897The CACERTPath directory must contain the hashes of each CA certificate
9898as filenames (or as links to them).
9899Symbolic links can be generated with the following
9900two (Bourne) shell commands:
9901.(b
9902C=FileName_of_CA_Certificate
9903ln -s $C `openssl x509 -noout -hash < $C`.0
9904.)b
9905An X.509 certificate is also required for authentication in client mode
9906(ClientCertFile and corresponding private ClientKeyFile), however,
9907.i sendmail
9908will always use STARTTLS when offered by a server.
9909The client and server certificates can be identical.
9910Certificates can be obtained from a certificate authority
9911or created with the help of OpenSSL.
9912The required format for certificates and private keys is PEM.
9913To allow for automatic startup of sendmail, private keys
9914(ServerKeyFile, ClientKeyFile)
9915must be stored unencrypted.
9916The keys are only protected by the permissions of the file system.
9917Never make a private key available to a third party.
9918.sh 3 "PRNG for STARTTLS"
9919.pp
9920STARTTLS requires a strong pseudo random number generator (PRNG)
9921to operate properly.
9922Depending on the TLS library you use, it may be required to explicitly
9923initialize the PRNG with random data.
9924OpenSSL makes use of
9925.b /dev/urandom(4)
9926if available (this corresponds to the compile flag HASURANDOMDEV).
9927On systems which lack this support, a random file must be specified in the
9928.i sendmail.cf
9929file using the option RandFile.
9930It is
9931.b strongly
9932advised to use the "Entropy Gathering Daemon" EGD
9933from Brian Warner on those systems to provide useful random data.
9934In this case,
9935.i sendmail
9936must be compiled with the flag EGD, and the
9937RandFile option must point to the EGD socket.
9938If neither
9939.b /dev/urandom(4)
9940nor EGD are available, you have to make sure
9941that useful random data is available all the time in RandFile.
9942If the file hasn't been modified in the last 10 minutes before
9943it is supposed to be used by
9944.i sendmail
9945the content is considered obsolete.
9946One method for generating this file is:
9947.(b
9948openssl rand -out /etc/mail/randfile -rand \c
9949.i /path/to/file:... \c
9950256
9951.)b
9952See the OpenSSL documentation for more information.
9953In this case, the PRNG for TLS is only
9954seeded with other random data if the
9955.b DontBlameSendmail
9956option
9957.b InsufficientEntropy
9958is set.
9959This is most likely not sufficient for certain actions, e.g.,
9960generation of (temporary) keys.
9961.pp
9962Please see the OpenSSL documentation or other sources
9963for further information about certificates, their creation and their usage,
9964the importance of a good PRNG, and other aspects of TLS.
9965.sh 1 "ACKNOWLEDGEMENTS"
9966.pp
9967I've worked on
9968.i sendmail
9969for many years,
9970and many employers have been remarkably patient
9971about letting me work on a large project
9972that was not part of my official job.
9973This includes time on the INGRES Project at
9974the University of California at Berkeley,
9975at Britton Lee,
9976and again on the Mammoth and Titan Projects at Berkeley.
9977.pp
9978Much of the second wave of improvements
9979resulting in version 8.1
9980should be credited to Bryan Costales of the
9981International Computer Science Institute.
9982As he passed me drafts of his book on
9983.i sendmail
9984I was inspired to start working on things again.
9985Bryan was also available to bounce ideas off of.
9986.pp
9987Gregory Neil Shapiro
9988of Worcester Polytechnic Institute
9989has become instrumental in all phases of
9990.i sendmail
9991support and development,
9992and was largely responsible for getting versions 8.8 and 8.9
9993out the door.
9994.pp
9995Many, many people contributed chunks of code and ideas to
9996.i sendmail .
9997It has proven to be a group network effort.
9998Version 8 in particular was a group project.
9999The following people and organizations made notable contributions:
10000.(l
10001Claus Assmann
10002John Beck, Hewlett-Packard & Sun Microsystems
10003Keith Bostic, CSRG, University of California, Berkeley
10004Andrew Cheng, Sun Microsystems
10005Michael J. Corrigan, University of California, San Diego
10006Bryan Costales, International Computer Science Institute & InfoBeat
10007Pa\*:r (Pell) Emanuelsson
10008Craig Everhart, Transarc Corporation
10009Per Hedeland, Ericsson
10010Tom Ivar Helbekkmo, Norwegian School of Economics
10011Kari Hurtta, Finnish Meteorological Institute
10012Allan E. Johannesen, WPI
10013Jonathan Kamens, OpenVision Technologies, Inc.
10014Takahiro Kanbe, Fuji Xerox Information Systems Co., Ltd.
10015Brian Kantor, University of California, San Diego
10016John Kennedy, Cal State University, Chico
10017Murray S. Kucherawy, HookUp Communication Corp.
10018Bruce Lilly, Sony U.S.
10019Karl London
10020Motonori Nakamura, Ritsumeikan University & Kyoto University
10021John Gardiner Myers, Carnegie Mellon University
10022Neil Rickert, Northern Illinois University
10023Gregory Neil Shapiro, WPI
10024Eric Schnoebelen, Convex Computer Corp.
10025Eric Wassenaar, National Institute for Nuclear and High Energy Physics, Amsterdam
10026Randall Winchester, University of Maryland
10027Christophe Wolfhugel, Pasteur Institute & Herve Schauer Consultants (Paris)
10028Exactis.com, Inc.
10029.)l
10030I apologize for anyone I have omitted, misspelled, misattributed, or
10031otherwise missed.
10032At this point, I suspect that at least a hundred people
10033have contributed code,
10034and many more have contributed ideas, comments, and encouragement.
10035I've tried to list them in the RELEASE_NOTES in the distribution directory.
10036I appreciate their contribution as well.
10037.pp
10038Special thanks are reserved for Michael Corrigan and Christophe Wolfhugel,
10039who besides being wonderful guinea pigs and contributors
10040have also consented to be added to the ``sendmail@Sendmail.ORG'' list
10041and, by answering the bulk of the questions sent to that list,
10042have freed me up to do other work.
10043.++ A
10044.+c "COMMAND LINE FLAGS"
10045.ba 0
10046.nr ii 1i
10047.pp
10048Arguments must be presented with flags before addresses.
10049The flags are:
10050.ip \-A\fIx\fP
10051Select an alternative .cf file which is either
10052.i sendmail.cf
10053for
10054.b \-Am
10055or
10056.i submit.cf
10057for
10058.b \-Ac .
10059By default the .cf file is chosen based on the operation mode.
10060For
10061.b -bm
10062(default),
10063.b -bs ,
10064and
10065.b -t
10066it is
10067.i submit.cf
10068if it exists, for all others it is
10069.i sendmail.cf .
10070.ip \-b\fIx\fP
10071Set operation mode to
10072.i x .
10073Operation modes are:
10074.(b
10075.ta 4n
10076m Deliver mail (default)
10077s Speak SMTP on input side
10078a\(dg ``Arpanet'' mode (get envelope sender information from header)
10079d Run as a daemon in background
10080D Run as a daemon in foreground
10081t Run in test mode
10082v Just verify addresses, don't collect or deliver
10083i Initialize the alias database
10084p Print the mail queue
10085P Print overview over the mail queue (requires shared memory)
10086h Print the persistent host status database
10087H Purge expired entries from the persistent host status database
10088.)b
10089.(f
10090\(dgDeprecated.
10091.)f
10092.ip \-B\fItype\fP
10093Indicate body type.
10094.ip \-C\fIfile\fP
10095Use a different configuration file.
10096.i Sendmail
10097runs as the invoking user (rather than root)
10098when this flag is specified.
10099.ip \-d\fIlevel\fP
10100Set debugging level.
10101.ip "\-f\ \fIaddr\fP"
10102The envelope sender address is set to
10103.i addr .
10104This address may also be used in the From: header
10105if that header is missing during initial submission.
10106The envelope sender address is used as the recipient
10107for delivery status notifications
10108and may also appear in a Return-Path: header.
10109.ip \-F\ \fIname\fP
10110Sets the full name of this user to
10111.i name .
10112.ip \-G
10113When accepting messages via the command line,
10114indicate that they are for relay (gateway) submission.
10115sendmail may complain about syntactically invalid messages,
10116e.g., unqualified host names,
10117rather than fixing them when this flag is set.
10118sendmail will not do any canonicalization in this mode.
10119.ip "\-h\ \fIcnt\fP"
10120Sets the
10121.q "hop count"
10122to
10123.i cnt .
10124This represents the number of times this message has been processed
10125by
10126.i sendmail
10127(to the extent that it is supported by the underlying networks).
10128.i Cnt
10129is incremented during processing,
10130and if it reaches
10131MAXHOP
10132(currently 25)
10133.i sendmail
10134throws away the message with an error.
10135.ip "\-L \fItag\fP"
10136Sets the identifier used for syslog.
10137Note that this identifier is set
10138as early as possible.
10139However,
10140.i sendmail
10141may be used
10142if problems arise
10143before the command line arguments
10144are processed.
10145.ip \-n
10146Don't do aliasing or forwarding.
10147.ip "\-N \fInotifications\fP"
10148Tag all addresses being sent as wanting the indicated
10149.i notifications ,
10150which consists of the word
10151.q NEVER
10152or a comma-separated list of
10153.q SUCCESS ,
10154.q FAILURE ,
10155and
10156.q DELAY
10157for successful delivery,
10158failure,
10159and a message that is stuck in a queue somewhere.
10160The default is
10161.q FAILURE,DELAY .
10162.ip "\-r\ \fIaddr\fP"
10163An obsolete form of
10164.b \-f .
10165.ip \-o\fIx\|value\fP
10166Set option
10167.i x
10168to the specified
10169.i value .
10170These options are described in Section 5.6.
10171.ip \-O\fIoption\fP\fB=\fP\fIvalue\fP
10172Set
10173.i option
10174to the specified
10175.i value
10176(for long form option names).
10177These options are described in Section 5.6.
10178.ip \-M\fIx\|value\fP
10179Set macro
10180.i x
10181to the specified
10182.i value .
10183.ip \-p\fIprotocol\fP
10184Set the sending protocol.
10185Programs are encouraged to set this.
10186The protocol field can be in the form
10187.i protocol \c
10188.b : \c
10189.i host
10190to set both the sending protocol and sending host.
10191For example,
10192.q \-pUUCP:uunet
10193sets the sending protocol to UUCP
10194and the sending host to uunet.
10195(Some existing programs use \-oM to set the r and s macros;
10196this is equivalent to using \-p.)
10197.ip \-q\fItime\fP
10198Try to process the queued up mail.
10199If the time is given,
10200a
10201.i sendmail
10202will start one or more processes to run through the queue(s) at the specified
10203time interval to deliver queued mail; otherwise, it only runs once.
10204Each of these processes acts on a workgroup.
10205These processes are also known as workgroup processes or WGP's for short.
10206Each workgroup is responsible for controlling the processing of one or
10207more queues; workgroups help manage the use of system resources by sendmail.
10208Each workgroup may have one or more children concurrently processing
10209queues depending on the setting of \fIMaxQueueChildren\fP.
10210.ip \-qp\fItime\fP
10211Similar to \-q with a time argument,
10212except that instead of periodically starting WGP's
10213sendmail starts persistent WGP's
10214that alternate between processing queues and sleeping.
10215The sleep time is specified by the time argument; it defaults to 1 second,
10216except that a WGP always sleeps at least 5 seconds if their queues were
10217empty in the previous run.
10218Persistent processes are managed by a queue control process (QCP).
10219The QCP is the parent process of the WGP's.
10220Typically the QCP will be the sendmail daemon (when started with \-bd or \-bD)
10221or a special process (named Queue control) (when started without \-bd or \-bD).
10222If a persistent WGP ceases to be active for some reason
10223another WGP will be started by the QCP for the same workgroup
10224in most cases. When a persistent WGP has core dumped, the debug flag
10225\fIno_persistent_restart\fP is set or the specific persistent WGP has been
10226restarted too many times already then the WGP will not be started again
10227and a message will be logged to this effect.
10228To stop (SIGTERM) or restart (SIGHUP) persistent WGP's the appropriate
10229signal should be sent to the QCP. The QCP will propagate the signal to all of
10230the WGP's and if appropriate restart the persistent WGP's.
10231.ip \-q\fIGname\fP
10232Run the jobs in the queue group
10233.i name
10234once.
10235.ip \-q[!]\fIXstring\fP
10236Run the queue once,
10237limiting the jobs to those matching
10238.i Xstring .
10239The key letter
10240.i X
10241can be
10242.b I
10243to limit based on queue identifier,
10244.b R
10245to limit based on recipient,
10246or
10247.b S
10248to limit based on sender.
10249A particular queued job is accepted if one of the corresponding addresses
10250contains the indicated
10251.i string .
10252The optional ! character negates the condition tested.
10253Multiple
10254.i \-q\fIX\fP
10255flags are permitted,
10256with items with the same key letter
10257.q or'ed
10258together, and items with different key letters
10259.q and'ed
10260together.
10261.ip "\-R ret"
10262What information you want returned if the message bounces;
10263.i ret
10264can be
10265.q HDRS
10266for headers only or
10267.q FULL
10268for headers plus body.
10269This is a request only;
10270the other end is not required to honor the parameter.
10271If
10272.q HDRS
10273is specified local bounces also return only the headers.
10274.ip \-t
10275Read the header for
10276.q To: ,
10277.q Cc: ,
10278and
10279.q Bcc:
10280lines, and send to everyone listed in those lists.
10281The
10282.q Bcc:
10283line will be deleted before sending.
10284Any addresses in the argument vector will be deleted
10285from the send list.
10286.ip "\-V envid"
10287The indicated
10288.i envid
10289is passed with the envelope of the message
10290and returned if the message bounces.
10291.ip "\-X \fIlogfile\fP"
10292Log all traffic in and out of
10293.i sendmail
10294in the indicated
10295.i logfile
10296for debugging mailer problems.
10297This produces a lot of data very quickly and should be used sparingly.
10298.pp
10299There are a number of options that may be specified as
10300primitive flags.
10301These are the e, i, m, and v options.
10302Also,
10303the f option
10304may be specified as the
10305.b \-s
10306flag.
10307The DSN related options
10308.q "\-N" ,
10309.q "\-R" ,
10310and
10311.q "\-V"
10312have no effects on
10313.i sendmail
10314running as daemon.
10315.+c "QUEUE FILE FORMATS"
10316.pp
10317This appendix describes the format of the queue files.
10318These files live in a queue directory.
10319The individual qf, df, and xf files
10320may be stored in separate
10321.i qf/ ,
10322.i df/ ,
10323and
10324.i xf/
10325subdirectories
10326if they are present in the queue directory.
10327.pp
10328All queue files have the name
10329.i ttYMDhmsNNppppp
10330where
10331.i YMDhmsNNppppp
10332is the
10333.i id
10334for this message
10335and the
10336.i tt
10337is a type.
10338The individual letters in the
10339.i id
10340are:
10341.nr ii 0.5i
10342.ip Y
10343Encoded year
10344.ip M
10345Encoded month
10346.ip D
10347Encoded day
10348.ip h
10349Encoded hour
10350.ip m
10351Encoded minute
10352.ip s
10353Encoded second
10354.ip NN
10355Encoded envelope number
10356.ip ppppp
10357At least five decimal digits of the process ID
10358.pp
10359All files with the same id collectively define one message.
10360Due to the use of memory-buffered files,
10361some of these files may never appear on disk.
10362.pp
10363The types are:
10364.nr ii 0.5i
10365.ip qf
10366The queue control file.
10367This file contains the information necessary to process the job.
10368.ip df
10369The data file.
10370The message body (excluding the header) is kept in this file.
10371Sometimes the df file is not stored in the same directory as the qf file;
10372in this case,
10373the qf file contains a `d' record which names the queue directory
10374that contains the df file.
10375.ip tf
10376A temporary file.
10377This is an image of the
10378.b qf
10379file when it is being rebuilt.
10380It should be renamed to a
10381.b qf
10382file very quickly.
10383.ip xf
10384A transcript file,
10385existing during the life of a session
10386showing everything that happens
10387during that session.
10388Sometimes the xf file must be generated before a queue group has been selected;
10389in this case,
10390the xf file will be stored in a directory of the default queue group.
10391.ip Qf
10392A ``lost'' queue control file.
10393.i sendmail
10394renames a
10395.b qf
10396file to
10397.b Qf
10398if there is a severe (configuration) problem that cannot be solved without
10399human intervention.
10400Search the logfile for the queue file id to figure out what happened.
10401After you resolved the problem, you can rename the
10402.b Qf
10403file to
10404.b qf
10405and send it again.
10406.pp
10407The
10408.b qf
10409file is structured as a series of lines
10410each beginning with a code letter.
10411The lines are as follows:
10412.ip V
10413The version number of the queue file format,
10414used to allow new
10415.i sendmail
10416binaries to read queue files created by older versions.
10417Defaults to version zero.
10418Must be the first line of the file if present.
10419For 8.12 the version number is 6.
10420.ip A
10421The information given by the AUTH= parameter of the
10422.q "MAIL FROM:"
10423command or $f@$j
10424if sendmail has been called directly.
10425.ip H
10426A header definition.
10427There may be any number of these lines.
10428The order is important:
10429they represent the order in the final message.
10430These use the same syntax
10431as header definitions in the configuration file.
10432.ip C
10433The controlling address.
10434The syntax is
10435.q localuser:aliasname .
10436Recipient addresses following this line
10437will be flagged so that deliveries will be run as the
10438.i localuser
10439(a user name from the /etc/passwd file);
10440.i aliasname
10441is the name of the alias that expanded to this address
10442(used for printing messages).
10443.ip Q
10444The ``original recipient'',
10445specified by the ORCPT= field in an ESMTP transaction.
10446Used exclusively for Delivery Status Notifications.
10447It applies only to the following `R' line.
10448.ip r
10449The ``final recipient''
10450used for Delivery Status Notifications.
10451It applies only to the following `R' line.
10452.ip R
10453A recipient address.
10454This will normally be completely aliased,
10455but is actually realiased when the job is processed.
10456There will be one line for each recipient.
10457Version 1 qf files
10458also include a leading colon-terminated list of flags,
10459which can be
10460`S' to return a message on successful final delivery,
10461`F' to return a message on failure,
10462`D' to return a message if the message is delayed,
10463`B' to indicate that the body should be returned,
10464`N' to suppress returning the body,
10465and
10466`P' to declare this as a ``primary'' (command line or SMTP-session) address.
10467.ip S
10468The sender address.
10469There may only be one of these lines.
10470.ip T
10471The job creation time.
10472This is used to compute when to time out the job.
10473.ip P
10474The current message priority.
10475This is used to order the queue.
10476Higher numbers mean lower priorities.
10477The priority changes
10478as the message sits in the queue.
10479The initial priority depends on the message class
10480and the size of the message.
10481.ip M
10482A message.
10483This line is printed by the
10484.i mailq
10485command,
10486and is generally used to store status information.
10487It can contain any text.
10488.ip F
10489Flag bits, represented as one letter per flag.
10490Defined flag bits are
10491.b r
10492indicating that this is a response message
10493and
10494.b w
10495indicating that a warning message has been sent
10496announcing that the mail has been delayed.
10497Other flag bits are:
10498.b 8 :
10499the body contains 8bit data,
10500.b b :
10501a Bcc: header should be removed,
10502.b d :
10503the mail has RET parameters (see RFC 1894),
10504.b n :
10505the body of the message should not be returned
10506in case of an error,
10507.b s :
10508the envelope has been split.
10509.ip N
10510The total number of delivery attempts.
10511.ip K
10512The time (as seconds since January 1, 1970)
10513of the last delivery attempt.
10514.ip d
10515If the df file is in a different directory than the qf file,
10516then a `d' record is present,
10517specifying the directory in which the df file resides.
10518.ip I
10519The i-number of the data file;
10520this can be used to recover your mail queue
10521after a disastrous disk crash.
10522.ip $
10523A macro definition.
10524The values of certain macros
10525are passed through to the queue run phase.
10526.ip B
10527The body type.
10528The remainder of the line is a text string defining the body type.
10529If this field is missing,
10530the body type is assumed to be
10531.q "undefined"
10532and no special processing is attempted.
10533Legal values are
10534.q 7BIT
10535and
10536.q 8BITMIME .
10537.ip Z
10538The original envelope id (from the ESMTP transaction).
10539For Deliver Status Notifications only.
10540.pp
10541As an example,
10542the following is a queue file sent to
10543.q eric@mammoth.Berkeley.EDU
10544and
10545.q bostic@okeeffe.CS.Berkeley.EDU \**:
10546.(f
10547\**This example is contrived and probably inaccurate for your environment.
10548Glance over it to get an idea;
10549nothing can replace looking at what your own system generates.
10550.)f
10551.(b
10552V4
10553T711358135
10554K904446490
10555N0
10556P2100941
10557$_eric@localhost
10558${daemon_flags}
10559Seric
10560Ceric:100:1000:sendmail@vangogh.CS.Berkeley.EDU
10561RPFD:eric@mammoth.Berkeley.EDU
10562RPFD:bostic@okeeffe.CS.Berkeley.EDU
10563H?P?Return-path: <^g>
10564H??Received: by vangogh.CS.Berkeley.EDU (5.108/2.7) id AAA06703;
10565 Fri, 17 Jul 1992 00:28:55 -0700
10566H??Received: from mail.CS.Berkeley.EDU by vangogh.CS.Berkeley.EDU (5.108/2.7)
10567 id AAA06698; Fri, 17 Jul 1992 00:28:54 -0700
10568H??Received: from [128.32.31.21] by mail.CS.Berkeley.EDU (5.96/2.5)
10569 id AA22777; Fri, 17 Jul 1992 03:29:14 -0400
10570H??Received: by foo.bar.baz.de (5.57/Ultrix3.0-C)
10571 id AA22757; Fri, 17 Jul 1992 09:31:25 GMT
10572H?F?From: eric@foo.bar.baz.de (Eric Allman)
10573H?x?Full-name: Eric Allman
10574H??Message-id: <9207170931.AA22757@foo.bar.baz.de>
10575H??To: sendmail@vangogh.CS.Berkeley.EDU
10576H??Subject: this is an example message
10577.)b
10578This shows
10579the person who sent the message,
10580the submission time
10581(in seconds since January 1, 1970),
10582the message priority,
10583the message class,
10584the recipients,
10585and the headers for the message.
10586.+c "SUMMARY OF SUPPORT FILES"
10587.pp
10588This is a summary of the support files
10589that
10590.i sendmail
10591creates or generates.
10592Many of these can be changed by editing the sendmail.cf file;
10593check there to find the actual pathnames.
10594.nr ii 1i
10595.ip "/usr/\*(SD/sendmail"
10596The binary of
10597.i sendmail .
10598.ip /usr/\*(SB/newaliases
10599A link to /usr/\*(SD/sendmail;
10600causes the alias database to be rebuilt.
10601Running this program is completely equivalent to giving
10602.i sendmail
10603the
10604.b \-bi
10605flag.
10606.ip /usr/\*(SB/mailq
10607Prints a listing of the mail queue.
10608This program is equivalent to using the
10609.b \-bp
10610flag to
10611.i sendmail .
10612.ip /etc/mail/sendmail.cf
10613The configuration file,
10614in textual form.
10615.ip /etc/mail/helpfile
10616The SMTP help file.
10617.ip /etc/mail/statistics
10618A statistics file; need not be present.
10619.ip /etc/mail/sendmail.pid
10620Created in daemon mode;
10621it contains the process id of the current SMTP daemon.
10622If you use this in scripts;
10623use ``head \-1'' to get just the first line;
10624the second line contains the command line used to invoke the daemon,
10625and later versions of
10626.i sendmail
10627may add more information to subsequent lines.
10628.ip /etc/mail/aliases
10629The textual version of the alias file.
10630.ip /etc/mail/aliases.db
10631The alias file in
10632.i hash \|(3)
10633format.
10634.ip /etc/mail/aliases.{pag,dir}
10635The alias file in
10636.i ndbm \|(3)
10637format.
10638.ip /var/spool/mqueue
10639The directory in which the mail queue(s)
10640and temporary files reside.
10641.ip /var/spool/mqueue/qf*
10642Control (queue) files for messages.
10643.ip /var/spool/mqueue/df*
10644Data files.
10645.ip /var/spool/mqueue/tf*
10646Temporary versions of the qf files,
10647used during queue file rebuild.
10648.ip /var/spool/mqueue/xf*
10649A transcript of the current session.
10650.if o \
10651\{\
10652. bp
10653. rs
10654. sp |4i
10655. ce 2
10656This page intentionally left blank;
10657replace it with a blank sheet for double-sided output.
10658.\}
10659.\".ro
10660.\".ls 1
10661.\".tp
10662.\".sp 2i
10663.\".in 0
10664.\".ce 100
10665.\".sz 24
10666.\".b SENDMAIL
10667.\".sz 14
10668.\".sp
10669.\"INSTALLATION AND OPERATION GUIDE
10670.\".sp
10671.\".sz 10
10672.\"Eric Allman
10673.\".sp
| 7324just queue messages
7325(i.e., don't try to send them).
7326Defaults to 8 multiplied by
7327the number of processors online on the system
7328(if that can be determined).
7329.ip QueueFileMode=\fImode\fP
7330[no short name]
7331Default permissions for queue files (octal).
7332If not set, sendmail uses 0600 unless its real
7333and effective uid are different in which case it uses 0644.
7334.ip QueueSortOrder=\fIalgorithm\fP
7335[no short name]
7336Sets the
7337.i algorithm
7338used for sorting the queue.
7339Only the first character of the value is used.
7340Legal values are
7341.q host
7342(to order by the name of the first host name of the first recipient),
7343.q filename
7344(to order by the name of the queue file name),
7345.q time
7346(to order by the submission/creation time),
7347.q random
7348(to order randomly),
7349.q modification
7350(to order by the modification time of the qf file (older entries first)),
7351and
7352.q priority
7353(to order by message priority).
7354Host ordering makes better use of the connection cache,
7355but may tend to process low priority messages
7356that go to a single host
7357over high priority messages that go to several hosts;
7358it probably shouldn't be used on slow network links.
7359Filename and modification time ordering saves the overhead of
7360reading all of the queued items
7361before starting the queue run.
7362Creation (submission) time ordering is almost always a bad idea,
7363since it allows large, bulk mail to go out
7364before smaller, personal mail,
7365but may have applicability on some hosts with very fast connections.
7366Random is useful if several queue runners are started by hand
7367which try to drain the same queue since odds are they will be working
7368on different parts of the queue at the same time.
7369Priority ordering is the default.
7370.ip QueueTimeout=\fItimeout\fP
7371[T]
7372A synonym for
7373.q Timeout.queuereturn .
7374Use that form instead of the
7375.q QueueTimeout
7376form.
7377.ip RandFile
7378[no short name]
7379Name of file containing random data or the name of the UNIX socket
7380if EGD is used.
7381A (required) prefix "egd:" or "file:" specifies the type.
7382STARTTLS requires this filename if the compile flag HASURANDOMDEV is not set
7383(see sendmail/README).
7384.ip ResolverOptions=\fIoptions\fP
7385[I]
7386Set resolver options.
7387Values can be set using
7388.b + \c
7389.i flag
7390and cleared using
7391.b \- \c
7392.i flag ;
7393the
7394.i flag s
7395can be
7396.q debug ,
7397.q aaonly ,
7398.q usevc ,
7399.q primary ,
7400.q igntc ,
7401.q recurse ,
7402.q defnames ,
7403.q stayopen ,
7404.q use_inet6 ,
7405or
7406.q dnsrch .
7407The string
7408.q HasWildcardMX
7409(without a
7410.b +
7411or
7412.b \- )
7413can be specified to turn off matching against MX records
7414when doing name canonifications.
7415The string
7416.q WorkAroundBrokenAAAA
7417(without a
7418.b +
7419or
7420.b \- )
7421can be specified to work around some broken nameservers
7422which return SERVFAIL (a temporary failure) on T_AAAA (IPv6) lookups.
7423Notice: it might be necessary to apply the same (or similar) options to
7424.i submit.cf
7425too.
7426.ip RrtImpliesDsn
7427[R]
7428If this option is set, a
7429.q Return-Receipt-To:
7430header causes the request of a DSN, which is sent to
7431the envelope sender as required by RFC 1891,
7432not to the address given in the header.
7433.ip RunAsUser=\fIuser\fP
7434[no short name]
7435The
7436.i user
7437parameter may be a user name
7438(looked up in
7439.i /etc/passwd )
7440or a numeric user id;
7441either form can have
7442.q ":group"
7443attached
7444(where group can be numeric or symbolic).
7445If set to a non-zero (non-root) value,
7446.i sendmail
7447will change to this user id shortly after startup\**.
7448.(f
7449\**When running as a daemon,
7450it changes to this user after accepting a connection
7451but before reading any
7452.sm SMTP
7453commands.
7454.)f
7455This avoids a certain class of security problems.
7456However, this means that all
7457.q \&.forward
7458and
7459.q :include:
7460files must be readable by the indicated
7461.i user
7462and all files to be written must be writable by
7463.i user
7464Also, all file and program deliveries will be marked unsafe
7465unless the option
7466.b DontBlameSendmail=NonRootSafeAddr
7467is set,
7468in which case the delivery will be done as
7469.i user .
7470It is also incompatible with the
7471.b SafeFileEnvironment
7472option.
7473In other words, it may not actually add much to security on an average system,
7474and may in fact detract from security
7475(because other file permissions must be loosened).
7476However, it should be useful on firewalls and other
7477places where users don't have accounts and the aliases file is
7478well constrained.
7479.ip RecipientFactor=\fIfact\fP
7480[y]
7481The indicated
7482.i fact or
7483is added to the priority (thus
7484.i lowering
7485the priority of the job)
7486for each recipient,
7487i.e., this value penalizes jobs with large numbers of recipients.
7488Defaults to 30000.
7489.ip RefuseLA=\fILA\fP
7490[X]
7491When the system load average exceeds
7492.i LA ,
7493refuse incoming SMTP connections.
7494Defaults to 12 multiplied by
7495the number of processors online on the system
7496(if that can be determined).
7497.ip RetryFactor=\fIfact\fP
7498[Z]
7499The
7500.i fact or
7501is added to the priority
7502every time a job is processed.
7503Thus,
7504each time a job is processed,
7505its priority will be decreased by the indicated value.
7506In most environments this should be positive,
7507since hosts that are down are all too often down for a long time.
7508Defaults to 90000.
7509.ip SafeFileEnvironment=\fIdir\fP
7510[no short name]
7511If this option is set,
7512.i sendmail
7513will do a
7514.i chroot (2)
7515call into the indicated
7516.i dir ectory
7517before doing any file writes.
7518If the file name specified by the user begins with
7519.i dir ,
7520that partial path name will be stripped off before writing,
7521so (for example)
7522if the SafeFileEnvironment variable is set to
7523.q /safe
7524then aliases of
7525.q /safe/logs/file
7526and
7527.q /logs/file
7528actually indicate the same file.
7529Additionally, if this option is set,
7530.i sendmail
7531refuses to deliver to symbolic links.
7532.ip SaveFromLine
7533[f]
7534Save
7535UNIX-style
7536.q From
7537lines at the front of headers.
7538Normally they are assumed redundant
7539and discarded.
7540.ip SharedMemoryKey
7541[no short name]
7542Key to use for shared memory segment;
7543if not set (or 0), shared memory will not be used.
7544Requires support for shared memory to be compiled into
7545.i sendmail .
7546If this option is set,
7547.i sendmail
7548can share some data between different instances.
7549For example, the number of entries in a queue directory
7550or the available space in a file system.
7551This allows for more efficient program execution, since only
7552one process needs to update the data instead of each individual
7553process gathering the data each time it is required.
7554.ip SendMimeErrors
7555[j]
7556If set, send error messages in MIME format
7557(see RFC 2045 and RFC 1344 for details).
7558If disabled,
7559.i sendmail
7560will not return the DSN keyword in response to an EHLO
7561and will not do Delivery Status Notification processing as described in
7562RFC 1891.
7563.ip ServerCertFile
7564[no short name]
7565File containing the certificate of the server, i.e., this certificate
7566is used when sendmail acts as server
7567(used for STARTTLS).
7568.ip ServerKeyFile
7569[no short name]
7570File containing the private key belonging to the server certificate
7571(used for STARTTLS).
7572.ip ServiceSwitchFile=\fIfilename\fP
7573[no short name]
7574If your host operating system has a service switch abstraction
7575(e.g., /etc/nsswitch.conf on Solaris
7576or /etc/svc.conf on Ultrix and DEC OSF/1)
7577that service will be consulted and this option is ignored.
7578Otherwise, this is the name of a file
7579that provides the list of methods used to implement particular services.
7580The syntax is a series of lines,
7581each of which is a sequence of words.
7582The first word is the service name,
7583and following words are service types.
7584The services that
7585.i sendmail
7586consults directly are
7587.q aliases
7588and
7589.q hosts.
7590Service types can be
7591.q dns ,
7592.q nis ,
7593.q nisplus ,
7594or
7595.q files
7596(with the caveat that the appropriate support
7597must be compiled in
7598before the service can be referenced).
7599If ServiceSwitchFile is not specified, it defaults to
7600/etc/mail/service.switch.
7601If that file does not exist, the default switch is:
7602.(b
7603aliases files
7604hosts dns nis files
7605.)b
7606The default file is
7607.q /etc/mail/service.switch .
7608.ip SevenBitInput
7609[7]
7610Strip input to seven bits for compatibility with old systems.
7611This shouldn't be necessary.
7612.ip SingleLineFromHeader
7613[no short name]
7614If set, From: lines that have embedded newlines are unwrapped
7615onto one line.
7616This is to get around a botch in Lotus Notes
7617that apparently cannot understand legally wrapped RFC 822 headers.
7618.ip SingleThreadDelivery
7619[no short name]
7620If set, a client machine will never try to open two SMTP connections
7621to a single server machine at the same time,
7622even in different processes.
7623That is, if another
7624.i sendmail
7625is already talking to some host a new
7626.i sendmail
7627will not open another connection.
7628This property is of mixed value;
7629although this reduces the load on the other machine,
7630it can cause mail to be delayed
7631(for example, if one
7632.i sendmail
7633is delivering a huge message, other
7634.i sendmail s
7635won't be able to send even small messages).
7636Also, it requires another file descriptor
7637(for the lock file)
7638per connection, so you may have to reduce the
7639.b ConnectionCacheSize
7640option to avoid running out of per-process file descriptors.
7641Requires the
7642.b HostStatusDirectory
7643option.
7644.ip SmtpGreetingMessage=\fImessage\fP
7645[$e macro]
7646The message printed when the SMTP server starts up.
7647Defaults to
7648.q "$j Sendmail $v ready at $b".
7649.ip StatusFile=\fIfile\fP
7650[S]
7651Log summary statistics in the named
7652.i file .
7653If no file name is specified, "statistics" is used.
7654If not set,
7655no summary statistics are saved.
7656This file does not grow in size.
7657It can be printed using the
7658.i mailstats (8)
7659program.
7660.ip SuperSafe
7661[s]
7662This option can be set to True, False, or Interactive.
7663If set to True,
7664.i sendmail
7665will be super-safe when running things,
7666i.e., always instantiate the queue file,
7667even if you are going to attempt immediate delivery.
7668.i Sendmail
7669always instantiates the queue file
7670before returning control to the client
7671under any circumstances.
7672This should really
7673.i always
7674be set to True.
7675The Interactive value has been introduced in 8.12 and can
7676be used together with
7677.b DeliveryMode=i .
7678It skips some synchronization calls which are effectively
7679doubled in the code execution path for this mode.
7680.ip TLSSrvOptions
7681[no short name]
7682List of options for SMTP STARTTLS for the server
7683consisting of single characters
7684with intervening white space or commas.
7685The flag ``V'' disables client verification, and hence
7686it is not possible to use a client certificate for relaying.
7687Currently there are no other flags available.
7688.ip TempFileMode=\fImode\fP
7689[F]
7690The file mode for transcript files, files to which
7691.i sendmail
7692delivers directly, files in the
7693.b HostStatusDirectory ,
7694and
7695.b StatusFile .
7696It is interpreted in octal by default.
7697Defaults to 0600.
7698.ip Timeout.\fItype\fP=\|\fItimeout\fP
7699[r; subsumes old T option as well]
7700Set timeout values.
7701For more information,
7702see section
7703.\" XREF
77044.1.
7705.ip TimeZoneSpec=\fItzinfo\fP
7706[t]
7707Set the local time zone info to
7708.i tzinfo
7709\*- for example,
7710.q PST8PDT .
7711Actually, if this is not set,
7712the TZ environment variable is cleared (so the system default is used);
7713if set but null, the user's TZ variable is used,
7714and if set and non-null the TZ variable is set to this value.
7715.ip TrustedUser=\fIuser\fP
7716[no short name]
7717The
7718.i user
7719parameter may be a user name
7720(looked up in
7721.i /etc/passwd )
7722or a numeric user id.
7723Trusted user for file ownership and starting the daemon. If set, generated
7724alias databases and the control socket (if configured) will automatically
7725be owned by this user.
7726.ip TryNullMXList
7727[w]
7728If this system is the
7729.q best
7730(that is, lowest preference)
7731MX for a given host,
7732its configuration rules should normally detect this situation
7733and treat that condition specially
7734by forwarding the mail to a UUCP feed,
7735treating it as local,
7736or whatever.
7737However, in some cases (such as Internet firewalls)
7738you may want to try to connect directly to that host
7739as though it had no MX records at all.
7740Setting this option causes
7741.i sendmail
7742to try this.
7743The downside is that errors in your configuration
7744are likely to be diagnosed as
7745.q "host unknown"
7746or
7747.q "message timed out"
7748instead of something more meaningful.
7749This option is disrecommended.
7750.ip UnixFromLine=\fIfromline\fP
7751[$l macro]
7752Defines the format used when
7753.i sendmail
7754must add a UNIX-style From_ line
7755(that is, a line beginning
7756.q From<space>user ).
7757Defaults to
7758.q "From $g $d" .
7759Don't change this unless your system uses a different UNIX mailbox format
7760(very unlikely).
7761.ip UnsafeGroupWrites
7762[no short name]
7763If set (default),
7764:include: and .forward files that are group writable are considered
7765.q unsafe ,
7766that is,
7767they cannot reference programs or write directly to files.
7768World writable :include: and .forward files
7769are always unsafe.
7770Note: use
7771.b DontBlameSendmail
7772instead; this option is deprecated.
7773.ip UseErrorsTo
7774[l]
7775If there is an
7776.q Errors-To:
7777header, send error messages to the addresses listed there.
7778They normally go to the envelope sender.
7779Use of this option causes
7780.i sendmail
7781to violate RFC 1123.
7782This option is disrecommended and deprecated.
7783.ip UserDatabaseSpec=\fIudbspec\fP
7784[U]
7785The user database specification.
7786.ip Verbose
7787[v]
7788Run in verbose mode.
7789If this is set,
7790.i sendmail
7791adjusts options
7792.b HoldExpensive
7793(old
7794.b c )
7795and
7796.b DeliveryMode
7797(old
7798.b d )
7799so that all mail is delivered completely
7800in a single job
7801so that you can see the entire delivery process.
7802Option
7803.b Verbose
7804should
7805.i never
7806be set in the configuration file;
7807it is intended for command line use only.
7808.ip XscriptFileBufferSize=\fIthreshold\fP
7809[no short name]
7810Set the
7811.i threshold ,
7812in bytes,
7813before a memory-based
7814queue transcript file
7815becomes disk-based.
7816The default is 4096 bytes.
7817.lp
7818All options can be specified on the command line using the
7819\-O or \-o flag,
7820but most will cause
7821.i sendmail
7822to relinquish its set-user-ID permissions.
7823The options that will not cause this are
7824SevenBitInput [7],
7825EightBitMode [8],
7826MinFreeBlocks [b],
7827CheckpointInterval [C],
7828DeliveryMode [d],
7829ErrorMode [e],
7830IgnoreDots [i],
7831SendMimeErrors [j],
7832LogLevel [L],
7833MeToo [m],
7834OldStyleHeaders [o],
7835PrivacyOptions [p],
7836SuperSafe [s],
7837Verbose [v],
7838QueueSortOrder,
7839MinQueueAge,
7840DefaultCharSet,
7841Dial Delay,
7842NoRecipientAction,
7843ColonOkInAddr,
7844MaxQueueRunSize,
7845SingleLineFromHeader,
7846and
7847AllowBogusHELO.
7848Actually, PrivacyOptions [p] given on the command line
7849are added to those already specified in the
7850.i sendmail.cf
7851file, i.e., they can't be reset.
7852Also, M (define macro) when defining the r or s macros
7853is also considered
7854.q safe .
7855.sh 2 "P \*- Precedence Definitions"
7856.pp
7857Values for the
7858.q "Precedence:"
7859field may be defined using the
7860.b P
7861control line.
7862The syntax of this field is:
7863.(b
7864\fBP\fP\fIname\fP\fB=\fP\fInum\fP
7865.)b
7866When the
7867.i name
7868is found in a
7869.q Precedence:
7870field,
7871the message class is set to
7872.i num .
7873Higher numbers mean higher precedence.
7874Numbers less than zero
7875have the special property
7876that if an error occurs during processing
7877the body of the message will not be returned;
7878this is expected to be used for
7879.q "bulk"
7880mail such as through mailing lists.
7881The default precedence is zero.
7882For example,
7883our list of precedences is:
7884.(b
7885Pfirst-class=0
7886Pspecial-delivery=100
7887Plist=\-30
7888Pbulk=\-60
7889Pjunk=\-100
7890.)b
7891People writing mailing list exploders
7892are encouraged to use
7893.q "Precedence: list" .
7894Older versions of
7895.i sendmail
7896(which discarded all error returns for negative precedences)
7897didn't recognize this name, giving it a default precedence of zero.
7898This allows list maintainers to see error returns
7899on both old and new versions of
7900.i sendmail .
7901.sh 2 "V \*- Configuration Version Level"
7902.pp
7903To provide compatibility with old configuration files,
7904the
7905.b V
7906line has been added to define some very basic semantics
7907of the configuration file.
7908These are not intended to be long term supports;
7909rather, they describe compatibility features
7910which will probably be removed in future releases.
7911.pp
7912.b N.B.:
7913these version
7914.i levels
7915have nothing
7916to do with the version
7917.i number
7918on the files.
7919For example,
7920as of this writing
7921version 10 config files
7922(specifically, 8.10)
7923used version level 9 configurations.
7924.pp
7925.q Old
7926configuration files are defined as version level one.
7927Version level two files make the following changes:
7928.np
7929Host name canonification ($[ ... $])
7930appends a dot if the name is recognized;
7931this gives the config file a way of finding out if anything matched.
7932(Actually, this just initializes the
7933.q host
7934map with the
7935.q \-a.
7936flag \*- you can reset it to anything you prefer
7937by declaring the map explicitly.)
7938.np
7939Default host name extension is consistent throughout processing;
7940version level one configurations turned off domain extension
7941(that is, adding the local domain name)
7942during certain points in processing.
7943Version level two configurations are expected to include a trailing dot
7944to indicate that the name is already canonical.
7945.np
7946Local names that are not aliases
7947are passed through a new distinguished ruleset five;
7948this can be used to append a local relay.
7949This behavior can be prevented by resolving the local name
7950with an initial `@'.
7951That is, something that resolves to a local mailer and a user name of
7952.q vikki
7953will be passed through ruleset five,
7954but a user name of
7955.q @vikki
7956will have the `@' stripped,
7957will not be passed through ruleset five,
7958but will otherwise be treated the same as the prior example.
7959The expectation is that this might be used to implement a policy
7960where mail sent to
7961.q vikki
7962was handled by a central hub,
7963but mail sent to
7964.q vikki@localhost
7965was delivered directly.
7966.pp
7967Version level three files
7968allow # initiated comments on all lines.
7969Exceptions are backslash escaped # marks
7970and the $# syntax.
7971.pp
7972Version level four configurations
7973are completely equivalent to level three
7974for historical reasons.
7975.pp
7976Version level five configuration files
7977change the default definition of
7978.b $w
7979to be just the first component of the hostname.
7980.pp
7981Version level six configuration files
7982change many of the local processing options
7983(such as aliasing and matching the beginning of the address for
7984`|' characters)
7985to be mailer flags;
7986this allows fine-grained control over the special local processing.
7987Level six configuration files may also use long option names.
7988The
7989.b ColonOkInAddr
7990option (to allow colons in the local-part of addresses)
7991defaults
7992.b on
7993for lower numbered configuration files;
7994the configuration file requires some additional intelligence
7995to properly handle the RFC 822 group construct.
7996.pp
7997Version level seven configuration files
7998used new option names to replace old macros
7999(\c
8000.b $e
8001became
8002.b SmtpGreetingMessage ,
8003.b $l
8004became
8005.b UnixFromLine ,
8006and
8007.b $o
8008became
8009.b OperatorChars .
8010Also, prior to version seven,
8011the
8012.b F=q
8013flag (use 250 instead of 252 return value for
8014.sm "SMTP VRFY"
8015commands)
8016was assumed.
8017.pp
8018Version level eight configuration files allow
8019.b $#
8020on the left hand side of ruleset lines.
8021.pp
8022Version level nine configuration files allow
8023parentheses in rulesets, i.e. they are not treated
8024as comments and hence removed.
8025.pp
8026Version level ten configuration files allow
8027queue group definitions.
8028.pp
8029The
8030.b V
8031line may have an optional
8032.b / \c
8033.i vendor
8034to indicate that this configuration file uses modifications
8035specific to a particular vendor\**.
8036.(f
8037\**And of course, vendors are encouraged to add themselves
8038to the list of recognized vendors by editing the routine
8039.i setvendor
8040in
8041.i conf.c .
8042Please send e-mail to sendmail@Sendmail.ORG
8043to register your vendor dialect.
8044.)f
8045You may use
8046.q /Berkeley
8047to emphasize that this configuration file
8048uses the Berkeley dialect of
8049.i sendmail .
8050.sh 2 "K \*- Key File Declaration"
8051.pp
8052Special maps can be defined using the line:
8053.(b
8054Kmapname mapclass arguments
8055.)b
8056The
8057.i mapname
8058is the handle by which this map is referenced in the rewriting rules.
8059The
8060.i mapclass
8061is the name of a type of map;
8062these are compiled in to
8063.i sendmail .
8064The
8065.i arguments
8066are interpreted depending on the class;
8067typically,
8068there would be a single argument naming the file containing the map.
8069.pp
8070Maps are referenced using the syntax:
8071.(b
8072$( \fImap\fP \fIkey\fP $@ \fIarguments\fP $: \fIdefault\fP $)
8073.)b
8074where either or both of the
8075.i arguments
8076or
8077.i default
8078portion may be omitted.
8079The
8080.i "$@ arguments"
8081may appear more than once.
8082The indicated
8083.i key
8084and
8085.i arguments
8086are passed to the appropriate mapping function.
8087If it returns a value, it replaces the input.
8088If it does not return a value and the
8089.i default
8090is specified, the
8091.i default
8092replaces the input.
8093Otherwise, the input is unchanged.
8094.pp
8095The
8096.i arguments
8097are passed to the map for arbitrary use.
8098Most map classes can interpolate these arguments
8099into their values using the syntax
8100.q %\fIn\fP
8101(where
8102.i n
8103is a digit)
8104to indicate the corresponding
8105.i argument .
8106Argument
8107.q %0
8108indicates the database key.
8109For example, the rule
8110.(b
8111.ta 1.5i
8112R$\- ! $+ $: $(uucp $1 $@ $2 $: $2 @ $1 . UUCP $)
8113.)b
8114Looks up the UUCP name in a (user defined) UUCP map;
8115if not found it turns it into
8116.q \&.UUCP
8117form.
8118The database might contain records like:
8119.(b
8120decvax %1@%0.DEC.COM
8121research %1@%0.ATT.COM
8122.)b
8123Note that
8124.i default
8125clauses never do this mapping.
8126.pp
8127The built-in map with both name and class
8128.q host
8129is the host name canonicalization lookup.
8130Thus,
8131the syntax:
8132.(b
8133$(host \fIhostname\fP$)
8134.)b
8135is equivalent to:
8136.(b
8137$[\fIhostname\fP$]
8138.)b
8139.pp
8140There are many defined classes.
8141.ip dbm
8142Database lookups using the ndbm(3) library.
8143.i Sendmail
8144must be compiled with
8145.b NDBM
8146defined.
8147.ip btree
8148Database lookups using the btree interface to the Berkeley DB
8149library.
8150.i Sendmail
8151must be compiled with
8152.b NEWDB
8153defined.
8154.ip hash
8155Database lookups using the hash interface to the Berkeley DB
8156library.
8157.i Sendmail
8158must be compiled with
8159.b NEWDB
8160defined.
8161.ip nis
8162NIS lookups.
8163.i Sendmail
8164must be compiled with
8165.b NIS
8166defined.
8167.ip nisplus
8168NIS+ lookups.
8169.i Sendmail
8170must be compiled with
8171.b NISPLUS
8172defined.
8173The argument is the name of the table to use for lookups,
8174and the
8175.b \-k
8176and
8177.b \-v
8178flags may be used to set the key and value columns respectively.
8179.ip hesiod
8180Hesiod lookups.
8181.i Sendmail
8182must be compiled with
8183.b HESIOD
8184defined.
8185.ip ldap
8186LDAP X500 directory lookups.
8187.i Sendmail
8188must be compiled with
8189.b LDAPMAP
8190defined.
8191The map supports most of the standard arguments
8192and most of the command line arguments of the
8193.i ldapsearch
8194program.
8195Note that,
8196by default,
8197if a single query matches multiple values,
8198only the first value will be returned
8199unless the
8200.b \-z
8201(value separator)
8202map flag is set.
8203Also, the
8204.b \-1
8205map flag will treat a multiple value return
8206as if there were no matches.
8207.ip netinfo
8208NeXT NetInfo lookups.
8209.i Sendmail
8210must be compiled with
8211.b NETINFO
8212defined.
8213.ip text
8214Text file lookups.
8215The format of the text file is defined by the
8216.b \-k
8217(key field number),
8218.b \-v
8219(value field number),
8220and
8221.b \-z
8222(field delimiter)
8223flags.
8224.ip ph
8225PH query map.
8226Contributed and supported by
8227Mark Roth, roth@uiuc.edu.
8228For more information,
8229consult the web site
8230.q http://www-dev.cso.uiuc.edu/sendmail/ .
8231.ip nsd
8232nsd map for IRIX 6.5 and later.
8233Contributed and supported by Bob Mende of SGI,
8234mende@sgi.com.
8235.ip stab
8236Internal symbol table lookups.
8237Used internally for aliasing.
8238.ip implicit
8239Really should be called
8240.q alias
8241\(em this is used to get the default lookups
8242for alias files,
8243and is the default if no class is specified for alias files.
8244.ip user
8245Looks up users using
8246.i getpwnam (3).
8247The
8248.b \-v
8249flag can be used to specify the name of the field to return
8250(although this is normally used only to check the existence
8251of a user).
8252.ip host
8253Canonifies host domain names.
8254Given a host name it calls the name server
8255to find the canonical name for that host.
8256.ip bestmx
8257Returns the best MX record for a host name given as the key.
8258The current machine is always preferred \*-
8259that is, if the current machine is one of the hosts listed as a
8260lowest-preference MX record, then it will be guaranteed to be returned.
8261This can be used to find out if this machine is the target for an MX record,
8262and mail can be accepted on that basis.
8263If the
8264.b \-z
8265flag is given, then all MX names are returned,
8266separated by the given delimiter.
8267.ip dns
8268This map requires the option -R to specify the DNS resource record
8269type to lookup. The following types are supported:
8270A, AAAA, AFSDB, CNAME, MX, NS, PTR, SRV, and TXT.
8271A map lookup will return only one record.
8272Hence for some types, e.g., MX records, the return value might be a random
8273element of the list due to randomizing in the DNS resolver.
8274.ip sequence
8275The arguments on the `K' line are a list of maps;
8276the resulting map searches the argument maps in order
8277until it finds a match for the indicated key.
8278For example, if the key definition is:
8279.(b
8280Kmap1 ...
8281Kmap2 ...
8282Kseqmap sequence map1 map2
8283.)b
8284then a lookup against
8285.q seqmap
8286first does a lookup in map1.
8287If that is found, it returns immediately.
8288Otherwise, the same key is used for map2.
8289.ip syslog
8290the key is logged via
8291.i syslogd \|(8).
8292The lookup returns the empty string.
8293.ip switch
8294Much like the
8295.q sequence
8296map except that the order of maps is determined by the service switch.
8297The argument is the name of the service to be looked up;
8298the values from the service switch are appended to the map name
8299to create new map names.
8300For example, consider the key definition:
8301.(b
8302Kali switch aliases
8303.)b
8304together with the service switch entry:
8305.(b
8306aliases nis files
8307.)b
8308This causes a query against the map
8309.q ali
8310to search maps named
8311.q ali.nis
8312and
8313.q ali.files
8314in that order.
8315.ip dequote
8316Strip double quotes (") from a name.
8317It does not strip backslashes,
8318and will not strip quotes if the resulting string
8319would contain unscannable syntax
8320(that is, basic errors like unbalanced angle brackets;
8321more sophisticated errors such as unknown hosts are not checked).
8322The intent is for use when trying to accept mail from systems such as
8323DECnet
8324that routinely quote odd syntax such as
8325.(b
8326"49ers::ubell"
8327.)b
8328A typical usage is probably something like:
8329.(b
8330Kdequote dequote
8331
8332\&...
8333
8334R$\- $: $(dequote $1 $)
8335R$\- $+ $: $>3 $1 $2
8336.)b
8337Care must be taken to prevent unexpected results;
8338for example,
8339.(b
8340"|someprogram < input > output"
8341.)b
8342will have quotes stripped,
8343but the result is probably not what you had in mind.
8344Fortunately these cases are rare.
8345.ip regex
8346The map definition on the
8347.b K
8348line contains a regular expression.
8349Any key input is compared to that expression using the
8350POSIX regular expressions routines regcomp(), regerr(), and regexec().
8351Refer to the documentation for those routines for more information
8352about the regular expression matching.
8353No rewriting of the key is done if the
8354.b \-m
8355flag is used. Without it, the key is discarded or if
8356.b \-s
8357if used, it is substituted by the substring matches, delimited by
8358.b $|
8359or the string specified with the the
8360.b \-d
8361flag. The flags available for the map are
8362.(b
8363.ta 4n
8364-n not
8365-f case sensitive
8366-b basic regular expressions (default is extended)
8367-s substring match
8368-d set the delimiter used for -s
8369-a append string to key
8370-m match only, do not replace/discard value
8371-D perform no lookup in deferred delivery mode.
8372.)b
8373The
8374.b \-s
8375flag can include an optional parameter which can be used
8376to select the substrings in the result of the lookup. For example,
8377.(b
8378-s1,3,4
8379.)b
8380Notes: to match a
8381.b $
8382in a string,
8383\\$$
8384must be used.
8385If the pattern contains spaces, they must be replaced
8386with the blank substitution character, unless it is
8387space itself.
8388.ip program
8389The arguments on the
8390.b K
8391line are the pathname to a program and any initial parameters to be passed.
8392When the map is called,
8393the key is added to the initial parameters
8394and the program is invoked
8395as the default user/group id.
8396The first line of standard output is returned as the value of the lookup.
8397This has many potential security problems,
8398and has terrible performance;
8399it should be used only when absolutely necessary.
8400.ip macro
8401Set or clear a macro value.
8402To set a macro,
8403pass the value as the first argument in the map lookup.
8404To clear a macro,
8405do not pass an argument in the map lookup.
8406The map always returns the empty string.
8407Example of typical usage include:
8408.(b
8409Kstorage macro
8410
8411\&...
8412
8413# set macro ${MyMacro} to the ruleset match
8414R$+ $: $(storage {MyMacro} $@ $1 $) $1
8415# set macro ${MyMacro} to an empty string
8416R$* $: $(storage {MyMacro} $@ $) $1
8417# clear macro ${MyMacro}
8418R$\- $: $(storage {MyMacro} $) $1
8419.)b
8420.ip arith
8421Perform simple arithmetic operations.
8422The operation is given as key, currently +, -, *, /, %,
8423|, & (bitwise OR, AND),
8424l (for less than), and = are supported.
8425The two operands are given as arguments.
8426The lookup returns the result of the computation,
8427i.e.
8428.sm TRUE
8429or
8430.sm FALSE
8431for comparisons, integer values otherwise.
8432All options which are possible for maps are ignored.
8433A simple example is:
8434.(b
8435Kcomp arith
8436
8437\&...
8438
8439Scheck_etrn
8440R$* $: $(comp l $@ $&{load_avg} $@ 7 $) $1
8441RFALSE $# error \&...
8442.)b
8443.pp
8444Most of these accept as arguments the same optional flags
8445and a filename
8446(or a mapname for NIS;
8447the filename is the root of the database path,
8448so that
8449.q .db
8450or some other extension appropriate for the database type
8451will be added to get the actual database name).
8452Known flags are:
8453.ip "\-o"
8454Indicates that this map is optional \*- that is,
8455if it cannot be opened,
8456no error is produced,
8457and
8458.i sendmail
8459will behave as if the map existed but was empty.
8460.ip "\-N, \-O"
8461If neither
8462.b \-N
8463or
8464.b \-O
8465are specified,
8466.i sendmail
8467uses an adaptive algorithm to decide whether or not to look for null bytes
8468on the end of keys.
8469It starts by trying both;
8470if it finds any key with a null byte it never tries again without a null byte
8471and vice versa.
8472If
8473.b \-N
8474is specified it never tries without a null byte and
8475if
8476.b \-O
8477is specified it never tries with a null byte.
8478Setting one of
8479these can speed matches but are never necessary.
8480If both
8481.b \-N
8482and
8483.b \-O
8484are specified,
8485.i sendmail
8486will never try any matches at all \(em
8487that is, everything will appear to fail.
8488.ip "\-a\fIx\fP"
8489Append the string
8490.i x
8491on successful matches.
8492For example, the default
8493.i host
8494map appends a dot on successful matches.
8495.ip "\-T\fIx\fP"
8496Append the string
8497.i x
8498on temporary failures.
8499For example,
8500.i x
8501would be appended if a DNS lookup returned
8502.q "server failed"
8503or an NIS lookup could not locate a server.
8504See also the
8505.b \-t
8506flag.
8507.ip "\-f"
8508Do not fold upper to lower case before looking up the key.
8509.ip "\-m"
8510Match only (without replacing the value).
8511If you only care about the existence of a key and not the value
8512(as you might when searching the NIS map
8513.q hosts.byname
8514for example),
8515this flag prevents the map from substituting the value.
8516However,
8517The \-a argument is still appended on a match,
8518and the default is still taken if the match fails.
8519.ip "\-k\fIkeycol\fP"
8520The key column name (for NIS+) or number
8521(for text lookups).
8522For LDAP maps this is an LDAP filter string
8523in which %s is replaced with the literal contents of the lookup key
8524and %0 is replaced with the LDAP escaped contents of the lookup key
8525according to RFC 2254.
8526.ip "\-v\fIvalcol\fP"
8527The value column name (for NIS+) or number
8528(for text lookups).
8529For LDAP maps this is the name of one or more
8530attributes to be returned;
8531multiple attributes can be separated by commas.
8532If not specified, all attributes found in the match
8533will be returned.
8534.ip "\-z\fIdelim\fP"
8535The column delimiter (for text lookups).
8536It can be a single character or one of the special strings
8537.q \|\en
8538or
8539.q \|\et
8540to indicate newline or tab respectively.
8541If omitted entirely,
8542the column separator is any sequence of white space.
8543For LDAP maps this is the separator character
8544to combine multiple values
8545into a single return string.
8546If not set,
8547the LDAP lookup will only return the first match found.
8548.ip "\-t"
8549Normally, when a map attempts to do a lookup
8550and the server fails
8551(e.g.,
8552.i sendmail
8553couldn't contact any name server;
8554this is
8555.i not
8556the same as an entry not being found in the map),
8557the message being processed is queued for future processing.
8558The
8559.b \-t
8560flag turns off this behavior,
8561letting the temporary failure (server down)
8562act as though it were a permanent failure (entry not found).
8563It is particularly useful for DNS lookups,
8564where someone else's misconfigured name server can cause problems
8565on your machine.
8566However, care must be taken to ensure that you don't bounce mail
8567that would be resolved correctly if you tried again.
8568A common strategy is to forward such mail
8569to another, possibly better connected, mail server.
8570.ip "\-D"
8571Perform no lookup in deferred delivery mode.
8572This flag is set by default for the
8573.i host
8574map.
8575.ip "\-S\fIspacesub\fP
8576The character to use to replace space characters
8577after a successful map lookup (esp. useful for regex
8578and syslog maps).
8579.ip "\-s\fIspacesub\fP
8580For the dequote map only,
8581the character to use to replace space characters
8582after a successful dequote.
8583.ip "\-q"
8584Don't dequote the key before lookup.
8585.ip "\-L\fIlevel\fP
8586For the syslog map only, it specifies the level
8587to use for the syslog call.
8588.ip "\-A"
8589When rebuilding an alias file,
8590the
8591.b \-A
8592flag causes duplicate entries in the text version
8593to be merged.
8594For example, two entries:
8595.(b
8596list: user1, user2
8597list: user3
8598.)b
8599would be treated as though it were the single entry
8600.(b
8601list: user1, user2, user3
8602.)b
8603in the presence of the
8604.b \-A
8605flag.
8606.pp
8607Some additional flags are available for the host and dns maps:
8608.ip "\-d"
8609delay: specify the resolver's retransmission time interval (in seconds).
8610.ip "\-r"
8611retry: specify the number of times to retransmit a resolver query.
8612.pp
8613The following additional flags are present in the ldap map only:
8614.ip "\-R"
8615Do not auto chase referrals. sendmail must be compiled with
8616.b \-DLDAP_REFERRALS
8617to use this flag.
8618.ip "\-n"
8619Retrieve attribute names only.
8620.ip "\-V\fIsep\fP"
8621Retrieve both attributes name and value(s),
8622separated by
8623.i sep .
8624.ip "\-r\fIderef\fP"
8625Set the alias dereference option to one of never, always, search, or find.
8626.ip "\-s\fIscope\fP"
8627Set search scope to one of base, one (one level), or sub (subtree).
8628.ip "\-h\fIhost\fP"
8629LDAP server hostname.
8630Some LDAP libraries allow you to specify multiple, space-separated hosts for
8631redundancy.
8632In addition, each of the hosts listed can be followed by a colon and a port
8633number to override the default LDAP port.
8634.ip "\-b\fIbase\fP"
8635LDAP search base.
8636.ip "\-p\fIport\fP"
8637LDAP service port.
8638.ip "\-l\fItimelimit\fP"
8639Time limit for LDAP queries.
8640.ip "\-Z\fIsizelimit\fP"
8641Size (number of matches) limit for LDAP queries.
8642.ip "\-d\fIdistinguished_name\fP"
8643The distinguished name to use to login to the LDAP server.
8644.ip "\-M\fImethod\fP"
8645The method to authenticate to the LDAP server.
8646Should be one of
8647.b LDAP_AUTH_NONE ,
8648.b LDAP_AUTH_SIMPLE ,
8649or
8650.b LDAP_AUTH_KRBV4 .
8651.ip "\-P\fIpasswordfile\fP"
8652The file containing the secret key for the
8653.b LDAP_AUTH_SIMPLE
8654authentication method
8655or the name of the Kerberos ticket file for
8656.b LDAP_AUTH_KRBV4 .
8657.ip "\-1"
8658Force LDAP searches to only succeed if a single match is found.
8659If multiple values are found,
8660the search is treated as if no match was found.
8661.pp
8662The
8663.i dbm
8664map appends the strings
8665.q \&.pag
8666and
8667.q \&.dir
8668to the given filename;
8669the
8670.i hash
8671and
8672.i btree
8673maps append
8674.q \&.db .
8675For example, the map specification
8676.(b
8677Kuucp dbm \-o \-N /etc/mail/uucpmap
8678.)b
8679specifies an optional map named
8680.q uucp
8681of class
8682.q dbm ;
8683it always has null bytes at the end of every string,
8684and the data is located in
8685/etc/mail/uucpmap.{dir,pag}.
8686.pp
8687The program
8688.i makemap (8)
8689can be used to build any of the three database-oriented maps.
8690It takes the following flags:
8691.ip \-f
8692Do not fold upper to lower case in the map.
8693.ip \-N
8694Include null bytes in keys.
8695.ip \-o
8696Append to an existing (old) file.
8697.ip \-r
8698Allow replacement of existing keys;
8699normally, re-inserting an existing key is an error.
8700.ip \-v
8701Print what is happening.
8702.lp
8703The
8704.i sendmail
8705daemon does not have to be restarted to read the new maps
8706as long as you change them in place;
8707file locking is used so that the maps won't be read
8708while they are being updated.
8709.pp
8710New classes can be added in the routine
8711.b setupmaps
8712in file
8713.b conf.c .
8714.sh 2 "Q \*- Queue Group Declaration"
8715.pp
8716In addition to the option
8717.i QueueDirectory,
8718queue groups can be declared that define a (group of) queue directories
8719under a common name.
8720The syntax is as follows:
8721.(b F
8722.b Q \c
8723.i name
8724{, \c
8725.i field =\c
8726.i value \|}+
8727.)b
8728where
8729.i name
8730is the symbolic name of the queue group under which
8731it can be referenced in various places
8732and the
8733.q field=name
8734pairs define attributes of the queue group.
8735Fields are:
8736.ip Flags
8737Flags for this queue group.
8738.ip Nice
8739The nice(2) increment for the queue group.
8740This value must be greater or equal zero.
8741.ip Interval
8742The time between two queue runs.
8743.ip Path
8744The queue directory of the group (required).
8745.ip Runners
8746The number of parallel runners processing the queue.
8747.ip Jobs
8748The maximum number of jobs (messages delivered) per queue run.
8749.ip recipients
8750The maximum number of recipients per envelope.
8751Envelopes with more than this number of recipients will be split
8752into multiple envelopes in the same queue directory.
8753The default value 0 means no limit.
8754.lp
8755Only the first character of the field name is checked.
8756.pp
8757By default, a queue group named
8758.i mqueue
8759is defined that uses the value of the
8760.i QueueDirectory
8761option as path.
8762Notice: all paths that are used for queue groups must
8763be subdirectories of
8764.i QueueDirectory .
8765Since they can be symbolic links, this isn't a real restriction,
8766If
8767.i QueueDirectory
8768uses a wildcard, then the directory one level up is considered
8769the ``base'' directory which all other queue directories must share.
8770Please make sure that the queue directories do not overlap,
8771e.g., do not specify
8772.(b
8773O QueueDirectory=/var/spool/mqueue/*
8774Qone, P=/var/spool/mqueue/dir1
8775Qtwo, P=/var/spool/mqueue/dir2
8776.)b
8777because this also includes
8778.q dir1
8779and
8780.q dir2
8781in the default queue group.
8782However,
8783.(b
8784O QueueDirectory=/var/spool/mqueue/main*
8785Qone, P=/var/spool/mqueue/dir
8786Qtwo, P=/var/spool/mqueue/other*
8787.)b
8788is a valid queue group specification.
8789.pp
8790Options listed in the ``Flags'' field can be used to modify
8791the behavior of a queue group.
8792The ``f'' flag must be set if multiple queue runners are
8793supposed to work on the entries in a queue group.
8794Otherwise
8795.i sendmail
8796will work on the entries strictly sequentially.
8797.pp
8798The ``Interval'' field sets the time between queue runs.
8799If no queue group specific interval is set, then the parameter of the
8800.b -q
8801option from the command line is used.
8802.pp
8803To control the overall number of concurrently active queue runners
8804the option
8805.b MaxQueueChildren
8806can be set.
8807This limits the number of processes used for running the queues to
8808.b MaxQueueChildren ,
8809though at any one time fewer processes may be active
8810as a result of queue options, completed queue runs, system load, etc.
8811.pp
8812The maximum number of queue runners for an individual queue group can be
8813controlled via the
8814.b Runners
8815option.
8816If set to 0, entries in the queue will not be processed, which
8817is useful to ``quarantine'' queue files.
8818The number of runners per queue group may also be set with the option
8819.b MaxRunnersPerQueue ,
8820which applies to queue groups that have no individual limit.
8821That is, the default value for
8822.b Runners
8823is
8824.b MaxRunnersPerQueue
8825if set, otherwise 1.
8826.pp
8827The field Jobs describes the maximum number of jobs
8828(messages delivered) per queue run, which is the queue group specific
8829value of
8830.b MaxQueueRunSize .
8831.pp
8832Notice: queue groups should be declared after all queue related options
8833have been set because queue groups take their defaults from those options.
8834If an option is set after a queue group declaration, the values of
8835options in the queue group are set to the defaults of
8836.i sendmail
8837unless explicitly set in the declaration.
8838.pp
8839Each envelope is assigned to a queue group based on the algorithm
8840described in section
8841``Queue Groups and Queue Directories''.
8842.sh 2 "X \*- Mail Filter (Milter) Definitions"
8843.pp
8844The
8845.i sendmail
8846Mail Filter API (Milter) is designed to allow third-party programs access
8847to mail messages as they are being processed in order to filter
8848meta-information and content.
8849They are declared in the configuration file as:
8850.(b F
8851.b X \c
8852.i name
8853{, \c
8854.i field =\c
8855.i value \|}*
8856.)b
8857where
8858.i name
8859is the name of the filter
8860(used internally only)
8861and the
8862.q field=name
8863pairs define attributes of the filter.
8864Also see the documentation for the
8865.b InputMailFilters
8866option for more information.
8867.pp
8868Fields are:
8869.(b
8870.ta 1i
8871Socket The socket specification
8872Flags Special flags for this filter
8873Timeouts Timeouts for this filter
8874.)b
8875Only the first character of the field name is checked
8876(it's case-sensitive).
8877.pp
8878The socket specification is one of the following forms:
8879.(b F
8880.b S= \c
8881.b inet \c
8882.b :
8883.i port
8884.b @
8885.i host
8886.)b
8887.(b F
8888.b S= \c
8889.b inet6 \c
8890.b :
8891.i port
8892.b @
8893.i host
8894.)b
8895.(b F
8896.b S= \c
8897.b local \c
8898.b :
8899.i path
8900.)b
8901The first two describe an IPv4 or IPv6 socket listening on a certain
8902.i port
8903at a given
8904.i host
8905or IP address.
8906The final form describes a named socket on the filesystem at the given
8907.i path .
8908.pp
8909The following flags may be set in the filter description.
8910.nr ii 4n
8911.ip R
8912Reject connection if filter unavailable.
8913.ip T
8914Temporary fail connection if filter unavailable.
8915.pp
8916The timeouts can be set using the four fields inside of the
8917.b T=
8918equate:
8919.nr ii 4n
8920.ip C
8921Timeout for connecting to a filter.
8922If set to 0, the system's
8923.i connect()
8924timeout will be used.
8925.ip S
8926Timeout for sending information from the MTA to a filter.
8927.ip R
8928Timeout for reading reply from the filter.
8929.ip E
8930Overall timeout between sending end-of-message to filter and waiting for
8931the final acknowledgment.
8932.pp
8933Note the separator between each timeout field is a
8934.b ';' .
8935The default values (if not set) are:
8936.b T=C:5m;S:10s;R:10s;E:5m
8937where
8938.b s
8939is seconds and
8940.b m
8941is minutes.
8942.pp
8943Examples:
8944.(b
8945Xfilter1, S=local:/var/run/f1.sock, F=R
8946Xfilter2, S=inet6:999@localhost, F=T, T=S:1s;R:1s;E:5m
8947Xfilter3, S=inet:3333@localhost, T=C:2m
8948.)b
8949.sh 2 "The User Database"
8950.pp
8951The user database is deprecated in favor of ``virtusertable''
8952and ``genericstable'' as explained in the file
8953.b cf/README .
8954If you have a version of
8955.i sendmail
8956with the user database package
8957compiled in,
8958the handling of sender and recipient addresses
8959is modified.
8960.pp
8961The location of this database is controlled with the
8962.b UserDatabaseSpec
8963option.
8964.sh 3 "Structure of the user database"
8965.pp
8966The database is a sorted (BTree-based) structure.
8967User records are stored with the key:
8968.(b
8969\fIuser-name\fP\fB:\fP\fIfield-name\fP
8970.)b
8971The sorted database format ensures that user records are clustered together.
8972Meta-information is always stored with a leading colon.
8973.pp
8974Field names define both the syntax and semantics of the value.
8975Defined fields include:
8976.nr ii 1i
8977.ip maildrop
8978The delivery address for this user.
8979There may be multiple values of this record.
8980In particular,
8981mailing lists will have one
8982.i maildrop
8983record for each user on the list.
8984.ip "mailname"
8985The outgoing mailname for this user.
8986For each outgoing name,
8987there should be an appropriate
8988.i maildrop
8989record for that name to allow return mail.
8990See also
8991.i :default:mailname .
8992.ip mailsender
8993Changes any mail sent to this address to have the indicated envelope sender.
8994This is intended for mailing lists,
8995and will normally be the name of an appropriate -request address.
8996It is very similar to the owner-\c
8997.i list
8998syntax in the alias file.
8999.ip fullname
9000The full name of the user.
9001.ip office-address
9002The office address for this user.
9003.ip office-phone
9004The office phone number for this user.
9005.ip office-fax
9006The office FAX number for this user.
9007.ip home-address
9008The home address for this user.
9009.ip home-phone
9010The home phone number for this user.
9011.ip home-fax
9012The home FAX number for this user.
9013.ip project
9014A (short) description of the project this person is affiliated with.
9015In the University this is often just the name of their graduate advisor.
9016.ip plan
9017A pointer to a file from which plan information can be gathered.
9018.pp
9019As of this writing,
9020only a few of these fields are actually being used by
9021.i sendmail :
9022.i maildrop
9023and
9024.i mailname .
9025A
9026.i finger
9027program that uses the other fields is planned.
9028.sh 3 "User database semantics"
9029.pp
9030When the rewriting rules submit an address to the local mailer,
9031the user name is passed through the alias file.
9032If no alias is found (or if the alias points back to the same address),
9033the name (with
9034.q :maildrop
9035appended)
9036is then used as a key in the user database.
9037If no match occurs (or if the maildrop points at the same address),
9038forwarding is tried.
9039.pp
9040If the first token of the user name returned by ruleset 0
9041is an
9042.q @
9043sign, the user database lookup is skipped.
9044The intent is that the user database will act as a set of defaults
9045for a cluster (in our case, the Computer Science Division);
9046mail sent to a specific machine should ignore these defaults.
9047.pp
9048When mail is sent,
9049the name of the sending user is looked up in the database.
9050If that user has a
9051.q mailname
9052record,
9053the value of that record is used as their outgoing name.
9054For example, I might have a record:
9055.(b
9056eric:mailname Eric.Allman@CS.Berkeley.EDU
9057.)b
9058This would cause my outgoing mail to be sent as Eric.Allman.
9059.pp
9060If a
9061.q maildrop
9062is found for the user,
9063but no corresponding
9064.q mailname
9065record exists,
9066the record
9067.q :default:mailname
9068is consulted.
9069If present, this is the name of a host to override the local host.
9070For example, in our case we would set it to
9071.q CS.Berkeley.EDU .
9072The effect is that anyone known in the database
9073gets their outgoing mail stamped as
9074.q user@CS.Berkeley.EDU ,
9075but people not listed in the database use the local hostname.
9076.sh 3 "Creating the database\**"
9077.(f
9078\**These instructions are known to be incomplete.
9079Other features are available which provide similar functionality,
9080e.g., virtual hosting and mapping local addresses into a
9081generic form as explained in cf/README.
9082.)f
9083.pp
9084The user database is built from a text file
9085using the
9086.i makemap
9087utility
9088(in the distribution in the makemap subdirectory).
9089The text file is a series of lines corresponding to userdb records;
9090each line has a key and a value separated by white space.
9091The key is always in the format described above \*-
9092for example:
9093.(b
9094eric:maildrop
9095.)b
9096This file is normally installed in a system directory;
9097for example, it might be called
9098.i /etc/mail/userdb .
9099To make the database version of the map, run the program:
9100.(b
9101makemap btree /etc/mail/userdb < /etc/mail/userdb
9102.)b
9103Then create a config file that uses this.
9104For example, using the V8 M4 configuration, include the
9105following line in your .mc file:
9106.(b
9107define(\`confUSERDB_SPEC\', /etc/mail/userdb.db)
9108.)b
9109.sh 1 "OTHER CONFIGURATION"
9110.pp
9111There are some configuration changes that can be made by
9112recompiling
9113.i sendmail .
9114This section describes what changes can be made
9115and what has to be modified to make them.
9116In most cases this should be unnecessary
9117unless you are porting
9118.i sendmail
9119to a new environment.
9120.sh 2 "Parameters in devtools/OS/$oscf"
9121.pp
9122These parameters are intended to describe the compilation environment,
9123not site policy,
9124and should normally be defined in the operating system
9125configuration file.
9126.b "This section needs a complete rewrite."
9127.ip NDBM
9128If set,
9129the new version of the DBM library
9130that allows multiple databases will be used.
9131If neither NDBM nor NEWDB are set,
9132a much less efficient method of alias lookup is used.
9133.ip NEWDB
9134If set, use the new database package from Berkeley (from 4.4BSD).
9135This package is substantially faster than DBM or NDBM.
9136If NEWDB and NDBM are both set,
9137.i sendmail
9138will read DBM files,
9139but will create and use NEWDB files.
9140.ip NIS
9141Include support for NIS.
9142If set together with
9143.i both
9144NEWDB and NDBM,
9145.i sendmail
9146will create both DBM and NEWDB files if and only if
9147an alias file includes the substring
9148.q /yp/
9149in the name.
9150This is intended for compatibility with Sun Microsystems'
9151.i mkalias
9152program used on YP masters.
9153.ip NISPLUS
9154Compile in support for NIS+.
9155.ip NETINFO
9156Compile in support for NetInfo (NeXT stations).
9157.ip LDAPMAP
9158Compile in support for LDAP X500 queries.
9159Requires libldap and liblber
9160from the Umich LDAP 3.2 or 3.3 release
9161or equivalent libraries for other LDAP libraries
9162such as OpenLDAP.
9163.ip HESIOD
9164Compile in support for Hesiod.
9165.ip MAP_NSD
9166Compile in support for IRIX NSD lookups.
9167.ip MAP_REGEX
9168Compile in support for regular expression matching.
9169.ip DNSMAP
9170Compile in support for DNS map lookups in the
9171.i sendmail.cf
9172file.
9173.ip PH_MAP
9174Compile in support for ph lookups.
9175.ip SASL
9176Compile in support for SASL,
9177a required component for SMTP Authentication support.
9178.ip STARTTLS
9179Compile in support for STARTTLS.
9180.ip EGD
9181Compile in support for the "Entropy Gathering Daemon"
9182to provide better random data for TLS.
9183.ip TCPWRAPPERS
9184Compile in support for TCP Wrappers.
9185.ip _PATH_SENDMAILCF
9186The pathname of the sendmail.cf file.
9187.ip _PATH_SENDMAILPID
9188The pathname of the sendmail.pid file.
9189.ip SM_CONF_SHM
9190Compile in support for shared memory, see section about
9191"/var/spool/mqueue".
9192.ip MILTER
9193Compile in support for contacting external mail filters built with the
9194Milter API.
9195.pp
9196There are also several compilation flags to indicate the environment
9197such as
9198.q _AIX3
9199and
9200.q _SCO_unix_ .
9201See the sendmail/README
9202file for the latest scoop on these flags.
9203.sh 2 "Parameters in sendmail/conf.h"
9204.pp
9205Parameters and compilation options
9206are defined in conf.h.
9207Most of these need not normally be tweaked;
9208common parameters are all in sendmail.cf.
9209However, the sizes of certain primitive vectors, etc.,
9210are included in this file.
9211The numbers following the parameters
9212are their default value.
9213.pp
9214This document is not the best source of information
9215for compilation flags in conf.h \(em
9216see sendmail/README or sendmail/conf.h itself.
9217.nr ii 1.2i
9218.ip "MAXLINE [2048]"
9219The maximum line length of any input line.
9220If message lines exceed this length
9221they will still be processed correctly;
9222however, header lines,
9223configuration file lines,
9224alias lines,
9225etc.,
9226must fit within this limit.
9227.ip "MAXNAME [256]"
9228The maximum length of any name,
9229such as a host or a user name.
9230.ip "MAXPV [256]"
9231The maximum number of parameters to any mailer.
9232This limits the number of recipients that may be passed in one transaction.
9233It can be set to any arbitrary number above about 10,
9234since
9235.i sendmail
9236will break up a delivery into smaller batches as needed.
9237A higher number may reduce load on your system, however.
9238.ip "MAXQUEUEGROUPS [50]"
9239The maximum number of queue groups.
9240.ip "MAXATOM [1000]"
9241The maximum number of atoms
9242(tokens)
9243in a single address.
9244For example,
9245the address
9246.q "eric@CS.Berkeley.EDU"
9247is seven atoms.
9248.ip "MAXMAILERS [25]"
9249The maximum number of mailers that may be defined
9250in the configuration file.
9251This value is defined in include/sendmail/sendmail.h.
9252.ip "MAXRWSETS [200]"
9253The maximum number of rewriting sets
9254that may be defined.
9255The first half of these are reserved for numeric specification
9256(e.g., ``S92''),
9257while the upper half are reserved for auto-numbering
9258(e.g., ``Sfoo'').
9259Thus, with a value of 200 an attempt to use ``S99'' will succeed,
9260but ``S100'' will fail.
9261.ip "MAXPRIORITIES [25]"
9262The maximum number of values for the
9263.q Precedence:
9264field that may be defined
9265(using the
9266.b P
9267line in sendmail.cf).
9268.ip "MAXUSERENVIRON [100]"
9269The maximum number of items in the user environment
9270that will be passed to subordinate mailers.
9271.ip "MAXMXHOSTS [100]"
9272The maximum number of MX records we will accept for any single host.
9273.ip "MAXMAPSTACK [12]"
9274The maximum number of maps that may be "stacked" in a
9275.b sequence
9276class map.
9277.ip "MAXMIMEARGS [20]"
9278The maximum number of arguments in a MIME Content-Type: header;
9279additional arguments will be ignored.
9280.ip "MAXMIMENESTING [20]"
9281The maximum depth to which MIME messages may be nested
9282(that is, nested Message or Multipart documents;
9283this does not limit the number of components in a single Multipart document).
9284.ip "MAXDAEMONS [10]"
9285The maximum number of sockets sendmail will open for accepting connections
9286on different ports.
9287.ip "MAXMACNAMELEN [25]"
9288The maximum length of a macro name.
9289.lp
9290A number of other compilation options exist.
9291These specify whether or not specific code should be compiled in.
9292Ones marked with \(dg
9293are 0/1 valued.
9294.nr ii 1.2i
9295.ip NETINET\(dg
9296If set,
9297support for Internet protocol networking is compiled in.
9298Previous versions of
9299.i sendmail
9300referred to this as
9301.sm DAEMON ;
9302this old usage is now incorrect.
9303Defaults on;
9304turn it off in the Makefile
9305if your system doesn't support the Internet protocols.
9306.ip NETINET6\(dg
9307If set,
9308support for IPv6 networking is compiled in.
9309It must be separately enabled by adding DaemonPortOptions settings.
9310.ip NETISO\(dg
9311If set,
9312support for ISO protocol networking is compiled in
9313(it may be appropriate to #define this in the Makefile instead of conf.h).
9314.ip NETUNIX\(dg
9315If set,
9316support for UNIX domain sockets is compiled in.
9317This is used for control socket support.
9318.ip LOG
9319If set,
9320the
9321.i syslog
9322routine in use at some sites is used.
9323This makes an informational log record
9324for each message processed,
9325and makes a higher priority log record
9326for internal system errors.
9327.b "STRONGLY RECOMMENDED"
9328\(em if you want no logging, turn it off in the configuration file.
9329.ip MATCHGECOS\(dg
9330Compile in the code to do ``fuzzy matching'' on the GECOS field
9331in /etc/passwd.
9332This also requires that the
9333.b MatchGECOS
9334option be turned on.
9335.ip NAMED_BIND\(dg
9336Compile in code to use the
9337Berkeley Internet Name Domain (BIND) server
9338to resolve TCP/IP host names.
9339.ip NOTUNIX
9340If you are using a non-UNIX mail format,
9341you can set this flag to turn off special processing
9342of UNIX-style
9343.q "From "
9344lines.
9345.ip USERDB\(dg
9346Include the
9347.b experimental
9348Berkeley user information database package.
9349This adds a new level of local name expansion
9350between aliasing and forwarding.
9351It also uses the NEWDB package.
9352This may change in future releases.
9353.lp
9354The following options are normally turned on
9355in per-operating-system clauses in conf.h.
9356.ip IDENTPROTO\(dg
9357Compile in the IDENT protocol as defined in RFC 1413.
9358This defaults on for all systems except Ultrix,
9359which apparently has the interesting
9360.q feature
9361that when it receives a
9362.q "host unreachable"
9363message it closes all open connections to that host.
9364Since some firewall gateways send this error code
9365when you access an unauthorized port (such as 113, used by IDENT),
9366Ultrix cannot receive email from such hosts.
9367.ip SYSTEM5
9368Set all of the compilation parameters appropriate for System V.
9369.ip HASFLOCK\(dg
9370Use Berkeley-style
9371.b flock
9372instead of System V
9373.b lockf
9374to do file locking.
9375Due to the highly unusual semantics of locks
9376across forks in
9377.b lockf ,
9378this should always be used if at all possible.
9379.ip HASINITGROUPS
9380Set this if your system has the
9381.i initgroups()
9382call
9383(if you have multiple group support).
9384This is the default if SYSTEM5 is
9385.i not
9386defined or if you are on HPUX.
9387.ip HASUNAME
9388Set this if you have the
9389.i uname (2)
9390system call (or corresponding library routine).
9391Set by default if
9392SYSTEM5
9393is set.
9394.ip HASGETDTABLESIZE
9395Set this if you have the
9396.i getdtablesize (2)
9397system call.
9398.ip HASWAITPID
9399Set this if you have the
9400.i haswaitpid (2)
9401system call.
9402.ip FAST_PID_RECYCLE
9403Set this if your system can possibly
9404reuse the same pid in the same second of time.
9405.ip SFS_TYPE
9406The mechanism that can be used to get file system capacity information.
9407The values can be one of
9408SFS_USTAT (use the ustat(2) syscall),
9409SFS_4ARGS (use the four argument statfs(2) syscall),
9410SFS_VFS (use the two argument statfs(2) syscall including <sys/vfs.h>),
9411SFS_MOUNT (use the two argument statfs(2) syscall including <sys/mount.h>),
9412SFS_STATFS (use the two argument statfs(2) syscall including <sys/statfs.h>),
9413SFS_STATVFS (use the two argument statfs(2) syscall including <sys/statvfs.h>),
9414or
9415SFS_NONE (no way to get this information).
9416.ip LA_TYPE
9417The load average type.
9418Details are described below.
9419.lp
9420The are several built-in ways of computing the load average.
9421.i Sendmail
9422tries to auto-configure them based on imperfect guesses;
9423you can select one using the
9424.i cc
9425option
9426.b \-DLA_TYPE= \c
9427.i type ,
9428where
9429.i type
9430is:
9431.ip LA_INT
9432The kernel stores the load average in the kernel as an array of long integers.
9433The actual values are scaled by a factor FSCALE
9434(default 256).
9435.ip LA_SHORT
9436The kernel stores the load average in the kernel as an array of short integers.
9437The actual values are scaled by a factor FSCALE
9438(default 256).
9439.ip LA_FLOAT
9440The kernel stores the load average in the kernel as an array of
9441double precision floats.
9442.ip LA_MACH
9443Use MACH-style load averages.
9444.ip LA_SUBR
9445Call the
9446.i getloadavg
9447routine to get the load average as an array of doubles.
9448.ip LA_ZERO
9449Always return zero as the load average.
9450This is the fallback case.
9451.lp
9452If type
9453.sm LA_INT ,
9454.sm LA_SHORT ,
9455or
9456.sm LA_FLOAT
9457is specified,
9458you may also need to specify
9459.sm _PATH_UNIX
9460(the path to your system binary)
9461and
9462.sm LA_AVENRUN
9463(the name of the variable containing the load average in the kernel;
9464usually
9465.q _avenrun
9466or
9467.q avenrun ).
9468.sh 2 "Configuration in sendmail/conf.c"
9469.pp
9470The following changes can be made in conf.c.
9471.sh 3 "Built-in Header Semantics"
9472.pp
9473Not all header semantics are defined in the configuration file.
9474Header lines that should only be included by certain mailers
9475(as well as other more obscure semantics)
9476must be specified in the
9477.i HdrInfo
9478table in
9479.i conf.c .
9480This table contains the header name
9481(which should be in all lower case)
9482and a set of header control flags (described below),
9483The flags are:
9484.ip H_ACHECK
9485Normally when the check is made to see if a header line is compatible
9486with a mailer,
9487.i sendmail
9488will not delete an existing line.
9489If this flag is set,
9490.i sendmail
9491will delete
9492even existing header lines.
9493That is,
9494if this bit is set and the mailer does not have flag bits set
9495that intersect with the required mailer flags
9496in the header definition in
9497sendmail.cf,
9498the header line is
9499.i always
9500deleted.
9501.ip H_EOH
9502If this header field is set,
9503treat it like a blank line,
9504i.e.,
9505it will signal the end of the header
9506and the beginning of the message text.
9507.ip H_FORCE
9508Add this header entry
9509even if one existed in the message before.
9510If a header entry does not have this bit set,
9511.i sendmail
9512will not add another header line if a header line
9513of this name already existed.
9514This would normally be used to stamp the message
9515by everyone who handled it.
9516.ip H_TRACE
9517If set,
9518this is a timestamp
9519(trace)
9520field.
9521If the number of trace fields in a message
9522exceeds a preset amount
9523the message is returned
9524on the assumption that it has an aliasing loop.
9525.ip H_RCPT
9526If set,
9527this field contains recipient addresses.
9528This is used by the
9529.b \-t
9530flag to determine who to send to
9531when it is collecting recipients from the message.
9532.ip H_FROM
9533This flag indicates that this field
9534specifies a sender.
9535The order of these fields in the
9536.i HdrInfo
9537table specifies
9538.i sendmail 's
9539preference
9540for which field to return error messages to.
9541.ip H_ERRORSTO
9542Addresses in this header should receive error messages.
9543.ip H_CTE
9544This header is a Content-Transfer-Encoding header.
9545.ip H_CTYPE
9546This header is a Content-Type header.
9547.ip H_STRIPVAL
9548Strip the value from the header (for Bcc:).
9549.nr ii 5n
9550.lp
9551Let's look at a sample
9552.i HdrInfo
9553specification:
9554.(b
9555.ta 4n +\w'"content-transfer-encoding", 'u
9556struct hdrinfo HdrInfo[] =
9557\&{
9558 /* originator fields, most to least significant */
9559 "resent-sender", H_FROM,
9560 "resent-from", H_FROM,
9561 "sender", H_FROM,
9562 "from", H_FROM,
9563 "full-name", H_ACHECK,
9564 "errors-to", H_FROM\^|\^H_ERRORSTO,
9565 /* destination fields */
9566 "to", H_RCPT,
9567 "resent-to", H_RCPT,
9568 "cc", H_RCPT,
9569 "bcc", H_RCPT\^|\^H_STRIPVAL,
9570 /* message identification and control */
9571 "message", H_EOH,
9572 "text", H_EOH,
9573 /* trace fields */
9574 "received", H_TRACE\^|\^H_FORCE,
9575 /* miscellaneous fields */
9576 "content-transfer-encoding", H_CTE,
9577 "content-type", H_CTYPE,
9578
9579 NULL, 0,
9580};
9581.)b
9582This structure indicates that the
9583.q To: ,
9584.q Resent-To: ,
9585and
9586.q Cc:
9587fields
9588all specify recipient addresses.
9589Any
9590.q Full-Name:
9591field will be deleted unless the required mailer flag
9592(indicated in the configuration file)
9593is specified.
9594The
9595.q Message:
9596and
9597.q Text:
9598fields will terminate the header;
9599these are used by random dissenters around the network world.
9600The
9601.q Received:
9602field will always be added,
9603and can be used to trace messages.
9604.pp
9605There are a number of important points here.
9606First,
9607header fields are not added automatically just because they are in the
9608.i HdrInfo
9609structure;
9610they must be specified in the configuration file
9611in order to be added to the message.
9612Any header fields mentioned in the configuration file but not
9613mentioned in the
9614.i HdrInfo
9615structure have default processing performed;
9616that is,
9617they are added unless they were in the message already.
9618Second,
9619the
9620.i HdrInfo
9621structure only specifies cliched processing;
9622certain headers are processed specially by ad hoc code
9623regardless of the status specified in
9624.i HdrInfo .
9625For example,
9626the
9627.q Sender:
9628and
9629.q From:
9630fields are always scanned on ARPANET mail
9631to determine the sender\**;
9632.(f
9633\**Actually, this is no longer true in SMTP;
9634this information is contained in the envelope.
9635The older ARPANET protocols did not completely distinguish
9636envelope from header.
9637.)f
9638this is used to perform the
9639.q "return to sender"
9640function.
9641The
9642.q "From:"
9643and
9644.q "Full-Name:"
9645fields are used to determine the full name of the sender
9646if possible;
9647this is stored in the macro
9648.b $x
9649and used in a number of ways.
9650.sh 3 "Restricting Use of Email"
9651.pp
9652If it is necessary to restrict mail through a relay,
9653the
9654.i checkcompat
9655routine can be modified.
9656This routine is called for every recipient address.
9657It returns an exit status
9658indicating the status of the message.
9659The status
9660.sm EX_OK
9661accepts the address,
9662.sm EX_TEMPFAIL
9663queues the message for a later try,
9664and other values
9665(commonly
9666.sm EX_UNAVAILABLE )
9667reject the message.
9668It is up to
9669.i checkcompat
9670to print an error message
9671(using
9672.i usrerr )
9673if the message is rejected.
9674For example,
9675.i checkcompat
9676could read:
9677.(b
9678.re
9679.sz -1
9680.ta 4n +4n +4n +4n +4n +4n +4n
9681int
9682checkcompat(to, e)
9683 register ADDRESS *to;
9684 register ENVELOPE *e;
9685\&{
9686 register STAB *s;
9687
9688 s = stab("private", ST_MAILER, ST_FIND);
9689 if (s != NULL && e\->e_from.q_mailer != LocalMailer &&
9690 to->q_mailer == s->s_mailer)
9691 {
9692 usrerr("No private net mail allowed through this machine");
9693 return (EX_UNAVAILABLE);
9694 }
9695 if (MsgSize > 50000 && bitnset(M_LOCALMAILER, to\->q_mailer))
9696 {
9697 usrerr("Message too large for non-local delivery");
9698 e\->e_flags |= EF_NORETURN;
9699 return (EX_UNAVAILABLE);
9700 }
9701 return (EX_OK);
9702}
9703.sz
9704.)b
9705This would reject messages greater than 50000 bytes
9706unless they were local.
9707The
9708.i EF_NORETURN
9709flag can be set in
9710.i e\(->e_flags
9711to suppress the return of the actual body
9712of the message in the error return.
9713The actual use of this routine is highly dependent on the
9714implementation,
9715and use should be limited.
9716.sh 3 "New Database Map Classes"
9717.pp
9718New key maps can be added by creating a class initialization function
9719and a lookup function.
9720These are then added to the routine
9721.i setupmaps.
9722.pp
9723The initialization function is called as
9724.(b
9725\fIxxx\fP_map_init(MAP *map, char *args)
9726.)b
9727The
9728.i map
9729is an internal data structure.
9730The
9731.i args
9732is a pointer to the portion of the configuration file line
9733following the map class name;
9734flags and filenames can be extracted from this line.
9735The initialization function must return
9736.sm true
9737if it successfully opened the map,
9738.sm false
9739otherwise.
9740.pp
9741The lookup function is called as
9742.(b
9743\fIxxx\fP_map_lookup(MAP *map, char buf[], char **av, int *statp)
9744.)b
9745The
9746.i map
9747defines the map internally.
9748The
9749.i buf
9750has the input key.
9751This may be (and often is) used destructively.
9752The
9753.i av
9754is a list of arguments passed in from the rewrite line.
9755The lookup function should return a pointer to the new value.
9756If the map lookup fails,
9757.i *statp
9758should be set to an exit status code;
9759in particular, it should be set to
9760.sm EX_TEMPFAIL
9761if recovery is to be attempted by the higher level code.
9762.sh 3 "Queueing Function"
9763.pp
9764The routine
9765.i shouldqueue
9766is called to decide if a message should be queued
9767or processed immediately.
9768Typically this compares the message priority to the current load average.
9769The default definition is:
9770.(b
9771bool
9772shouldqueue(pri, ctime)
9773 long pri;
9774 time_t ctime;
9775{
9776 if (CurrentLA < QueueLA)
9777 return false;
9778 return (pri > (QueueFactor / (CurrentLA \- QueueLA + 1)));
9779}
9780.)b
9781If the current load average
9782(global variable
9783.i CurrentLA ,
9784which is set before this function is called)
9785is less than the low threshold load average
9786(option
9787.b x ,
9788variable
9789.i QueueLA ),
9790.i shouldqueue
9791returns
9792.sm false
9793immediately
9794(that is, it should
9795.i not
9796queue).
9797If the current load average exceeds the high threshold load average
9798(option
9799.b X ,
9800variable
9801.i RefuseLA ),
9802.i shouldqueue
9803returns
9804.sm true
9805immediately.
9806Otherwise, it computes the function based on the message priority,
9807the queue factor
9808(option
9809.b q ,
9810global variable
9811.i QueueFactor ),
9812and the current and threshold load averages.
9813.pp
9814An implementation wishing to take the actual age of the message into account
9815can also use the
9816.i ctime
9817parameter,
9818which is the time that the message was first submitted to
9819.i sendmail .
9820Note that the
9821.i pri
9822parameter is already weighted
9823by the number of times the message has been tried
9824(although this tends to lower the priority of the message with time);
9825the expectation is that the
9826.i ctime
9827would be used as an
9828.q "escape clause"
9829to ensure that messages are eventually processed.
9830.sh 3 "Refusing Incoming SMTP Connections"
9831.pp
9832The function
9833.i refuseconnections
9834returns
9835.sm true
9836if incoming SMTP connections should be refused.
9837The current implementation is based exclusively on the current load average
9838and the refuse load average option
9839(option
9840.b X ,
9841global variable
9842.i RefuseLA ):
9843.(b
9844bool
9845refuseconnections()
9846{
9847 return (RefuseLA > 0 && CurrentLA >= RefuseLA);
9848}
9849.)b
9850A more clever implementation
9851could look at more system resources.
9852.sh 3 "Load Average Computation"
9853.pp
9854The routine
9855.i getla
9856returns the current load average (as a rounded integer).
9857The distribution includes several possible implementations.
9858If you are porting to a new environment
9859you may need to add some new tweaks.\**
9860.(f
9861\**If you do, please send updates to
9862sendmail@Sendmail.ORG.
9863.)f
9864.sh 2 "Configuration in sendmail/daemon.c"
9865.pp
9866The file
9867.i sendmail/daemon.c
9868contains a number of routines that are dependent
9869on the local networking environment.
9870The version supplied assumes you have BSD style sockets.
9871.pp
9872In previous releases,
9873we recommended that you modify the routine
9874.i maphostname
9875if you wanted to generalize
9876.b $[
9877\&...\&
9878.b $]
9879lookups.
9880We now recommend that you create a new keyed map instead.
9881.sh 2 "STARTTLS"
9882.pp
9883In this section we assume that
9884.i sendmail
9885has been compiled with support for STARTTLS.
9886To properly understand the use of STARTTLS in
9887.i sendmail ,
9888it is necessary to understand at least some basics about X.509 certificates
9889and public key cryptography.
9890This information can be found in books about SSL/TLS
9891or on WWW sites, e.g.,
9892.q http://www.OpenSSL.org/ .
9893.sh 3 "Certificates for STARTTLS"
9894.pp
9895When acting as a server,
9896.i sendmail
9897requires X.509 certificates to support STARTTLS:
9898one as certificate for the server (ServerCertFile and corresponding
9899private ServerKeyFile)
9900at least one root CA (CACERTFile),
9901i.e., a certificate that is used to sign other certificates,
9902and a path to a directory which contains other CAs (CACERTPath).
9903The file specified via
9904CACERTFile
9905can contain several certificates of CAs.
9906The DNs of these certificates are sent
9907to the client during the TLS handshake (as part of the
9908CertificateRequest) as the list of acceptable CAs.
9909However, do not list too many root CAs in that file, otherwise
9910the TLS handshake may fail; e.g.,
9911.(b
9912error:14094417:SSL routines:SSL3_READ_BYTES:
9913sslv3 alert illegal parameter:s3_pkt.c:964:SSL alert number 47
9914.)b
9915You should probably put only the CA cert into that file
9916that signed your own cert(s), or at least only those you trust.
9917The CACERTPath directory must contain the hashes of each CA certificate
9918as filenames (or as links to them).
9919Symbolic links can be generated with the following
9920two (Bourne) shell commands:
9921.(b
9922C=FileName_of_CA_Certificate
9923ln -s $C `openssl x509 -noout -hash < $C`.0
9924.)b
9925An X.509 certificate is also required for authentication in client mode
9926(ClientCertFile and corresponding private ClientKeyFile), however,
9927.i sendmail
9928will always use STARTTLS when offered by a server.
9929The client and server certificates can be identical.
9930Certificates can be obtained from a certificate authority
9931or created with the help of OpenSSL.
9932The required format for certificates and private keys is PEM.
9933To allow for automatic startup of sendmail, private keys
9934(ServerKeyFile, ClientKeyFile)
9935must be stored unencrypted.
9936The keys are only protected by the permissions of the file system.
9937Never make a private key available to a third party.
9938.sh 3 "PRNG for STARTTLS"
9939.pp
9940STARTTLS requires a strong pseudo random number generator (PRNG)
9941to operate properly.
9942Depending on the TLS library you use, it may be required to explicitly
9943initialize the PRNG with random data.
9944OpenSSL makes use of
9945.b /dev/urandom(4)
9946if available (this corresponds to the compile flag HASURANDOMDEV).
9947On systems which lack this support, a random file must be specified in the
9948.i sendmail.cf
9949file using the option RandFile.
9950It is
9951.b strongly
9952advised to use the "Entropy Gathering Daemon" EGD
9953from Brian Warner on those systems to provide useful random data.
9954In this case,
9955.i sendmail
9956must be compiled with the flag EGD, and the
9957RandFile option must point to the EGD socket.
9958If neither
9959.b /dev/urandom(4)
9960nor EGD are available, you have to make sure
9961that useful random data is available all the time in RandFile.
9962If the file hasn't been modified in the last 10 minutes before
9963it is supposed to be used by
9964.i sendmail
9965the content is considered obsolete.
9966One method for generating this file is:
9967.(b
9968openssl rand -out /etc/mail/randfile -rand \c
9969.i /path/to/file:... \c
9970256
9971.)b
9972See the OpenSSL documentation for more information.
9973In this case, the PRNG for TLS is only
9974seeded with other random data if the
9975.b DontBlameSendmail
9976option
9977.b InsufficientEntropy
9978is set.
9979This is most likely not sufficient for certain actions, e.g.,
9980generation of (temporary) keys.
9981.pp
9982Please see the OpenSSL documentation or other sources
9983for further information about certificates, their creation and their usage,
9984the importance of a good PRNG, and other aspects of TLS.
9985.sh 1 "ACKNOWLEDGEMENTS"
9986.pp
9987I've worked on
9988.i sendmail
9989for many years,
9990and many employers have been remarkably patient
9991about letting me work on a large project
9992that was not part of my official job.
9993This includes time on the INGRES Project at
9994the University of California at Berkeley,
9995at Britton Lee,
9996and again on the Mammoth and Titan Projects at Berkeley.
9997.pp
9998Much of the second wave of improvements
9999resulting in version 8.1
10000should be credited to Bryan Costales of the
10001International Computer Science Institute.
10002As he passed me drafts of his book on
10003.i sendmail
10004I was inspired to start working on things again.
10005Bryan was also available to bounce ideas off of.
10006.pp
10007Gregory Neil Shapiro
10008of Worcester Polytechnic Institute
10009has become instrumental in all phases of
10010.i sendmail
10011support and development,
10012and was largely responsible for getting versions 8.8 and 8.9
10013out the door.
10014.pp
10015Many, many people contributed chunks of code and ideas to
10016.i sendmail .
10017It has proven to be a group network effort.
10018Version 8 in particular was a group project.
10019The following people and organizations made notable contributions:
10020.(l
10021Claus Assmann
10022John Beck, Hewlett-Packard & Sun Microsystems
10023Keith Bostic, CSRG, University of California, Berkeley
10024Andrew Cheng, Sun Microsystems
10025Michael J. Corrigan, University of California, San Diego
10026Bryan Costales, International Computer Science Institute & InfoBeat
10027Pa\*:r (Pell) Emanuelsson
10028Craig Everhart, Transarc Corporation
10029Per Hedeland, Ericsson
10030Tom Ivar Helbekkmo, Norwegian School of Economics
10031Kari Hurtta, Finnish Meteorological Institute
10032Allan E. Johannesen, WPI
10033Jonathan Kamens, OpenVision Technologies, Inc.
10034Takahiro Kanbe, Fuji Xerox Information Systems Co., Ltd.
10035Brian Kantor, University of California, San Diego
10036John Kennedy, Cal State University, Chico
10037Murray S. Kucherawy, HookUp Communication Corp.
10038Bruce Lilly, Sony U.S.
10039Karl London
10040Motonori Nakamura, Ritsumeikan University & Kyoto University
10041John Gardiner Myers, Carnegie Mellon University
10042Neil Rickert, Northern Illinois University
10043Gregory Neil Shapiro, WPI
10044Eric Schnoebelen, Convex Computer Corp.
10045Eric Wassenaar, National Institute for Nuclear and High Energy Physics, Amsterdam
10046Randall Winchester, University of Maryland
10047Christophe Wolfhugel, Pasteur Institute & Herve Schauer Consultants (Paris)
10048Exactis.com, Inc.
10049.)l
10050I apologize for anyone I have omitted, misspelled, misattributed, or
10051otherwise missed.
10052At this point, I suspect that at least a hundred people
10053have contributed code,
10054and many more have contributed ideas, comments, and encouragement.
10055I've tried to list them in the RELEASE_NOTES in the distribution directory.
10056I appreciate their contribution as well.
10057.pp
10058Special thanks are reserved for Michael Corrigan and Christophe Wolfhugel,
10059who besides being wonderful guinea pigs and contributors
10060have also consented to be added to the ``sendmail@Sendmail.ORG'' list
10061and, by answering the bulk of the questions sent to that list,
10062have freed me up to do other work.
10063.++ A
10064.+c "COMMAND LINE FLAGS"
10065.ba 0
10066.nr ii 1i
10067.pp
10068Arguments must be presented with flags before addresses.
10069The flags are:
10070.ip \-A\fIx\fP
10071Select an alternative .cf file which is either
10072.i sendmail.cf
10073for
10074.b \-Am
10075or
10076.i submit.cf
10077for
10078.b \-Ac .
10079By default the .cf file is chosen based on the operation mode.
10080For
10081.b -bm
10082(default),
10083.b -bs ,
10084and
10085.b -t
10086it is
10087.i submit.cf
10088if it exists, for all others it is
10089.i sendmail.cf .
10090.ip \-b\fIx\fP
10091Set operation mode to
10092.i x .
10093Operation modes are:
10094.(b
10095.ta 4n
10096m Deliver mail (default)
10097s Speak SMTP on input side
10098a\(dg ``Arpanet'' mode (get envelope sender information from header)
10099d Run as a daemon in background
10100D Run as a daemon in foreground
10101t Run in test mode
10102v Just verify addresses, don't collect or deliver
10103i Initialize the alias database
10104p Print the mail queue
10105P Print overview over the mail queue (requires shared memory)
10106h Print the persistent host status database
10107H Purge expired entries from the persistent host status database
10108.)b
10109.(f
10110\(dgDeprecated.
10111.)f
10112.ip \-B\fItype\fP
10113Indicate body type.
10114.ip \-C\fIfile\fP
10115Use a different configuration file.
10116.i Sendmail
10117runs as the invoking user (rather than root)
10118when this flag is specified.
10119.ip \-d\fIlevel\fP
10120Set debugging level.
10121.ip "\-f\ \fIaddr\fP"
10122The envelope sender address is set to
10123.i addr .
10124This address may also be used in the From: header
10125if that header is missing during initial submission.
10126The envelope sender address is used as the recipient
10127for delivery status notifications
10128and may also appear in a Return-Path: header.
10129.ip \-F\ \fIname\fP
10130Sets the full name of this user to
10131.i name .
10132.ip \-G
10133When accepting messages via the command line,
10134indicate that they are for relay (gateway) submission.
10135sendmail may complain about syntactically invalid messages,
10136e.g., unqualified host names,
10137rather than fixing them when this flag is set.
10138sendmail will not do any canonicalization in this mode.
10139.ip "\-h\ \fIcnt\fP"
10140Sets the
10141.q "hop count"
10142to
10143.i cnt .
10144This represents the number of times this message has been processed
10145by
10146.i sendmail
10147(to the extent that it is supported by the underlying networks).
10148.i Cnt
10149is incremented during processing,
10150and if it reaches
10151MAXHOP
10152(currently 25)
10153.i sendmail
10154throws away the message with an error.
10155.ip "\-L \fItag\fP"
10156Sets the identifier used for syslog.
10157Note that this identifier is set
10158as early as possible.
10159However,
10160.i sendmail
10161may be used
10162if problems arise
10163before the command line arguments
10164are processed.
10165.ip \-n
10166Don't do aliasing or forwarding.
10167.ip "\-N \fInotifications\fP"
10168Tag all addresses being sent as wanting the indicated
10169.i notifications ,
10170which consists of the word
10171.q NEVER
10172or a comma-separated list of
10173.q SUCCESS ,
10174.q FAILURE ,
10175and
10176.q DELAY
10177for successful delivery,
10178failure,
10179and a message that is stuck in a queue somewhere.
10180The default is
10181.q FAILURE,DELAY .
10182.ip "\-r\ \fIaddr\fP"
10183An obsolete form of
10184.b \-f .
10185.ip \-o\fIx\|value\fP
10186Set option
10187.i x
10188to the specified
10189.i value .
10190These options are described in Section 5.6.
10191.ip \-O\fIoption\fP\fB=\fP\fIvalue\fP
10192Set
10193.i option
10194to the specified
10195.i value
10196(for long form option names).
10197These options are described in Section 5.6.
10198.ip \-M\fIx\|value\fP
10199Set macro
10200.i x
10201to the specified
10202.i value .
10203.ip \-p\fIprotocol\fP
10204Set the sending protocol.
10205Programs are encouraged to set this.
10206The protocol field can be in the form
10207.i protocol \c
10208.b : \c
10209.i host
10210to set both the sending protocol and sending host.
10211For example,
10212.q \-pUUCP:uunet
10213sets the sending protocol to UUCP
10214and the sending host to uunet.
10215(Some existing programs use \-oM to set the r and s macros;
10216this is equivalent to using \-p.)
10217.ip \-q\fItime\fP
10218Try to process the queued up mail.
10219If the time is given,
10220a
10221.i sendmail
10222will start one or more processes to run through the queue(s) at the specified
10223time interval to deliver queued mail; otherwise, it only runs once.
10224Each of these processes acts on a workgroup.
10225These processes are also known as workgroup processes or WGP's for short.
10226Each workgroup is responsible for controlling the processing of one or
10227more queues; workgroups help manage the use of system resources by sendmail.
10228Each workgroup may have one or more children concurrently processing
10229queues depending on the setting of \fIMaxQueueChildren\fP.
10230.ip \-qp\fItime\fP
10231Similar to \-q with a time argument,
10232except that instead of periodically starting WGP's
10233sendmail starts persistent WGP's
10234that alternate between processing queues and sleeping.
10235The sleep time is specified by the time argument; it defaults to 1 second,
10236except that a WGP always sleeps at least 5 seconds if their queues were
10237empty in the previous run.
10238Persistent processes are managed by a queue control process (QCP).
10239The QCP is the parent process of the WGP's.
10240Typically the QCP will be the sendmail daemon (when started with \-bd or \-bD)
10241or a special process (named Queue control) (when started without \-bd or \-bD).
10242If a persistent WGP ceases to be active for some reason
10243another WGP will be started by the QCP for the same workgroup
10244in most cases. When a persistent WGP has core dumped, the debug flag
10245\fIno_persistent_restart\fP is set or the specific persistent WGP has been
10246restarted too many times already then the WGP will not be started again
10247and a message will be logged to this effect.
10248To stop (SIGTERM) or restart (SIGHUP) persistent WGP's the appropriate
10249signal should be sent to the QCP. The QCP will propagate the signal to all of
10250the WGP's and if appropriate restart the persistent WGP's.
10251.ip \-q\fIGname\fP
10252Run the jobs in the queue group
10253.i name
10254once.
10255.ip \-q[!]\fIXstring\fP
10256Run the queue once,
10257limiting the jobs to those matching
10258.i Xstring .
10259The key letter
10260.i X
10261can be
10262.b I
10263to limit based on queue identifier,
10264.b R
10265to limit based on recipient,
10266or
10267.b S
10268to limit based on sender.
10269A particular queued job is accepted if one of the corresponding addresses
10270contains the indicated
10271.i string .
10272The optional ! character negates the condition tested.
10273Multiple
10274.i \-q\fIX\fP
10275flags are permitted,
10276with items with the same key letter
10277.q or'ed
10278together, and items with different key letters
10279.q and'ed
10280together.
10281.ip "\-R ret"
10282What information you want returned if the message bounces;
10283.i ret
10284can be
10285.q HDRS
10286for headers only or
10287.q FULL
10288for headers plus body.
10289This is a request only;
10290the other end is not required to honor the parameter.
10291If
10292.q HDRS
10293is specified local bounces also return only the headers.
10294.ip \-t
10295Read the header for
10296.q To: ,
10297.q Cc: ,
10298and
10299.q Bcc:
10300lines, and send to everyone listed in those lists.
10301The
10302.q Bcc:
10303line will be deleted before sending.
10304Any addresses in the argument vector will be deleted
10305from the send list.
10306.ip "\-V envid"
10307The indicated
10308.i envid
10309is passed with the envelope of the message
10310and returned if the message bounces.
10311.ip "\-X \fIlogfile\fP"
10312Log all traffic in and out of
10313.i sendmail
10314in the indicated
10315.i logfile
10316for debugging mailer problems.
10317This produces a lot of data very quickly and should be used sparingly.
10318.pp
10319There are a number of options that may be specified as
10320primitive flags.
10321These are the e, i, m, and v options.
10322Also,
10323the f option
10324may be specified as the
10325.b \-s
10326flag.
10327The DSN related options
10328.q "\-N" ,
10329.q "\-R" ,
10330and
10331.q "\-V"
10332have no effects on
10333.i sendmail
10334running as daemon.
10335.+c "QUEUE FILE FORMATS"
10336.pp
10337This appendix describes the format of the queue files.
10338These files live in a queue directory.
10339The individual qf, df, and xf files
10340may be stored in separate
10341.i qf/ ,
10342.i df/ ,
10343and
10344.i xf/
10345subdirectories
10346if they are present in the queue directory.
10347.pp
10348All queue files have the name
10349.i ttYMDhmsNNppppp
10350where
10351.i YMDhmsNNppppp
10352is the
10353.i id
10354for this message
10355and the
10356.i tt
10357is a type.
10358The individual letters in the
10359.i id
10360are:
10361.nr ii 0.5i
10362.ip Y
10363Encoded year
10364.ip M
10365Encoded month
10366.ip D
10367Encoded day
10368.ip h
10369Encoded hour
10370.ip m
10371Encoded minute
10372.ip s
10373Encoded second
10374.ip NN
10375Encoded envelope number
10376.ip ppppp
10377At least five decimal digits of the process ID
10378.pp
10379All files with the same id collectively define one message.
10380Due to the use of memory-buffered files,
10381some of these files may never appear on disk.
10382.pp
10383The types are:
10384.nr ii 0.5i
10385.ip qf
10386The queue control file.
10387This file contains the information necessary to process the job.
10388.ip df
10389The data file.
10390The message body (excluding the header) is kept in this file.
10391Sometimes the df file is not stored in the same directory as the qf file;
10392in this case,
10393the qf file contains a `d' record which names the queue directory
10394that contains the df file.
10395.ip tf
10396A temporary file.
10397This is an image of the
10398.b qf
10399file when it is being rebuilt.
10400It should be renamed to a
10401.b qf
10402file very quickly.
10403.ip xf
10404A transcript file,
10405existing during the life of a session
10406showing everything that happens
10407during that session.
10408Sometimes the xf file must be generated before a queue group has been selected;
10409in this case,
10410the xf file will be stored in a directory of the default queue group.
10411.ip Qf
10412A ``lost'' queue control file.
10413.i sendmail
10414renames a
10415.b qf
10416file to
10417.b Qf
10418if there is a severe (configuration) problem that cannot be solved without
10419human intervention.
10420Search the logfile for the queue file id to figure out what happened.
10421After you resolved the problem, you can rename the
10422.b Qf
10423file to
10424.b qf
10425and send it again.
10426.pp
10427The
10428.b qf
10429file is structured as a series of lines
10430each beginning with a code letter.
10431The lines are as follows:
10432.ip V
10433The version number of the queue file format,
10434used to allow new
10435.i sendmail
10436binaries to read queue files created by older versions.
10437Defaults to version zero.
10438Must be the first line of the file if present.
10439For 8.12 the version number is 6.
10440.ip A
10441The information given by the AUTH= parameter of the
10442.q "MAIL FROM:"
10443command or $f@$j
10444if sendmail has been called directly.
10445.ip H
10446A header definition.
10447There may be any number of these lines.
10448The order is important:
10449they represent the order in the final message.
10450These use the same syntax
10451as header definitions in the configuration file.
10452.ip C
10453The controlling address.
10454The syntax is
10455.q localuser:aliasname .
10456Recipient addresses following this line
10457will be flagged so that deliveries will be run as the
10458.i localuser
10459(a user name from the /etc/passwd file);
10460.i aliasname
10461is the name of the alias that expanded to this address
10462(used for printing messages).
10463.ip Q
10464The ``original recipient'',
10465specified by the ORCPT= field in an ESMTP transaction.
10466Used exclusively for Delivery Status Notifications.
10467It applies only to the following `R' line.
10468.ip r
10469The ``final recipient''
10470used for Delivery Status Notifications.
10471It applies only to the following `R' line.
10472.ip R
10473A recipient address.
10474This will normally be completely aliased,
10475but is actually realiased when the job is processed.
10476There will be one line for each recipient.
10477Version 1 qf files
10478also include a leading colon-terminated list of flags,
10479which can be
10480`S' to return a message on successful final delivery,
10481`F' to return a message on failure,
10482`D' to return a message if the message is delayed,
10483`B' to indicate that the body should be returned,
10484`N' to suppress returning the body,
10485and
10486`P' to declare this as a ``primary'' (command line or SMTP-session) address.
10487.ip S
10488The sender address.
10489There may only be one of these lines.
10490.ip T
10491The job creation time.
10492This is used to compute when to time out the job.
10493.ip P
10494The current message priority.
10495This is used to order the queue.
10496Higher numbers mean lower priorities.
10497The priority changes
10498as the message sits in the queue.
10499The initial priority depends on the message class
10500and the size of the message.
10501.ip M
10502A message.
10503This line is printed by the
10504.i mailq
10505command,
10506and is generally used to store status information.
10507It can contain any text.
10508.ip F
10509Flag bits, represented as one letter per flag.
10510Defined flag bits are
10511.b r
10512indicating that this is a response message
10513and
10514.b w
10515indicating that a warning message has been sent
10516announcing that the mail has been delayed.
10517Other flag bits are:
10518.b 8 :
10519the body contains 8bit data,
10520.b b :
10521a Bcc: header should be removed,
10522.b d :
10523the mail has RET parameters (see RFC 1894),
10524.b n :
10525the body of the message should not be returned
10526in case of an error,
10527.b s :
10528the envelope has been split.
10529.ip N
10530The total number of delivery attempts.
10531.ip K
10532The time (as seconds since January 1, 1970)
10533of the last delivery attempt.
10534.ip d
10535If the df file is in a different directory than the qf file,
10536then a `d' record is present,
10537specifying the directory in which the df file resides.
10538.ip I
10539The i-number of the data file;
10540this can be used to recover your mail queue
10541after a disastrous disk crash.
10542.ip $
10543A macro definition.
10544The values of certain macros
10545are passed through to the queue run phase.
10546.ip B
10547The body type.
10548The remainder of the line is a text string defining the body type.
10549If this field is missing,
10550the body type is assumed to be
10551.q "undefined"
10552and no special processing is attempted.
10553Legal values are
10554.q 7BIT
10555and
10556.q 8BITMIME .
10557.ip Z
10558The original envelope id (from the ESMTP transaction).
10559For Deliver Status Notifications only.
10560.pp
10561As an example,
10562the following is a queue file sent to
10563.q eric@mammoth.Berkeley.EDU
10564and
10565.q bostic@okeeffe.CS.Berkeley.EDU \**:
10566.(f
10567\**This example is contrived and probably inaccurate for your environment.
10568Glance over it to get an idea;
10569nothing can replace looking at what your own system generates.
10570.)f
10571.(b
10572V4
10573T711358135
10574K904446490
10575N0
10576P2100941
10577$_eric@localhost
10578${daemon_flags}
10579Seric
10580Ceric:100:1000:sendmail@vangogh.CS.Berkeley.EDU
10581RPFD:eric@mammoth.Berkeley.EDU
10582RPFD:bostic@okeeffe.CS.Berkeley.EDU
10583H?P?Return-path: <^g>
10584H??Received: by vangogh.CS.Berkeley.EDU (5.108/2.7) id AAA06703;
10585 Fri, 17 Jul 1992 00:28:55 -0700
10586H??Received: from mail.CS.Berkeley.EDU by vangogh.CS.Berkeley.EDU (5.108/2.7)
10587 id AAA06698; Fri, 17 Jul 1992 00:28:54 -0700
10588H??Received: from [128.32.31.21] by mail.CS.Berkeley.EDU (5.96/2.5)
10589 id AA22777; Fri, 17 Jul 1992 03:29:14 -0400
10590H??Received: by foo.bar.baz.de (5.57/Ultrix3.0-C)
10591 id AA22757; Fri, 17 Jul 1992 09:31:25 GMT
10592H?F?From: eric@foo.bar.baz.de (Eric Allman)
10593H?x?Full-name: Eric Allman
10594H??Message-id: <9207170931.AA22757@foo.bar.baz.de>
10595H??To: sendmail@vangogh.CS.Berkeley.EDU
10596H??Subject: this is an example message
10597.)b
10598This shows
10599the person who sent the message,
10600the submission time
10601(in seconds since January 1, 1970),
10602the message priority,
10603the message class,
10604the recipients,
10605and the headers for the message.
10606.+c "SUMMARY OF SUPPORT FILES"
10607.pp
10608This is a summary of the support files
10609that
10610.i sendmail
10611creates or generates.
10612Many of these can be changed by editing the sendmail.cf file;
10613check there to find the actual pathnames.
10614.nr ii 1i
10615.ip "/usr/\*(SD/sendmail"
10616The binary of
10617.i sendmail .
10618.ip /usr/\*(SB/newaliases
10619A link to /usr/\*(SD/sendmail;
10620causes the alias database to be rebuilt.
10621Running this program is completely equivalent to giving
10622.i sendmail
10623the
10624.b \-bi
10625flag.
10626.ip /usr/\*(SB/mailq
10627Prints a listing of the mail queue.
10628This program is equivalent to using the
10629.b \-bp
10630flag to
10631.i sendmail .
10632.ip /etc/mail/sendmail.cf
10633The configuration file,
10634in textual form.
10635.ip /etc/mail/helpfile
10636The SMTP help file.
10637.ip /etc/mail/statistics
10638A statistics file; need not be present.
10639.ip /etc/mail/sendmail.pid
10640Created in daemon mode;
10641it contains the process id of the current SMTP daemon.
10642If you use this in scripts;
10643use ``head \-1'' to get just the first line;
10644the second line contains the command line used to invoke the daemon,
10645and later versions of
10646.i sendmail
10647may add more information to subsequent lines.
10648.ip /etc/mail/aliases
10649The textual version of the alias file.
10650.ip /etc/mail/aliases.db
10651The alias file in
10652.i hash \|(3)
10653format.
10654.ip /etc/mail/aliases.{pag,dir}
10655The alias file in
10656.i ndbm \|(3)
10657format.
10658.ip /var/spool/mqueue
10659The directory in which the mail queue(s)
10660and temporary files reside.
10661.ip /var/spool/mqueue/qf*
10662Control (queue) files for messages.
10663.ip /var/spool/mqueue/df*
10664Data files.
10665.ip /var/spool/mqueue/tf*
10666Temporary versions of the qf files,
10667used during queue file rebuild.
10668.ip /var/spool/mqueue/xf*
10669A transcript of the current session.
10670.if o \
10671\{\
10672. bp
10673. rs
10674. sp |4i
10675. ce 2
10676This page intentionally left blank;
10677replace it with a blank sheet for double-sided output.
10678.\}
10679.\".ro
10680.\".ls 1
10681.\".tp
10682.\".sp 2i
10683.\".in 0
10684.\".ce 100
10685.\".sz 24
10686.\".b SENDMAIL
10687.\".sz 14
10688.\".sp
10689.\"INSTALLATION AND OPERATION GUIDE
10690.\".sp
10691.\".sz 10
10692.\"Eric Allman
10693.\".sp
|
10674.\"Version $Revision: 8.609.2.2 $
| 10694.\"Version $Revision: 8.609.2.5 $
|
10675.\".ce 0
10676.bp 3
10677.ce
10678.sz 12
10679TABLE OF CONTENTS
10680.sz 10
10681.sp
10682.\" remove some things to avoid "out of temp file space" problem
10683.rm sh
10684.rm (x
10685.rm )x
10686.rm ip
10687.rm pp
10688.rm lp
10689.rm he
10690.rm fo
10691.rm eh
10692.rm oh
10693.rm ef
10694.rm of
10695.xp
10696.if o \
10697\{\
10698. bp
10699. rs
10700. sp |4i
10701. ce 2
10702This page intentionally left blank;
10703replace it with a blank sheet for double-sided output.
10704.\}
| 10695.\".ce 0
10696.bp 3
10697.ce
10698.sz 12
10699TABLE OF CONTENTS
10700.sz 10
10701.sp
10702.\" remove some things to avoid "out of temp file space" problem
10703.rm sh
10704.rm (x
10705.rm )x
10706.rm ip
10707.rm pp
10708.rm lp
10709.rm he
10710.rm fo
10711.rm eh
10712.rm oh
10713.rm ef
10714.rm of
10715.xp
10716.if o \
10717\{\
10718. bp
10719. rs
10720. sp |4i
10721. ce 2
10722This page intentionally left blank;
10723replace it with a blank sheet for double-sided output.
10724.\}
|