Merge from vendor branch GCC:
[dragonfly.git] / contrib / sendmail-8.13.4 / cf / README
1
2                 SENDMAIL CONFIGURATION FILES
3
4 This document describes the sendmail configuration files.  It
5 explains how to create a sendmail.cf file for use with sendmail.
6 It also describes how to set options for sendmail which are explained
7 in the Sendmail Installation and Operation guide (doc/op/op.me).
8
9 To get started, you may want to look at tcpproto.mc (for TCP-only
10 sites) and clientproto.mc (for clusters of clients using a single
11 mail host), or the generic-*.mc files as operating system-specific
12 examples.
13
14 Table of Content:
15
16 INTRODUCTION AND EXAMPLE
17 A BRIEF INTRODUCTION TO M4
18 FILE LOCATIONS
19 OSTYPE
20 DOMAINS
21 MAILERS
22 FEATURES
23 HACKS
24 SITE CONFIGURATION
25 USING UUCP MAILERS
26 TWEAKING RULESETS
27 MASQUERADING AND RELAYING
28 USING LDAP FOR ALIASES, MAPS, AND CLASSES
29 LDAP ROUTING
30 ANTI-SPAM CONFIGURATION CONTROL
31 CONNECTION CONTROL
32 STARTTLS
33 SMTP AUTHENTICATION
34 ADDING NEW MAILERS OR RULESETS
35 ADDING NEW MAIL FILTERS
36 QUEUE GROUP DEFINITIONS
37 NON-SMTP BASED CONFIGURATIONS
38 WHO AM I?
39 ACCEPTING MAIL FOR MULTIPLE NAMES
40 USING MAILERTABLES
41 USING USERDB TO MAP FULL NAMES
42 MISCELLANEOUS SPECIAL FEATURES
43 SECURITY NOTES
44 TWEAKING CONFIGURATION OPTIONS
45 MESSAGE SUBMISSION PROGRAM
46 FORMAT OF FILES AND MAPS
47 DIRECTORY LAYOUT
48 ADMINISTRATIVE DETAILS
49
50
51 +--------------------------+
52 | INTRODUCTION AND EXAMPLE |
53 +--------------------------+
54
55 Configuration files are contained in the subdirectory "cf", with a
56 suffix ".mc".  They must be run through "m4" to produce a ".cf" file.
57 You must pre-load "cf.m4":
58
59         m4 ${CFDIR}/m4/cf.m4 config.mc > config.cf
60
61 Alternatively, you can simply:
62
63         cd ${CFDIR}/cf
64         ./Build config.cf
65
66 where ${CFDIR} is the root of the cf directory and config.mc is the
67 name of your configuration file.  If you are running a version of M4
68 that understands the __file__ builtin (versions of GNU m4 >= 0.75 do
69 this, but the versions distributed with 4.4BSD and derivatives do not)
70 or the -I flag (ditto), then ${CFDIR} can be in an arbitrary directory.
71 For "traditional" versions, ${CFDIR} ***MUST*** be "..", or you MUST
72 use -D_CF_DIR_=/path/to/cf/dir/ -- note the trailing slash!  For example:
73
74         m4 -D_CF_DIR_=${CFDIR}/ ${CFDIR}/m4/cf.m4 config.mc > config.cf
75
76 Let's examine a typical .mc file:
77
78         divert(-1)
79         #
80         # Copyright (c) 1998-2004 Sendmail, Inc. and its suppliers.
81         #       All rights reserved.
82         # Copyright (c) 1983 Eric P. Allman.  All rights reserved.
83         # Copyright (c) 1988, 1993
84         #       The Regents of the University of California.  All rights reserved.
85         #
86         # By using this file, you agree to the terms and conditions set
87         # forth in the LICENSE file which can be found at the top level of
88         # the sendmail distribution.
89         #
90
91         #
92         #  This is a Berkeley-specific configuration file for HP-UX 9.x.
93         #  It applies only to the Computer Science Division at Berkeley,
94         #  and should not be used elsewhere.   It is provided on the sendmail
95         #  distribution as a sample only.  To create your own configuration
96         #  file, create an appropriate domain file in ../domain, change the
97         #  `DOMAIN' macro below to reference that file, and copy the result
98         #  to a name of your own choosing.
99         #
100         divert(0)
101
102 The divert(-1) will delete the crud in the resulting output file.
103 The copyright notice can be replaced by whatever your lawyers require;
104 our lawyers require the one that is included in these files.  A copyleft
105 is a copyright by another name.  The divert(0) restores regular output.
106
107         VERSIONID(`<SCCS or RCS version id>')
108
109 VERSIONID is a macro that stuffs the version information into the
110 resulting file.  You could use SCCS, RCS, CVS, something else, or
111 omit it completely.  This is not the same as the version id included
112 in SMTP greeting messages -- this is defined in m4/version.m4.
113
114         OSTYPE(`hpux9')dnl
115
116 You must specify an OSTYPE to properly configure things such as the
117 pathname of the help and status files, the flags needed for the local
118 mailer, and other important things.  If you omit it, you will get an
119 error when you try to build the configuration.  Look at the ostype
120 directory for the list of known operating system types.
121
122         DOMAIN(`CS.Berkeley.EDU')dnl
123
124 This example is specific to the Computer Science Division at Berkeley.
125 You can use "DOMAIN(`generic')" to get a sufficiently bland definition
126 that may well work for you, or you can create a customized domain
127 definition appropriate for your environment.
128
129         MAILER(`local')
130         MAILER(`smtp')
131
132 These describe the mailers used at the default CS site.  The local
133 mailer is always included automatically.  Beware: MAILER declarations
134 should only be followed by LOCAL_* sections.  The general rules are
135 that the order should be:
136
137         VERSIONID
138         OSTYPE
139         DOMAIN
140         FEATURE
141         local macro definitions
142         MAILER
143         LOCAL_CONFIG
144         LOCAL_RULE_*
145         LOCAL_RULESETS
146
147 There are a few exceptions to this rule.  Local macro definitions which
148 influence a FEATURE() should be done before that feature.  For example,
149 a define(`PROCMAIL_MAILER_PATH', ...) should be done before
150 FEATURE(`local_procmail').
151
152 *******************************************************************
153 ***  BE SURE YOU CUSTOMIZE THESE FILES!  They have some         ***
154 ***  Berkeley-specific assumptions built in, such as the name   ***
155 ***  of their UUCP-relay.  You'll want to create your own       ***
156 ***  domain description, and use that in place of               ***
157 ***  domain/Berkeley.EDU.m4.                                    ***
158 *******************************************************************
159
160
161 +----------------------------+
162 | A BRIEF INTRODUCTION TO M4 |
163 +----------------------------+
164
165 Sendmail uses the M4 macro processor to ``compile'' the configuration
166 files.  The most important thing to know is that M4 is stream-based,
167 that is, it doesn't understand about lines.  For this reason, in some
168 places you may see the word ``dnl'', which stands for ``delete
169 through newline''; essentially, it deletes all characters starting
170 at the ``dnl'' up to and including the next newline character.  In
171 most cases sendmail uses this only to avoid lots of unnecessary
172 blank lines in the output.
173
174 Other important directives are define(A, B) which defines the macro
175 ``A'' to have value ``B''.  Macros are expanded as they are read, so
176 one normally quotes both values to prevent expansion.  For example,
177
178         define(`SMART_HOST', `smart.foo.com')
179
180 One word of warning:  M4 macros are expanded even in lines that appear
181 to be comments.  For example, if you have
182
183         # See FEATURE(`foo') above
184
185 it will not do what you expect, because the FEATURE(`foo') will be
186 expanded.  This also applies to
187
188         # And then define the $X macro to be the return address
189
190 because ``define'' is an M4 keyword.  If you want to use them, surround
191 them with directed quotes, `like this'.
192
193 Since m4 uses single quotes (opening "`" and closing "'") to quote
194 arguments, those quotes can't be used in arguments.  For example,
195 it is not possible to define a rejection message containing a single
196 quote. Usually there are simple workarounds by changing those
197 messages; in the worst case it might be ok to change the value
198 directly in the generated .cf file, which however is not advised.
199
200
201 Notice:
202 -------
203
204 This package requires a post-V7 version of m4; if you are running the
205 4.2bsd, SysV.2, or 7th Edition version.  SunOS's /usr/5bin/m4 or
206 BSD-Net/2's m4 both work.  GNU m4 version 1.1 or later also works.
207 Unfortunately, the M4 on BSDI 1.0 doesn't work -- you'll have to use a
208 Net/2 or GNU version.  GNU m4 is available from
209 ftp://ftp.gnu.org/pub/gnu/m4/m4-1.4.tar.gz (check for the latest version).
210 EXCEPTIONS: DEC's m4 on Digital UNIX 4.x is broken (3.x is fine).  Use GNU
211 m4 on this platform.
212
213
214 +----------------+
215 | FILE LOCATIONS |
216 +----------------+
217
218 sendmail 8.9 has introduced a new configuration directory for sendmail
219 related files, /etc/mail.  The new files available for sendmail 8.9 --
220 the class {R} /etc/mail/relay-domains and the access database
221 /etc/mail/access -- take advantage of this new directory.  Beginning with
222 8.10, all files will use this directory by default (some options may be
223 set by OSTYPE() files).  This new directory should help to restore
224 uniformity to sendmail's file locations.
225
226 Below is a table of some of the common changes:
227
228 Old filename                    New filename
229 ------------                    ------------
230 /etc/bitdomain                  /etc/mail/bitdomain
231 /etc/domaintable                /etc/mail/domaintable
232 /etc/genericstable              /etc/mail/genericstable
233 /etc/uudomain                   /etc/mail/uudomain
234 /etc/virtusertable              /etc/mail/virtusertable
235 /etc/userdb                     /etc/mail/userdb
236
237 /etc/aliases                    /etc/mail/aliases
238 /etc/sendmail/aliases           /etc/mail/aliases
239 /etc/ucbmail/aliases            /etc/mail/aliases
240 /usr/adm/sendmail/aliases       /etc/mail/aliases
241 /usr/lib/aliases                /etc/mail/aliases
242 /usr/lib/mail/aliases           /etc/mail/aliases
243 /usr/ucblib/aliases             /etc/mail/aliases
244
245 /etc/sendmail.cw                /etc/mail/local-host-names
246 /etc/mail/sendmail.cw           /etc/mail/local-host-names
247 /etc/sendmail/sendmail.cw       /etc/mail/local-host-names
248
249 /etc/sendmail.ct                /etc/mail/trusted-users
250
251 /etc/sendmail.oE                /etc/mail/error-header
252
253 /etc/sendmail.hf                /etc/mail/helpfile
254 /etc/mail/sendmail.hf           /etc/mail/helpfile
255 /usr/ucblib/sendmail.hf         /etc/mail/helpfile
256 /etc/ucbmail/sendmail.hf        /etc/mail/helpfile
257 /usr/lib/sendmail.hf            /etc/mail/helpfile
258 /usr/share/lib/sendmail.hf      /etc/mail/helpfile
259 /usr/share/misc/sendmail.hf     /etc/mail/helpfile
260 /share/misc/sendmail.hf         /etc/mail/helpfile
261
262 /etc/service.switch             /etc/mail/service.switch
263
264 /etc/sendmail.st                /etc/mail/statistics
265 /etc/mail/sendmail.st           /etc/mail/statistics
266 /etc/mailer/sendmail.st         /etc/mail/statistics
267 /etc/sendmail/sendmail.st       /etc/mail/statistics
268 /usr/lib/sendmail.st            /etc/mail/statistics
269 /usr/ucblib/sendmail.st         /etc/mail/statistics
270
271 Note that all of these paths actually use a new m4 macro MAIL_SETTINGS_DIR
272 to create the pathnames.  The default value of this variable is
273 `/etc/mail/'.  If you set this macro to a different value, you MUST include
274 a trailing slash.
275
276 Notice: all filenames used in a .mc (or .cf) file should be absolute
277 (starting at the root, i.e., with '/').  Relative filenames most
278 likely cause surprises during operations (unless otherwise noted).
279
280
281 +--------+
282 | OSTYPE |
283 +--------+
284
285 You MUST define an operating system environment, or the configuration
286 file build will puke.  There are several environments available; look
287 at the "ostype" directory for the current list.  This macro changes
288 things like the location of the alias file and queue directory.  Some
289 of these files are identical to one another.
290
291 It is IMPERATIVE that the OSTYPE occur before any MAILER definitions.
292 In general, the OSTYPE macro should go immediately after any version
293 information, and MAILER definitions should always go last.
294
295 Operating system definitions are usually easy to write.  They may define
296 the following variables (everything defaults, so an ostype file may be
297 empty).  Unfortunately, the list of configuration-supported systems is
298 not as broad as the list of source-supported systems, since many of
299 the source contributors do not include corresponding ostype files.
300
301 ALIAS_FILE              [/etc/mail/aliases] The location of the text version
302                         of the alias file(s).  It can be a comma-separated
303                         list of names (but be sure you quote values with
304                         commas in them -- for example, use
305                                 define(`ALIAS_FILE', `a,b')
306                         to get "a" and "b" both listed as alias files;
307                         otherwise the define() primitive only sees "a").
308 HELP_FILE               [/etc/mail/helpfile] The name of the file
309                         containing information printed in response to
310                         the SMTP HELP command.
311 QUEUE_DIR               [/var/spool/mqueue] The directory containing
312                         queue files.  To use multiple queues, supply
313                         a value ending with an asterisk.  For
314                         example, /var/spool/mqueue/qd* will use all of the
315                         directories or symbolic links to directories
316                         beginning with 'qd' in /var/spool/mqueue as queue
317                         directories.  The names 'qf', 'df', and 'xf' are
318                         reserved as specific subdirectories for the
319                         corresponding queue file types as explained in
320                         doc/op/op.me.  See also QUEUE GROUP DEFINITIONS.
321 MSP_QUEUE_DIR           [/var/spool/clientmqueue] The directory containing
322                         queue files for the MSP (Mail Submission Program,
323                         see sendmail/SECURITY).
324 STATUS_FILE             [/etc/mail/statistics] The file containing status
325                         information.
326 LOCAL_MAILER_PATH       [/bin/mail] The program used to deliver local mail.
327 LOCAL_MAILER_FLAGS      [Prmn9] The flags used by the local mailer.  The
328                         flags lsDFMAw5:/|@q are always included.
329 LOCAL_MAILER_ARGS       [mail -d $u] The arguments passed to deliver local
330                         mail.
331 LOCAL_MAILER_MAX        [undefined] If defined, the maximum size of local
332                         mail that you are willing to accept.
333 LOCAL_MAILER_MAXMSGS    [undefined] If defined, the maximum number of
334                         messages to deliver in a single connection.  Only
335                         useful for LMTP local mailers.
336 LOCAL_MAILER_CHARSET    [undefined] If defined, messages containing 8-bit data
337                         that ARRIVE from an address that resolves to the
338                         local mailer and which are converted to MIME will be
339                         labeled with this character set.
340 LOCAL_MAILER_EOL        [undefined] If defined, the string to use as the
341                         end of line for the local mailer.
342 LOCAL_MAILER_DSN_DIAGNOSTIC_CODE
343                         [X-Unix] The DSN Diagnostic-Code value for the
344                         local mailer.  This should be changed with care.
345 LOCAL_SHELL_PATH        [/bin/sh] The shell used to deliver piped email.
346 LOCAL_SHELL_FLAGS       [eu9] The flags used by the shell mailer.  The
347                         flags lsDFM are always included.
348 LOCAL_SHELL_ARGS        [sh -c $u] The arguments passed to deliver "prog"
349                         mail.
350 LOCAL_SHELL_DIR         [$z:/] The directory search path in which the
351                         shell should run.
352 LOCAL_MAILER_QGRP       [undefined] The queue group for the local mailer.
353 USENET_MAILER_PATH      [/usr/lib/news/inews] The name of the program
354                         used to submit news.
355 USENET_MAILER_FLAGS     [rsDFMmn] The mailer flags for the usenet mailer.
356 USENET_MAILER_ARGS      [-m -h -n] The command line arguments for the
357                         usenet mailer.  NOTE: Some versions of inews
358                         (such as those shipped with newer versions of INN)
359                         use different flags.  Double check the defaults
360                         against the inews man page.
361 USENET_MAILER_MAX       [undefined] The maximum size of messages that will
362                         be accepted by the usenet mailer.
363 USENET_MAILER_QGRP      [undefined] The queue group for the usenet mailer.
364 SMTP_MAILER_FLAGS       [undefined] Flags added to SMTP mailer.  Default
365                         flags are `mDFMuX' for all SMTP-based mailers; the
366                         "esmtp" mailer adds `a'; "smtp8" adds `8'; and
367                         "dsmtp" adds `%'.
368 RELAY_MAILER_FLAGS      [undefined] Flags added to the relay mailer.  Default
369                         flags are `mDFMuX' for all SMTP-based mailers; the
370                         relay mailer adds `a8'.  If this is not defined,
371                         then SMTP_MAILER_FLAGS is used.
372 SMTP_MAILER_MAX         [undefined] The maximum size of messages that will
373                         be transported using the smtp, smtp8, esmtp, or dsmtp
374                         mailers.
375 SMTP_MAILER_MAXMSGS     [undefined] If defined, the maximum number of
376                         messages to deliver in a single connection for the
377                         smtp, smtp8, esmtp, or dsmtp mailers.
378 SMTP_MAILER_MAXRCPTS    [undefined] If defined, the maximum number of
379                         recipients to deliver in a single connection for the
380                         smtp, smtp8, esmtp, or dsmtp mailers.
381 SMTP_MAILER_ARGS        [TCP $h] The arguments passed to the smtp mailer.
382                         About the only reason you would want to change this
383                         would be to change the default port.
384 ESMTP_MAILER_ARGS       [TCP $h] The arguments passed to the esmtp mailer.
385 SMTP8_MAILER_ARGS       [TCP $h] The arguments passed to the smtp8 mailer.
386 DSMTP_MAILER_ARGS       [TCP $h] The arguments passed to the dsmtp mailer.
387 RELAY_MAILER_ARGS       [TCP $h] The arguments passed to the relay mailer.
388 SMTP_MAILER_QGRP        [undefined] The queue group for the smtp mailer.
389 ESMTP_MAILER_QGRP       [undefined] The queue group for the esmtp mailer.
390 SMTP8_MAILER_QGRP       [undefined] The queue group for the smtp8 mailer.
391 DSMTP_MAILER_QGRP       [undefined] The queue group for the dsmtp mailer.
392 RELAY_MAILER_QGRP       [undefined] The queue group for the relay mailer.
393 RELAY_MAILER_MAXMSGS    [undefined] If defined, the maximum number of
394                         messages to deliver in a single connection for the
395                         relay mailer.
396 SMTP_MAILER_CHARSET     [undefined] If defined, messages containing 8-bit data
397                         that ARRIVE from an address that resolves to one of
398                         the SMTP mailers and which are converted to MIME will
399                         be labeled with this character set.
400 UUCP_MAILER_PATH        [/usr/bin/uux] The program used to send UUCP mail.
401 UUCP_MAILER_FLAGS       [undefined] Flags added to UUCP mailer.  Default
402                         flags are `DFMhuU' (and `m' for uucp-new mailer,
403                         minus `U' for uucp-dom mailer).
404 UUCP_MAILER_ARGS        [uux - -r -z -a$g -gC $h!rmail ($u)] The arguments
405                         passed to the UUCP mailer.
406 UUCP_MAILER_MAX         [100000] The maximum size message accepted for
407                         transmission by the UUCP mailers.
408 UUCP_MAILER_CHARSET     [undefined] If defined, messages containing 8-bit data
409                         that ARRIVE from an address that resolves to one of
410                         the UUCP mailers and which are converted to MIME will
411                         be labeled with this character set.
412 UUCP_MAILER_QGRP        [undefined] The queue group for the UUCP mailers.
413 FAX_MAILER_PATH         [/usr/local/lib/fax/mailfax] The program used to
414                         submit FAX messages.
415 FAX_MAILER_ARGS         [mailfax $u $h $f] The arguments passed to the FAX
416                         mailer.
417 FAX_MAILER_MAX          [100000] The maximum size message accepted for
418                         transmission by FAX.
419 POP_MAILER_PATH         [/usr/lib/mh/spop] The pathname of the POP mailer.
420 POP_MAILER_FLAGS        [Penu] Flags added to POP mailer.  Flags lsDFMq
421                         are always added.
422 POP_MAILER_ARGS         [pop $u] The arguments passed to the POP mailer.
423 POP_MAILER_QGRP         [undefined] The queue group for the pop mailer.
424 PROCMAIL_MAILER_PATH    [/usr/local/bin/procmail] The path to the procmail
425                         program.  This is also used by
426                         FEATURE(`local_procmail').
427 PROCMAIL_MAILER_FLAGS   [SPhnu9] Flags added to Procmail mailer.  Flags
428                         DFM are always set.  This is NOT used by
429                         FEATURE(`local_procmail'); tweak LOCAL_MAILER_FLAGS
430                         instead.
431 PROCMAIL_MAILER_ARGS    [procmail -Y -m $h $f $u] The arguments passed to
432                         the Procmail mailer.  This is NOT used by
433                         FEATURE(`local_procmail'); tweak LOCAL_MAILER_ARGS
434                         instead.
435 PROCMAIL_MAILER_MAX     [undefined] If set, the maximum size message that
436                         will be accepted by the procmail mailer.
437 PROCMAIL_MAILER_QGRP    [undefined] The queue group for the procmail mailer.
438 MAIL11_MAILER_PATH      [/usr/etc/mail11] The path to the mail11 mailer.
439 MAIL11_MAILER_FLAGS     [nsFx] Flags for the mail11 mailer.
440 MAIL11_MAILER_ARGS      [mail11 $g $x $h $u] Arguments passed to the mail11
441                         mailer.
442 MAIL11_MAILER_QGRP      [undefined] The queue group for the mail11 mailer.
443 PH_MAILER_PATH          [/usr/local/etc/phquery] The path to the phquery
444                         program.
445 PH_MAILER_FLAGS         [ehmu] Flags for the phquery mailer.  Flags nrDFM
446                         are always set.
447 PH_MAILER_ARGS          [phquery -- $u] -- arguments to the phquery mailer.
448 PH_MAILER_QGRP          [undefined] The queue group for the ph mailer.
449 CYRUS_MAILER_FLAGS      [Ah5@/:|] The flags used by the cyrus mailer.  The
450                         flags lsDFMnPq are always included.
451 CYRUS_MAILER_PATH       [/usr/cyrus/bin/deliver] The program used to deliver
452                         cyrus mail.
453 CYRUS_MAILER_ARGS       [deliver -e -m $h -- $u] The arguments passed
454                         to deliver cyrus mail.
455 CYRUS_MAILER_MAX        [undefined] If set, the maximum size message that
456                         will be accepted by the cyrus mailer.
457 CYRUS_MAILER_USER       [cyrus:mail] The user and group to become when
458                         running the cyrus mailer.
459 CYRUS_MAILER_QGRP       [undefined] The queue group for the cyrus mailer.
460 CYRUS_BB_MAILER_FLAGS   [u] The flags used by the cyrusbb mailer.
461                         The flags lsDFMnP are always included.
462 CYRUS_BB_MAILER_ARGS    [deliver -e -m $u] The arguments passed
463                         to deliver cyrusbb mail.
464 CYRUSV2_MAILER_FLAGS    [A@/:|m] The flags used by the cyrusv2 mailer.  The
465                         flags lsDFMnqXz are always included.
466 CYRUSV2_MAILER_MAXMSGS  [undefined] If defined, the maximum number of
467                         messages to deliver in a single connection for the
468                         cyrusv2 mailer.
469 CYRUSV2_MAILER_MAXRCPTS [undefined] If defined, the maximum number of
470                         recipients to deliver in a single connection for the
471                         cyrusv2 mailer.
472 CYRUSV2_MAILER_ARGS     [FILE /var/imap/socket/lmtp] The arguments passed
473                         to the cyrusv2 mailer.  This can be used to
474                         change the name of the Unix domain socket, or
475                         to switch to delivery via TCP (e.g., `TCP $h lmtp')
476 CYRUSV2_MAILER_QGRP     [undefined] The queue group for the cyrusv2 mailer.
477 CYRUSV2_MAILER_CHARSET  [undefined] If defined, messages containing 8-bit data
478                         that ARRIVE from an address that resolves to one the
479                         Cyrus mailer and which are converted to MIME will
480                         be labeled with this character set.
481 confEBINDIR             [/usr/libexec] The directory for executables.
482                         Currently used for FEATURE(`local_lmtp') and
483                         FEATURE(`smrsh').
484 QPAGE_MAILER_FLAGS      [mDFMs] The flags used by the qpage mailer.
485 QPAGE_MAILER_PATH       [/usr/local/bin/qpage] The program used to deliver
486                         qpage mail.
487 QPAGE_MAILER_ARGS       [qpage -l0 -m -P$u] The arguments passed
488                         to deliver qpage mail.
489 QPAGE_MAILER_MAX        [4096] If set, the maximum size message that
490                         will be accepted by the qpage mailer.
491 QPAGE_MAILER_QGRP       [undefined] The queue group for the qpage mailer.
492 LOCAL_PROG_QGRP         [undefined] The queue group for the prog mailer.
493
494 Note: to tweak Name_MAILER_FLAGS use the macro MODIFY_MAILER_FLAGS:
495 MODIFY_MAILER_FLAGS(`Name', `change') where Name is the first part of
496 the macro Name_MAILER_FLAGS and change can be: flags that should
497 be used directly (thus overriding the default value), or if it
498 starts with `+' (`-') then those flags are added to (removed from)
499 the default value.  Example:
500
501         MODIFY_MAILER_FLAGS(`LOCAL', `+e')
502
503 will add the flag `e' to LOCAL_MAILER_FLAGS.  Notice: there are
504 several smtp mailers all of which are manipulated individually.
505 See the section MAILERS for the available mailer names.
506 WARNING: The FEATUREs local_lmtp and local_procmail set LOCAL_MAILER_FLAGS
507 unconditionally, i.e., without respecting any definitions in an
508 OSTYPE setting.
509
510
511 +---------+
512 | DOMAINS |
513 +---------+
514
515 You will probably want to collect domain-dependent defines into one
516 file, referenced by the DOMAIN macro.  For example, the Berkeley
517 domain file includes definitions for several internal distinguished
518 hosts:
519
520 UUCP_RELAY      The host that will accept UUCP-addressed email.
521                 If not defined, all UUCP sites must be directly
522                 connected.
523 BITNET_RELAY    The host that will accept BITNET-addressed email.
524                 If not defined, the .BITNET pseudo-domain won't work.
525 DECNET_RELAY    The host that will accept DECNET-addressed email.
526                 If not defined, the .DECNET pseudo-domain and addresses
527                 of the form node::user will not work.
528 FAX_RELAY       The host that will accept mail to the .FAX pseudo-domain.
529                 The "fax" mailer overrides this value.
530 LOCAL_RELAY     The site that will handle unqualified names -- that
531                 is, names without an @domain extension.
532                 Normally MAIL_HUB is preferred for this function.
533                 LOCAL_RELAY is mostly useful in conjunction with
534                 FEATURE(`stickyhost') -- see the discussion of
535                 stickyhost below.  If not set, they are assumed to
536                 belong on this machine.  This allows you to have a
537                 central site to store a company- or department-wide
538                 alias database.  This only works at small sites,
539                 and only with some user agents.
540 LUSER_RELAY     The site that will handle lusers -- that is, apparently
541                 local names that aren't local accounts or aliases.  To
542                 specify a local user instead of a site, set this to
543                 ``local:username''.
544
545 Any of these can be either ``mailer:hostname'' (in which case the
546 mailer is the internal mailer name, such as ``uucp-new'' and the hostname
547 is the name of the host as appropriate for that mailer) or just a
548 ``hostname'', in which case a default mailer type (usually ``relay'',
549 a variant on SMTP) is used.  WARNING: if you have a wildcard MX
550 record matching your domain, you probably want to define these to
551 have a trailing dot so that you won't get the mail diverted back
552 to yourself.
553
554 The domain file can also be used to define a domain name, if needed
555 (using "DD<domain>") and set certain site-wide features.  If all hosts
556 at your site masquerade behind one email name, you could also use
557 MASQUERADE_AS here.
558
559 You do not have to define a domain -- in particular, if you are a
560 single machine sitting off somewhere, it is probably more work than
561 it's worth.  This is just a mechanism for combining "domain dependent
562 knowledge" into one place.
563
564
565 +---------+
566 | MAILERS |
567 +---------+
568
569 There are fewer mailers supported in this version than the previous
570 version, owing mostly to a simpler world.  As a general rule, put the
571 MAILER definitions last in your .mc file.
572
573 local           The local and prog mailers.  You will almost always
574                 need these; the only exception is if you relay ALL
575                 your mail to another site.  This mailer is included
576                 automatically.
577
578 smtp            The Simple Mail Transport Protocol mailer.  This does
579                 not hide hosts behind a gateway or another other
580                 such hack; it assumes a world where everyone is
581                 running the name server.  This file actually defines
582                 five mailers: "smtp" for regular (old-style) SMTP to
583                 other servers, "esmtp" for extended SMTP to other
584                 servers, "smtp8" to do SMTP to other servers without
585                 converting 8-bit data to MIME (essentially, this is
586                 your statement that you know the other end is 8-bit
587                 clean even if it doesn't say so), "dsmtp" to do on
588                 demand delivery, and "relay" for transmission to the
589                 RELAY_HOST, LUSER_RELAY, or MAIL_HUB.
590
591 uucp            The UNIX-to-UNIX Copy Program mailer.  Actually, this
592                 defines two mailers, "uucp-old" (a.k.a. "uucp") and
593                 "uucp-new" (a.k.a. "suucp").  The latter is for when you
594                 know that the UUCP mailer at the other end can handle
595                 multiple recipients in one transfer.  If the smtp mailer
596                 is included in your configuration, two other mailers
597                 ("uucp-dom" and "uucp-uudom") are also defined [warning: you
598                 MUST specify MAILER(`smtp') before MAILER(`uucp')].  When you
599                 include the uucp mailer, sendmail looks for all names in
600                 class {U} and sends them to the uucp-old mailer; all
601                 names in class {Y} are sent to uucp-new; and all
602                 names in class {Z} are sent to uucp-uudom.  Note that
603                 this is a function of what version of rmail runs on
604                 the receiving end, and hence may be out of your control.
605                 See the section below describing UUCP mailers in more
606                 detail.
607
608 usenet          Usenet (network news) delivery.  If this is specified,
609                 an extra rule is added to ruleset 0 that forwards all
610                 local email for users named ``group.usenet'' to the
611                 ``inews'' program.  Note that this works for all groups,
612                 and may be considered a security problem.
613
614 fax             Facsimile transmission.  This is experimental and based
615                 on Sam Leffler's HylaFAX software.  For more information,
616                 see http://www.hylafax.org/.
617
618 pop             Post Office Protocol.
619
620 procmail        An interface to procmail (does not come with sendmail).
621                 This is designed to be used in mailertables.  For example,
622                 a common question is "how do I forward all mail for a given
623                 domain to a single person?".  If you have this mailer
624                 defined, you could set up a mailertable reading:
625
626                         host.com        procmail:/etc/procmailrcs/host.com
627
628                 with the file /etc/procmailrcs/host.com reading:
629
630                         :0      # forward mail for host.com
631                         ! -oi -f $1 person@other.host
632
633                 This would arrange for (anything)@host.com to be sent
634                 to person@other.host.  In a procmail script, $1 is the
635                 name of the sender and $2 is the name of the recipient.
636                 If you use this with FEATURE(`local_procmail'), the FEATURE
637                 should be listed first.
638
639                 Of course there are other ways to solve this particular
640                 problem, e.g., a catch-all entry in a virtusertable.
641
642 mail11          The DECnet mail11 mailer, useful only if you have the mail11
643                 program from gatekeeper.dec.com:/pub/DEC/gwtools (and
644                 DECnet, of course).  This is for Phase IV DECnet support;
645                 if you have Phase V at your site you may have additional
646                 problems.
647
648 phquery         The phquery program.  This is somewhat counterintuitively
649                 referenced as the "ph" mailer internally.  It can be used
650                 to do CCSO name server lookups.  The phquery program, which
651                 this mailer uses, is distributed with the ph client.
652
653 cyrus           The cyrus and cyrusbb mailers.  The cyrus mailer delivers to
654                 a local cyrus user.  this mailer can make use of the
655                 "user+detail@local.host" syntax (see
656                 FEATURE(`preserve_local_plus_detail')); it will deliver the
657                 mail to the user's "detail" mailbox if the mailbox's ACL
658                 permits.  The cyrusbb mailer delivers to a system-wide
659                 cyrus mailbox if the mailbox's ACL permits.  The cyrus
660                 mailer must be defined after the local mailer.
661
662 cyrusv2         The mailer for Cyrus v2.x.  The cyrusv2 mailer delivers to
663                 local cyrus users via LMTP.  This mailer can make use of the
664                 "user+detail@local.host" syntax (see
665                 FEATURE(`preserve_local_plus_detail')); it will deliver the
666                 mail to the user's "detail" mailbox if the mailbox's ACL
667                 permits.  The cyrusv2 mailer must be defined after the
668                 local mailer.
669
670 qpage           A mailer for QuickPage, a pager interface.  See
671                 http://www.qpage.org/ for further information.
672
673 The local mailer accepts addresses of the form "user+detail", where
674 the "+detail" is not used for mailbox matching but is available
675 to certain local mail programs (in particular, see
676 FEATURE(`local_procmail')).  For example, "eric", "eric+sendmail", and
677 "eric+sww" all indicate the same user, but additional arguments <null>,
678 "sendmail", and "sww" may be provided for use in sorting mail.
679
680
681 +----------+
682 | FEATURES |
683 +----------+
684
685 Special features can be requested using the "FEATURE" macro.  For
686 example, the .mc line:
687
688         FEATURE(`use_cw_file')
689
690 tells sendmail that you want to have it read an /etc/mail/local-host-names
691 file to get values for class {w}.  A FEATURE may contain up to 9
692 optional parameters -- for example:
693
694         FEATURE(`mailertable', `dbm /usr/lib/mailertable')
695
696 The default database map type for the table features can be set with
697
698         define(`DATABASE_MAP_TYPE', `dbm')
699
700 which would set it to use ndbm databases.  The default is the Berkeley DB
701 hash database format.  Note that you must still declare a database map type
702 if you specify an argument to a FEATURE.  DATABASE_MAP_TYPE is only used
703 if no argument is given for the FEATURE.  It must be specified before any
704 feature that uses a map.
705
706 Also, features which can take a map definition as an argument can also take
707 the special keyword `LDAP'.  If that keyword is used, the map will use the
708 LDAP definition described in the ``USING LDAP FOR ALIASES, MAPS, AND
709 CLASSES'' section below.
710
711 Available features are:
712
713 use_cw_file     Read the file /etc/mail/local-host-names file to get
714                 alternate names for this host.  This might be used if you
715                 were on a host that MXed for a dynamic set of other hosts.
716                 If the set is static, just including the line "Cw<name1>
717                 <name2> ..." (where the names are fully qualified domain
718                 names) is probably superior.  The actual filename can be
719                 overridden by redefining confCW_FILE.
720
721 use_ct_file     Read the file /etc/mail/trusted-users file to get the
722                 names of users that will be ``trusted'', that is, able to
723                 set their envelope from address using -f without generating
724                 a warning message.  The actual filename can be overridden
725                 by redefining confCT_FILE.
726
727 redirect        Reject all mail addressed to "address.REDIRECT" with
728                 a ``551 User has moved; please try <address>'' message.
729                 If this is set, you can alias people who have left
730                 to their new address with ".REDIRECT" appended.
731
732 nouucp          Don't route UUCP addresses.  This feature takes one
733                 parameter:
734                 `reject': reject addresses which have "!" in the local
735                         part unless it originates from a system
736                         that is allowed to relay.
737                 `nospecial': don't do anything special with "!".
738                 Warnings: 1. See the notice in the anti-spam section.
739                 2. don't remove "!" from OperatorChars if `reject' is
740                 given as parameter.
741
742 nocanonify      Don't pass addresses to $[ ... $] for canonification
743                 by default, i.e., host/domain names are considered canonical,
744                 except for unqualified names, which must not be used in this
745                 mode (violation of the standard).  It can be changed by
746                 setting the DaemonPortOptions modifiers (M=).  That is,
747                 FEATURE(`nocanonify') will be overridden by setting the
748                 'c' flag.  Conversely, if FEATURE(`nocanonify') is not used,
749                 it can be emulated by setting the 'C' flag
750                 (DaemonPortOptions=Modifiers=C).  This would generally only
751                 be used by sites that only act as mail gateways or which have
752                 user agents that do full canonification themselves.  You may
753                 also want to use
754                 "define(`confBIND_OPTS', `-DNSRCH -DEFNAMES')" to turn off
755                 the usual resolver options that do a similar thing.
756
757                 An exception list for FEATURE(`nocanonify') can be
758                 specified with CANONIFY_DOMAIN or CANONIFY_DOMAIN_FILE,
759                 i.e., a list of domains which are nevertheless passed to
760                 $[ ... $] for canonification.  This is useful to turn on
761                 canonification for local domains, e.g., use
762                 CANONIFY_DOMAIN(`my.domain my') to canonify addresses
763                 which end in "my.domain" or "my".
764                 Another way to require canonification in the local
765                 domain is CANONIFY_DOMAIN(`$=m').
766
767                 A trailing dot is added to addresses with more than
768                 one component in it such that other features which
769                 expect a trailing dot (e.g., virtusertable) will
770                 still work.
771
772                 If `canonify_hosts' is specified as parameter, i.e.,
773                 FEATURE(`nocanonify', `canonify_hosts'), then
774                 addresses which have only a hostname, e.g.,
775                 <user@host>, will be canonified (and hopefully fully
776                 qualified), too.
777
778 stickyhost      This feature is sometimes used with LOCAL_RELAY,
779                 although it can be used for a different effect with
780                 MAIL_HUB.
781
782                 When used without MAIL_HUB, email sent to
783                 "user@local.host" are marked as "sticky" -- that
784                 is, the local addresses aren't matched against UDB,
785                 don't go through ruleset 5, and are not forwarded to
786                 the LOCAL_RELAY (if defined).
787
788                 With MAIL_HUB, mail addressed to "user@local.host"
789                 is forwarded to the mail hub, with the envelope
790                 address still remaining "user@local.host".
791                 Without stickyhost, the envelope would be changed
792                 to "user@mail_hub", in order to protect against
793                 mailing loops.
794
795 mailertable     Include a "mailer table" which can be used to override
796                 routing for particular domains (which are not in class {w},
797                 i.e.  local host names).  The argument of the FEATURE may be
798                 the key definition.  If none is specified, the definition
799                 used is:
800
801                         hash /etc/mail/mailertable
802
803                 Keys in this database are fully qualified domain names
804                 or partial domains preceded by a dot -- for example,
805                 "vangogh.CS.Berkeley.EDU" or ".CS.Berkeley.EDU".  As a
806                 special case of the latter, "." matches any domain not
807                 covered by other keys.  Values must be of the form:
808                         mailer:domain
809                 where "mailer" is the internal mailer name, and "domain"
810                 is where to send the message.  These maps are not
811                 reflected into the message header.  As a special case,
812                 the forms:
813                         local:user
814                 will forward to the indicated user using the local mailer,
815                         local:
816                 will forward to the original user in the e-mail address
817                 using the local mailer, and
818                         error:code message
819                         error:D.S.N:code message
820                 will give an error message with the indicated SMTP reply
821                 code and message, where D.S.N is an RFC 1893 compliant
822                 error code.
823
824 domaintable     Include a "domain table" which can be used to provide
825                 domain name mapping.  Use of this should really be
826                 limited to your own domains.  It may be useful if you
827                 change names (e.g., your company changes names from
828                 oldname.com to newname.com).  The argument of the
829                 FEATURE may be the key definition.  If none is specified,
830                 the definition used is:
831
832                         hash /etc/mail/domaintable
833
834                 The key in this table is the domain name; the value is
835                 the new (fully qualified) domain.  Anything in the
836                 domaintable is reflected into headers; that is, this
837                 is done in ruleset 3.
838
839 bitdomain       Look up bitnet hosts in a table to try to turn them into
840                 internet addresses.  The table can be built using the
841                 bitdomain program contributed by John Gardiner Myers.
842                 The argument of the FEATURE may be the key definition; if
843                 none is specified, the definition used is:
844
845                         hash /etc/mail/bitdomain
846
847                 Keys are the bitnet hostname; values are the corresponding
848                 internet hostname.
849
850 uucpdomain      Similar feature for UUCP hosts.  The default map definition
851                 is:
852
853                         hash /etc/mail/uudomain
854
855                 At the moment there is no automagic tool to build this
856                 database.
857
858 always_add_domain
859                 Include the local host domain even on locally delivered
860                 mail.  Normally it is not added on unqualified names.
861                 However, if you use a shared message store but do not use
862                 the same user name space everywhere, you may need the host
863                 name on local names.  An optional argument specifies
864                 another domain to be added than the local.
865
866 allmasquerade   If masquerading is enabled (using MASQUERADE_AS), this
867                 feature will cause recipient addresses to also masquerade
868                 as being from the masquerade host.  Normally they get
869                 the local hostname.  Although this may be right for
870                 ordinary users, it can break local aliases.  For example,
871                 if you send to "localalias", the originating sendmail will
872                 find that alias and send to all members, but send the
873                 message with "To: localalias@masqueradehost".  Since that
874                 alias likely does not exist, replies will fail.  Use this
875                 feature ONLY if you can guarantee that the ENTIRE
876                 namespace on your masquerade host supersets all the
877                 local entries.
878
879 limited_masquerade
880                 Normally, any hosts listed in class {w} are masqueraded.  If
881                 this feature is given, only the hosts listed in class {M} (see
882                 below:  MASQUERADE_DOMAIN) are masqueraded.  This is useful
883                 if you have several domains with disjoint namespaces hosted
884                 on the same machine.
885
886 masquerade_entire_domain
887                 If masquerading is enabled (using MASQUERADE_AS) and
888                 MASQUERADE_DOMAIN (see below) is set, this feature will
889                 cause addresses to be rewritten such that the masquerading
890                 domains are actually entire domains to be hidden.  All
891                 hosts within the masquerading domains will be rewritten
892                 to the masquerade name (used in MASQUERADE_AS).  For example,
893                 if you have:
894
895                         MASQUERADE_AS(`masq.com')
896                         MASQUERADE_DOMAIN(`foo.org')
897                         MASQUERADE_DOMAIN(`bar.com')
898
899                 then *foo.org and *bar.com are converted to masq.com.  Without
900                 this feature, only foo.org and bar.com are masqueraded.
901
902                     NOTE: only domains within your jurisdiction and
903                     current hierarchy should be masqueraded using this.
904
905 local_no_masquerade
906                 This feature prevents the local mailer from masquerading even
907                 if MASQUERADE_AS is used.  MASQUERADE_AS will only have effect
908                 on addresses of mail going outside the local domain.
909
910 masquerade_envelope
911                 If masquerading is enabled (using MASQUERADE_AS) or the
912                 genericstable is in use, this feature will cause envelope
913                 addresses to also masquerade as being from the masquerade
914                 host.  Normally only the header addresses are masqueraded.
915
916 genericstable   This feature will cause unqualified addresses (i.e., without
917                 a domain) and addresses with a domain listed in class {G}
918                 to be looked up in a map and turned into another ("generic")
919                 form, which can change both the domain name and the user name.
920                 Notice: if you use an MSP (as it is default starting with
921                 8.12), the MTA will only receive qualified addresses from the
922                 MSP (as required by the RFCs).  Hence you need to add your
923                 domain to class {G}.  This feature is similar to the userdb
924                 functionality.  The same types of addresses as for
925                 masquerading are looked up, i.e., only header sender
926                 addresses unless the allmasquerade and/or masquerade_envelope
927                 features are given.  Qualified addresses must have the domain
928                 part in class {G}; entries can be added to this class by the
929                 macros GENERICS_DOMAIN or GENERICS_DOMAIN_FILE (analogously
930                 to MASQUERADE_DOMAIN and MASQUERADE_DOMAIN_FILE, see below).
931
932                 The argument of FEATURE(`genericstable') may be the map
933                 definition; the default map definition is:
934
935                         hash /etc/mail/genericstable
936
937                 The key for this table is either the full address, the domain
938                 (with a leading @; the localpart is passed as first argument)
939                 or the unqualified username (tried in the order mentioned);
940                 the value is the new user address.  If the new user address
941                 does not include a domain, it will be qualified in the standard
942                 manner, i.e., using $j or the masquerade name.  Note that the
943                 address being looked up must be fully qualified.  For local
944                 mail, it is necessary to use FEATURE(`always_add_domain')
945                 for the addresses to be qualified.
946                 The "+detail" of an address is passed as %1, so entries like
947
948                         old+*@foo.org   new+%1@example.com
949                         gen+*@foo.org   %1@example.com
950
951                 and other forms are possible.
952
953 generics_entire_domain
954                 If the genericstable is enabled and GENERICS_DOMAIN or
955                 GENERICS_DOMAIN_FILE is used, this feature will cause
956                 addresses to be searched in the map if their domain
957                 parts are subdomains of elements in class {G}.
958
959 virtusertable   A domain-specific form of aliasing, allowing multiple
960                 virtual domains to be hosted on one machine.  For example,
961                 if the virtuser table contained:
962
963                         info@foo.com    foo-info
964                         info@bar.com    bar-info
965                         joe@bar.com     error:nouser 550 No such user here
966                         jax@bar.com     error:5.7.0:550 Address invalid
967                         @baz.org        jane@example.net
968
969                 then mail addressed to info@foo.com will be sent to the
970                 address foo-info, mail addressed to info@bar.com will be
971                 delivered to bar-info, and mail addressed to anyone at baz.org
972                 will be sent to jane@example.net, mail to joe@bar.com will
973                 be rejected with the specified error message, and mail to
974                 jax@bar.com will also have a RFC 1893 compliant error code
975                 5.7.0.
976
977                 The username from the original address is passed
978                 as %1 allowing:
979
980                         @foo.org        %1@example.com
981
982                 meaning someone@foo.org will be sent to someone@example.com.
983                 Additionally, if the local part consists of "user+detail"
984                 then "detail" is passed as %2 and "+detail" is passed as %3
985                 when a match against user+* is attempted, so entries like
986
987                         old+*@foo.org   new+%2@example.com
988                         gen+*@foo.org   %2@example.com
989                         +*@foo.org      %1%3@example.com
990                         X++@foo.org     Z%3@example.com
991                         @bar.org        %1%3
992
993                 and other forms are possible.  Note: to preserve "+detail"
994                 for a default case (@domain) %1%3 must be used as RHS.
995                 There are two wildcards after "+": "+" matches only a non-empty
996                 detail, "*" matches also empty details, e.g., user+@foo.org
997                 matches +*@foo.org but not ++@foo.org.  This can be used
998                 to ensure that the parameters %2 and %3 are not empty.
999
1000                 All the host names on the left hand side (foo.com, bar.com,
1001                 and baz.org) must be in class {w} or class {VirtHost}.  The
1002                 latter can be defined by the macros VIRTUSER_DOMAIN or
1003                 VIRTUSER_DOMAIN_FILE (analogously to MASQUERADE_DOMAIN and
1004                 MASQUERADE_DOMAIN_FILE, see below).  If VIRTUSER_DOMAIN or
1005                 VIRTUSER_DOMAIN_FILE is used, then the entries of class
1006                 {VirtHost} are added to class {R}, i.e., relaying is allowed
1007                 to (and from) those domains.  The default map definition is:
1008
1009                         hash /etc/mail/virtusertable
1010
1011                 A new definition can be specified as the second argument of
1012                 the FEATURE macro, such as
1013
1014                         FEATURE(`virtusertable', `dbm /etc/mail/virtusers')
1015
1016 virtuser_entire_domain
1017                 If the virtusertable is enabled and VIRTUSER_DOMAIN or
1018                 VIRTUSER_DOMAIN_FILE is used, this feature will cause
1019                 addresses to be searched in the map if their domain
1020                 parts are subdomains of elements in class {VirtHost}.
1021
1022 ldap_routing    Implement LDAP-based e-mail recipient routing according to
1023                 the Internet Draft draft-lachman-laser-ldap-mail-routing-01.
1024                 This provides a method to re-route addresses with a
1025                 domain portion in class {LDAPRoute} to either a
1026                 different mail host or a different address.  Hosts can
1027                 be added to this class using LDAPROUTE_DOMAIN and
1028                 LDAPROUTE_DOMAIN_FILE (analogously to MASQUERADE_DOMAIN and
1029                 MASQUERADE_DOMAIN_FILE, see below).
1030
1031                 See the LDAP ROUTING section below for more information.
1032
1033 nodns           If you aren't running DNS at your site (for example,
1034                 you are UUCP-only connected).  It's hard to consider
1035                 this a "feature", but hey, it had to go somewhere.
1036                 Actually, as of 8.7 this is a no-op -- remove "dns" from
1037                 the hosts service switch entry instead.
1038
1039 nullclient      This is a special case -- it creates a configuration file
1040                 containing nothing but support for forwarding all mail to a
1041                 central hub via a local SMTP-based network.  The argument
1042                 is the name of that hub.
1043
1044                 The only other feature that should be used in conjunction
1045                 with this one is FEATURE(`nocanonify').  No mailers
1046                 should be defined.  No aliasing or forwarding is done.
1047
1048 local_lmtp      Use an LMTP capable local mailer.  The argument to this
1049                 feature is the pathname of an LMTP capable mailer.  By
1050                 default, mail.local is used.  This is expected to be the
1051                 mail.local which came with the 8.9 distribution which is
1052                 LMTP capable.  The path to mail.local is set by the
1053                 confEBINDIR m4 variable -- making the default
1054                 LOCAL_MAILER_PATH /usr/libexec/mail.local.
1055                 If a different LMTP capable mailer is used, its pathname
1056                 can be specified as second parameter and the arguments
1057                 passed to it (A=) as third parameter, e.g.,
1058
1059                         FEATURE(`local_lmtp', `/usr/local/bin/lmtp', `lmtp')
1060
1061                 WARNING: This feature sets LOCAL_MAILER_FLAGS unconditionally,
1062                 i.e., without respecting any definitions in an OSTYPE setting.
1063
1064 local_procmail  Use procmail or another delivery agent as the local mailer.
1065                 The argument to this feature is the pathname of the
1066                 delivery agent, which defaults to PROCMAIL_MAILER_PATH.
1067                 Note that this does NOT use PROCMAIL_MAILER_FLAGS or
1068                 PROCMAIL_MAILER_ARGS for the local mailer; tweak
1069                 LOCAL_MAILER_FLAGS and LOCAL_MAILER_ARGS instead, or
1070                 specify the appropriate parameters.  When procmail is used,
1071                 the local mailer can make use of the
1072                 "user+indicator@local.host" syntax; normally the +indicator
1073                 is just tossed, but by default it is passed as the -a
1074                 argument to procmail.
1075
1076                 This feature can take up to three arguments:
1077
1078                 1. Path to the mailer program
1079                    [default: /usr/local/bin/procmail]
1080                 2. Argument vector including name of the program
1081                    [default: procmail -Y -a $h -d $u]
1082                 3. Flags for the mailer [default: SPfhn9]
1083
1084                 Empty arguments cause the defaults to be taken.
1085                 Note that if you are on a system with a broken
1086                 setreuid() call, you may need to add -f $f to the procmail
1087                 argument vector to pass the proper sender to procmail.
1088
1089                 For example, this allows it to use the maildrop
1090                 (http://www.flounder.net/~mrsam/maildrop/) mailer instead
1091                 by specifying:
1092
1093                 FEATURE(`local_procmail', `/usr/local/bin/maildrop',
1094                  `maildrop -d $u')
1095
1096                 or scanmails using:
1097
1098                 FEATURE(`local_procmail', `/usr/local/bin/scanmails')
1099
1100                 WARNING: This feature sets LOCAL_MAILER_FLAGS unconditionally,
1101                 i.e.,  without respecting any definitions in an OSTYPE setting.
1102
1103 bestmx_is_local Accept mail as though locally addressed for any host that
1104                 lists us as the best possible MX record.  This generates
1105                 additional DNS traffic, but should be OK for low to
1106                 medium traffic hosts.  The argument may be a set of
1107                 domains, which will limit the feature to only apply to
1108                 these domains -- this will reduce unnecessary DNS
1109                 traffic.  THIS FEATURE IS FUNDAMENTALLY INCOMPATIBLE WITH
1110                 WILDCARD MX RECORDS!!!  If you have a wildcard MX record
1111                 that matches your domain, you cannot use this feature.
1112
1113 smrsh           Use the SendMail Restricted SHell (smrsh) provided
1114                 with the distribution instead of /bin/sh for mailing
1115                 to programs.  This improves the ability of the local
1116                 system administrator to control what gets run via
1117                 e-mail.  If an argument is provided it is used as the
1118                 pathname to smrsh; otherwise, the path defined by
1119                 confEBINDIR is used for the smrsh binary -- by default,
1120                 /usr/libexec/smrsh is assumed.
1121
1122 promiscuous_relay
1123                 By default, the sendmail configuration files do not permit
1124                 mail relaying (that is, accepting mail from outside your
1125                 local host (class {w}) and sending it to another host than
1126                 your local host).  This option sets your site to allow
1127                 mail relaying from any site to any site.  In almost all
1128                 cases, it is better to control relaying more carefully
1129                 with the access map, class {R}, or authentication.  Domains
1130                 can be added to class {R} by the macros RELAY_DOMAIN or
1131                 RELAY_DOMAIN_FILE (analogously to MASQUERADE_DOMAIN and
1132                 MASQUERADE_DOMAIN_FILE, see below).
1133
1134 relay_entire_domain
1135                 This option allows any host in your domain as defined by
1136                 class {m} to use your server for relaying.  Notice: make
1137                 sure that your domain is not just a top level domain,
1138                 e.g., com.  This can happen if you give your host a name
1139                 like example.com instead of host.example.com.
1140
1141 relay_hosts_only
1142                 By default, names that are listed as RELAY in the access
1143                 db and class {R} are treated as domain names, not host names.
1144                 For example, if you specify ``foo.com'', then mail to or
1145                 from foo.com, abc.foo.com, or a.very.deep.domain.foo.com
1146                 will all be accepted for relaying.  This feature changes
1147                 the behaviour to lookup individual host names only.
1148
1149 relay_based_on_MX
1150                 Turns on the ability to allow relaying based on the MX
1151                 records of the host portion of an incoming recipient; that
1152                 is, if an MX record for host foo.com points to your site,
1153                 you will accept and relay mail addressed to foo.com.  See
1154                 description below for more information before using this
1155                 feature.  Also, see the KNOWNBUGS entry regarding bestmx
1156                 map lookups.
1157
1158                 FEATURE(`relay_based_on_MX') does not necessarily allow
1159                 routing of these messages which you expect to be allowed,
1160                 if route address syntax (or %-hack syntax) is used.  If
1161                 this is a problem, add entries to the access-table or use
1162                 FEATURE(`loose_relay_check').
1163
1164 relay_mail_from
1165                 Allows relaying if the mail sender is listed as RELAY in
1166                 the access map.  If an optional argument `domain' (this
1167                 is the literal word `domain', not a placeholder) is given,
1168                 relaying can be allowed just based on the domain portion
1169                 of the sender address.  This feature should only be used if
1170                 absolutely necessary as the sender address can be easily
1171                 forged.  Use of this feature requires the "From:" tag to
1172                 be used for the key in the access map; see the discussion
1173                 of tags and FEATURE(`relay_mail_from') in the section on
1174                 anti-spam configuration control.
1175
1176 relay_local_from
1177                 Allows relaying if the domain portion of the mail sender
1178                 is a local host.  This should only be used if absolutely
1179                 necessary as it opens a window for spammers.  Specifically,
1180                 they can send mail to your mail server that claims to be
1181                 from your domain (either directly or via a routed address),
1182                 and you will go ahead and relay it out to arbitrary hosts
1183                 on the Internet.
1184
1185 accept_unqualified_senders
1186                 Normally, MAIL FROM: commands in the SMTP session will be
1187                 refused if the connection is a network connection and the
1188                 sender address does not include a domain name.  If your
1189                 setup sends local mail unqualified (i.e., MAIL FROM: <joe>),
1190                 you will need to use this feature to accept unqualified
1191                 sender addresses.  Setting the DaemonPortOptions modifier
1192                 'u' overrides the default behavior, i.e., unqualified
1193                 addresses are accepted even without this FEATURE.
1194                 If this FEATURE is not used, the DaemonPortOptions modifier
1195                 'f' can be used to enforce fully qualified addresses.
1196
1197 accept_unresolvable_domains
1198                 Normally, MAIL FROM: commands in the SMTP session will be
1199                 refused if the host part of the argument to MAIL FROM:
1200                 cannot be located in the host name service (e.g., an A or
1201                 MX record in DNS).  If you are inside a firewall that has
1202                 only a limited view of the Internet host name space, this
1203                 could cause problems.  In this case you probably want to
1204                 use this feature to accept all domains on input, even if
1205                 they are unresolvable.
1206
1207 access_db       Turns on the access database feature.  The access db gives
1208                 you the ability to allow or refuse to accept mail from
1209                 specified domains for administrative reasons.  Moreover,
1210                 it can control the behavior of sendmail in various situations.
1211                 By default, the access database specification is:
1212
1213                         hash -T<TMPF> /etc/mail/access
1214
1215                 See the anti-spam configuration control section for further
1216                 important information about this feature.  Notice:
1217                 "-T<TMPF>" is meant literal, do not replace it by anything.
1218
1219 blacklist_recipients
1220                 Turns on the ability to block incoming mail for certain
1221                 recipient usernames, hostnames, or addresses.  For
1222                 example, you can block incoming mail to user nobody,
1223                 host foo.mydomain.com, or guest@bar.mydomain.com.
1224                 These specifications are put in the access db as
1225                 described in the anti-spam configuration control section
1226                 later in this document.
1227
1228 delay_checks    The rulesets check_mail and check_relay will not be called
1229                 when a client connects or issues a MAIL command, respectively.
1230                 Instead, those rulesets will be called by the check_rcpt
1231                 ruleset; they will be skipped under certain circumstances.
1232                 See "Delay all checks" in the anti-spam configuration control
1233                 section.  Note: this feature is incompatible to the versions
1234                 in 8.10 and 8.11.
1235
1236 use_client_ptr  If this feature is enabled then check_relay will override
1237                 its first argument with $&{client_ptr}.  This is useful for
1238                 rejections based on the unverified hostname of client,
1239                 which turns on the same behavior as in earlier sendmail
1240                 versions when delay_checks was not in use.  See doc/op/op.*
1241                 about check_relay, {client_name}, and {client_ptr}.
1242
1243 dnsbl           Turns on rejection of hosts found in an DNS based rejection
1244                 list.  If an argument is provided it is used as the domain
1245                 in which blocked hosts are listed; otherwise it defaults to
1246                 blackholes.mail-abuse.org.  An explanation for an DNS based
1247                 rejection list can be found at http://mail-abuse.org/rbl/.
1248                 A second argument can be used to change the default error
1249                 message.  Without that second argument, the error message
1250                 will be
1251                         Rejected: IP-ADDRESS listed at SERVER
1252                 where IP-ADDRESS and SERVER are replaced by the appropriate
1253                 information.  By default, temporary lookup failures are
1254                 ignored.  This behavior can be changed by specifying a
1255                 third argument, which must be either `t' or a full error
1256                 message.  See the anti-spam configuration control section for
1257                 an example.  The dnsbl feature can be included several times
1258                 to query different DNS based rejection lists.  See also
1259                 enhdnsbl for an enhanced version.
1260
1261                 Set the DNSBL_MAP mc option to change the default map
1262                 definition from `host'.  Set the DNSBL_MAP_OPT mc option
1263                 to add additional options to the map specification used.
1264
1265                 Some DNS based rejection lists cause failures if asked
1266                 for AAAA records. If your sendmail version is compiled
1267                 with IPv6 support (NETINET6) and you experience this
1268                 problem, add
1269
1270                         define(`DNSBL_MAP', `dns -R A')
1271
1272                 before the first use of this feature.  Alternatively you
1273                 can use enhdnsbl instead (see below).  Moreover, this
1274                 statement can be used to reduce the number of DNS retries,
1275                 e.g.,
1276
1277                         define(`DNSBL_MAP', `dns -R A -r2')
1278
1279                 See below (EDNSBL_TO) for an explanation.
1280
1281                 NOTE: The default DNS blacklist, blackholes.mail-abuse.org,
1282                 is a service offered by the Mail Abuse Prevention System
1283                 (MAPS).  As of July 31, 2001, MAPS is a subscription
1284                 service, so using that network address won't work if you
1285                 haven't subscribed.  Contact MAPS to subscribe
1286                 (http://mail-abuse.org/).
1287
1288 enhdnsbl        Enhanced version of dnsbl (see above).  Further arguments
1289                 (up to 5) can be used to specify specific return values
1290                 from lookups.  Temporary lookup failures are ignored unless
1291                 a third argument is given, which must be either `t' or a full
1292                 error message.  By default, any successful lookup will
1293                 generate an error.  Otherwise the result of the lookup is
1294                 compared with the supplied argument(s), and only if a match
1295                 occurs an error is generated.  For example,
1296
1297                 FEATURE(`enhdnsbl', `dnsbl.example.com', `', `t', `127.0.0.2.')
1298
1299                 will reject the e-mail if the lookup returns the value
1300                 ``127.0.0.2.'', or generate a 451 response if the lookup
1301                 temporarily failed.  The arguments can contain metasymbols
1302                 as they are allowed in the LHS of rules.  As the example
1303                 shows, the default values are also used if an empty argument,
1304                 i.e., `', is specified.  This feature requires that sendmail
1305                 has been compiled with the flag DNSMAP (see sendmail/README).
1306
1307                 Set the EDNSBL_TO mc option to change the DNS retry count
1308                 from the default value of 5, this can be very useful when
1309                 a DNS server is not responding, which in turn may cause
1310                 clients to time out (an entry stating
1311
1312                         did not issue MAIL/EXPN/VRFY/ETRN
1313
1314                 will be logged).
1315
1316 ratecontrol     Enable simple ruleset to do connection rate control
1317                 checking.  This requires entries in access_db of the form
1318
1319                         ClientRate:IP.ADD.RE.SS         LIMIT
1320
1321                 The RHS specifies the maximum number of connections
1322                 (an integer number) over the time interval defined
1323                 by ConnectionRateWindowSize, where 0 means unlimited.
1324
1325                 Take the following example:
1326
1327                         ClientRate:10.1.2.3             4
1328                         ClientRate:127.0.0.1            0
1329                         ClientRate:                     10
1330
1331                 10.1.2.3 can only make up to 4 connections, the
1332                 general limit it 10, and 127.0.0.1 can make an unlimited
1333                 number of connections per ConnectionRateWindowSize.
1334
1335                 See also CONNECTION CONTROL.
1336
1337 conncontrol     Enable a simple check of the number of incoming SMTP
1338                 connections.  This requires entries in access_db of the
1339                 form
1340
1341                         ClientConn:IP.ADD.RE.SS         LIMIT
1342
1343                 The RHS specifies the maximum number of open connections
1344                 (an integer number).
1345
1346                 Take the following example:
1347
1348                         ClientConn:10.1.2.3             4
1349                         ClientConn:127.0.0.1            0
1350                         ClientConn:                     10
1351
1352                 10.1.2.3 can only have up to 4 open connections, the
1353                 general limit it 10, and 127.0.0.1 does not have any
1354                 explicit limit.
1355
1356                 See also CONNECTION CONTROL.
1357
1358 mtamark         Experimental support for "Marking Mail Transfer Agents in
1359                 Reverse DNS with TXT RRs" (MTAMark), see
1360                 draft-stumpf-dns-mtamark-01.  Optional arguments are:
1361
1362                 1. Error message, default:
1363
1364                         550 Rejected: $&{client_addr} not listed as MTA
1365
1366                 2. Temporary lookup failures are ignored unless a second
1367                 argument is given, which must be either `t' or a full
1368                 error message.
1369
1370                 3. Lookup prefix, default: _perm._smtp._srv.  This should
1371                 not be changed unless the draft changes it.
1372
1373                 Example:
1374
1375                         FEATURE(`mtamark', `', `t')
1376
1377 lookupdotdomain Look up also .domain in the access map.  This allows to
1378                 match only subdomains.  It does not work well with
1379                 FEATURE(`relay_hosts_only'), because most lookups for
1380                 subdomains are suppressed by the latter feature.
1381
1382 loose_relay_check
1383                 Normally, if % addressing is used for a recipient, e.g.
1384                 user%site@othersite, and othersite is in class {R}, the
1385                 check_rcpt ruleset will strip @othersite and recheck
1386                 user@site for relaying.  This feature changes that
1387                 behavior.  It should not be needed for most installations.
1388
1389 authinfo        Provide a separate map for client side authentication
1390                 information.  See SMTP AUTHENTICATION for details.
1391                 By default, the authinfo database specification is:
1392
1393                         hash /etc/mail/authinfo
1394
1395 preserve_luser_host
1396                 Preserve the name of the recipient host if LUSER_RELAY is
1397                 used.  Without this option, the domain part of the
1398                 recipient address will be replaced by the host specified as
1399                 LUSER_RELAY.  This feature only works if the hostname is
1400                 passed to the mailer (see mailer triple in op.me).  Note
1401                 that in the default configuration the local mailer does not
1402                 receive the hostname, i.e., the mailer triple has an empty
1403                 hostname.
1404
1405 preserve_local_plus_detail
1406                 Preserve the +detail portion of the address when passing
1407                 address to local delivery agent.  Disables alias and
1408                 .forward +detail stripping (e.g., given user+detail, only
1409                 that address will be looked up in the alias file; user+* and
1410                 user will not be looked up).  Only use if the local
1411                 delivery agent in use supports +detail addressing.
1412
1413 compat_check    Enable ruleset check_compat to look up pairs of addresses
1414                 with the Compat: tag -- Compat:sender<@>recipient -- in the
1415                 access map.  Valid values for the RHS include
1416                         DISCARD silently discard recipient
1417                         TEMP:   return a temporary error
1418                         ERROR:  return a permanent error
1419                 In the last two cases, a 4xy/5xy SMTP reply code should
1420                 follow the colon.
1421
1422 no_default_msa  Don't generate the default MSA daemon, i.e.,
1423                 DAEMON_OPTIONS(`Port=587,Name=MSA,M=E')
1424                 To define a MSA daemon with other parameters, use this
1425                 FEATURE and introduce new settings via DAEMON_OPTIONS().
1426
1427 msp             Defines config file for Message Submission Program.
1428                 See sendmail/SECURITY for details and cf/cf/submit.mc how
1429                 to use it.  An optional argument can be used to override
1430                 the default of `[localhost]' to use as host to send all
1431                 e-mails to.  Note that MX records will be used if the
1432                 specified hostname is not in square brackets (e.g.,
1433                 [hostname]).  If `MSA' is specified as second argument then
1434                 port 587 is used to contact the server.  Example:
1435
1436                         FEATURE(`msp', `', `MSA')
1437
1438                 Some more hints about possible changes can be found below
1439                 in the section MESSAGE SUBMISSION PROGRAM.
1440
1441                 Note: Due to many problems, submit.mc uses
1442
1443                         FEATURE(`msp', `[127.0.0.1]')
1444
1445                 by default.  If you have a machine with IPv6 only,
1446                 change it to
1447
1448                         FEATURE(`msp', `[IPv6:::1]')
1449
1450                 If you want to continue using '[localhost]', (the behavior
1451                 up to 8.12.6), use
1452
1453                         FEATURE(`msp')
1454
1455 queuegroup      A simple example how to select a queue group based
1456                 on the full e-mail address or the domain of the
1457                 recipient.  Selection is done via entries in the
1458                 access map using the tag QGRP:, for example:
1459
1460                         QGRP:example.com        main
1461                         QGRP:friend@some.org    others
1462                         QGRP:my.domain          local
1463
1464                 where "main", "others", and "local" are names of
1465                 queue groups.  If an argument is specified, it is used
1466                 as default queue group.
1467
1468                 Note: please read the warning in doc/op/op.me about
1469                 queue groups and possible queue manipulations.
1470
1471 greet_pause     Adds the greet_pause ruleset which enables open proxy
1472                 and SMTP slamming protection.  The feature can take an
1473                 argument specifying the milliseconds to wait:
1474
1475                         FEATURE(`greet_pause', `5000')  dnl 5 seconds
1476
1477                 If FEATURE(`access_db') is enabled, an access database
1478                 lookup with the GreetPause tag is done using client
1479                 hostname, domain, IP address, or subnet to determine the
1480                 pause time:
1481
1482                         GreetPause:my.domain    0
1483                         GreetPause:example.com  5000
1484                         GreetPause:10.1.2       2000
1485                         GreetPause:127.0.0.1    0
1486
1487                 When using FEATURE(`access_db'), the optional
1488                 FEATURE(`greet_pause') argument becomes the default if
1489                 nothing is found in the access database.  A ruleset called
1490                 Local_greet_pause can be used for local modifications, e.g.,
1491
1492                         LOCAL_RULESETS
1493                         SLocal_greet_pause
1494                         R$*             $: $&{daemon_flags}
1495                         R$* a $*        $# 0
1496
1497 +-------+
1498 | HACKS |
1499 +-------+
1500
1501 Some things just can't be called features.  To make this clear,
1502 they go in the hack subdirectory and are referenced using the HACK
1503 macro.  These will tend to be site-dependent.  The release
1504 includes the Berkeley-dependent "cssubdomain" hack (that makes
1505 sendmail accept local names in either Berkeley.EDU or CS.Berkeley.EDU;
1506 this is intended as a short-term aid while moving hosts into
1507 subdomains.
1508
1509
1510 +--------------------+
1511 | SITE CONFIGURATION |
1512 +--------------------+
1513
1514     *****************************************************
1515     * This section is really obsolete, and is preserved *
1516     * only for back compatibility.  You should plan on  *
1517     * using mailertables for new installations.  In     *
1518     * particular, it doesn't work for the newer forms   *
1519     * of UUCP mailers, such as uucp-uudom.              *
1520     *****************************************************
1521
1522 Complex sites will need more local configuration information, such as
1523 lists of UUCP hosts they speak with directly.  This can get a bit more
1524 tricky.  For an example of a "complex" site, see cf/ucbvax.mc.
1525
1526 The SITECONFIG macro allows you to indirectly reference site-dependent
1527 configuration information stored in the siteconfig subdirectory.  For
1528 example, the line
1529
1530         SITECONFIG(`uucp.ucbvax', `ucbvax', `U')
1531
1532 reads the file uucp.ucbvax for local connection information.  The
1533 second parameter is the local name (in this case just "ucbvax" since
1534 it is locally connected, and hence a UUCP hostname).  The third
1535 parameter is the name of both a macro to store the local name (in
1536 this case, {U}) and the name of the class (e.g., {U}) in which to store
1537 the host information read from the file.  Another SITECONFIG line reads
1538
1539         SITECONFIG(`uucp.ucbarpa', `ucbarpa.Berkeley.EDU', `W')
1540
1541 This says that the file uucp.ucbarpa contains the list of UUCP sites
1542 connected to ucbarpa.Berkeley.EDU.  Class {W} will be used to
1543 store this list, and $W is defined to be ucbarpa.Berkeley.EDU, that
1544 is, the name of the relay to which the hosts listed in uucp.ucbarpa
1545 are connected.  [The machine ucbarpa is gone now, but this
1546 out-of-date configuration file has been left around to demonstrate
1547 how you might do this.]
1548
1549 Note that the case of SITECONFIG with a third parameter of ``U'' is
1550 special; the second parameter is assumed to be the UUCP name of the
1551 local site, rather than the name of a remote site, and the UUCP name
1552 is entered into class {w} (the list of local hostnames) as $U.UUCP.
1553
1554 The siteconfig file (e.g., siteconfig/uucp.ucbvax.m4) contains nothing
1555 more than a sequence of SITE macros describing connectivity.  For
1556 example:
1557
1558         SITE(`cnmat')
1559         SITE(`sgi olympus')
1560
1561 The second example demonstrates that you can use two names on the
1562 same line; these are usually aliases for the same host (or are at
1563 least in the same company).
1564
1565 The macro LOCAL_UUCP can be used to add rules into the generated
1566 cf file at the place where MAILER(`uucp') inserts its rules.  This
1567 should only be used if really necessary.
1568
1569 +--------------------+
1570 | USING UUCP MAILERS |
1571 +--------------------+
1572
1573 It's hard to get UUCP mailers right because of the extremely ad hoc
1574 nature of UUCP addressing.  These config files are really designed
1575 for domain-based addressing, even for UUCP sites.
1576
1577 There are four UUCP mailers available.  The choice of which one to
1578 use is partly a matter of local preferences and what is running at
1579 the other end of your UUCP connection.  Unlike good protocols that
1580 define what will go over the wire, UUCP uses the policy that you
1581 should do what is right for the other end; if they change, you have
1582 to change.  This makes it hard to do the right thing, and discourages
1583 people from updating their software.  In general, if you can avoid
1584 UUCP, please do.
1585
1586 The major choice is whether to go for a domainized scheme or a
1587 non-domainized scheme.  This depends entirely on what the other
1588 end will recognize.  If at all possible, you should encourage the
1589 other end to go to a domain-based system -- non-domainized addresses
1590 don't work entirely properly.
1591
1592 The four mailers are:
1593
1594     uucp-old (obsolete name: "uucp")
1595         This is the oldest, the worst (but the closest to UUCP) way of
1596         sending messages across UUCP connections.  It does bangify
1597         everything and prepends $U (your UUCP name) to the sender's
1598         address (which can already be a bang path itself).  It can
1599         only send to one address at a time, so it spends a lot of
1600         time copying duplicates of messages.  Avoid this if at all
1601         possible.
1602
1603     uucp-new (obsolete name: "suucp")
1604         The same as above, except that it assumes that in one rmail
1605         command you can specify several recipients.  It still has a
1606         lot of other problems.
1607
1608     uucp-dom
1609         This UUCP mailer keeps everything as domain addresses.
1610         Basically, it uses the SMTP mailer rewriting rules.  This mailer
1611         is only included if MAILER(`smtp') is specified before
1612         MAILER(`uucp').
1613
1614         Unfortunately, a lot of UUCP mailer transport agents require
1615         bangified addresses in the envelope, although you can use
1616         domain-based addresses in the message header.  (The envelope
1617         shows up as the From_ line on UNIX mail.)  So....
1618
1619     uucp-uudom
1620         This is a cross between uucp-new (for the envelope addresses)
1621         and uucp-dom (for the header addresses).  It bangifies the
1622         envelope sender (From_ line in messages) without adding the
1623         local hostname, unless there is no host name on the address
1624         at all (e.g., "wolf") or the host component is a UUCP host name
1625         instead of a domain name ("somehost!wolf" instead of
1626         "some.dom.ain!wolf").  This is also included only if MAILER(`smtp')
1627         is also specified earlier.
1628
1629 Examples:
1630
1631 On host grasp.insa-lyon.fr (UUCP host name "grasp"), the following
1632 summarizes the sender rewriting for various mailers.
1633
1634 Mailer          sender          rewriting in the envelope
1635 ------          ------          -------------------------
1636 uucp-{old,new}  wolf            grasp!wolf
1637 uucp-dom        wolf            wolf@grasp.insa-lyon.fr
1638 uucp-uudom      wolf            grasp.insa-lyon.fr!wolf
1639
1640 uucp-{old,new}  wolf@fr.net     grasp!fr.net!wolf
1641 uucp-dom        wolf@fr.net     wolf@fr.net
1642 uucp-uudom      wolf@fr.net     fr.net!wolf
1643
1644 uucp-{old,new}  somehost!wolf   grasp!somehost!wolf
1645 uucp-dom        somehost!wolf   somehost!wolf@grasp.insa-lyon.fr
1646 uucp-uudom      somehost!wolf   grasp.insa-lyon.fr!somehost!wolf
1647
1648 If you are using one of the domainized UUCP mailers, you really want
1649 to convert all UUCP addresses to domain format -- otherwise, it will
1650 do it for you (and probably not the way you expected).  For example,
1651 if you have the address foo!bar!baz (and you are not sending to foo),
1652 the heuristics will add the @uucp.relay.name or @local.host.name to
1653 this address.  However, if you map foo to foo.host.name first, it
1654 will not add the local hostname.  You can do this using the uucpdomain
1655 feature.
1656
1657
1658 +-------------------+
1659 | TWEAKING RULESETS |
1660 +-------------------+
1661
1662 For more complex configurations, you can define special rules.
1663 The macro LOCAL_RULE_3 introduces rules that are used in canonicalizing
1664 the names.  Any modifications made here are reflected in the header.
1665
1666 A common use is to convert old UUCP addresses to SMTP addresses using
1667 the UUCPSMTP macro.  For example:
1668
1669         LOCAL_RULE_3
1670         UUCPSMTP(`decvax',      `decvax.dec.com')
1671         UUCPSMTP(`research',    `research.att.com')
1672
1673 will cause addresses of the form "decvax!user" and "research!user"
1674 to be converted to "user@decvax.dec.com" and "user@research.att.com"
1675 respectively.
1676
1677 This could also be used to look up hosts in a database map:
1678
1679         LOCAL_RULE_3
1680         R$* < @ $+ > $*         $: $1 < @ $(hostmap $2 $) > $3
1681
1682 This map would be defined in the LOCAL_CONFIG portion, as shown below.
1683
1684 Similarly, LOCAL_RULE_0 can be used to introduce new parsing rules.
1685 For example, new rules are needed to parse hostnames that you accept
1686 via MX records.  For example, you might have:
1687
1688         LOCAL_RULE_0
1689         R$+ <@ host.dom.ain.>   $#uucp $@ cnmat $: $1 < @ host.dom.ain.>
1690
1691 You would use this if you had installed an MX record for cnmat.Berkeley.EDU
1692 pointing at this host; this rule catches the message and forwards it on
1693 using UUCP.
1694
1695 You can also tweak rulesets 1 and 2 using LOCAL_RULE_1 and LOCAL_RULE_2.
1696 These rulesets are normally empty.
1697
1698 A similar macro is LOCAL_CONFIG.  This introduces lines added after the
1699 boilerplate option setting but before rulesets.  Do not declare rulesets in
1700 the LOCAL_CONFIG section.  It can be used to declare local database maps or
1701 whatever.  For example:
1702
1703         LOCAL_CONFIG
1704         Khostmap hash /etc/mail/hostmap
1705         Kyplocal nis -m hosts.byname
1706
1707
1708 +---------------------------+
1709 | MASQUERADING AND RELAYING |
1710 +---------------------------+
1711
1712 You can have your host masquerade as another using
1713
1714         MASQUERADE_AS(`host.domain')
1715
1716 This causes mail being sent to be labeled as coming from the
1717 indicated host.domain, rather than $j.  One normally masquerades as
1718 one of one's own subdomains (for example, it's unlikely that
1719 Berkeley would choose to masquerade as an MIT site).  This
1720 behaviour is modified by a plethora of FEATUREs; in particular, see
1721 masquerade_envelope, allmasquerade, limited_masquerade, and
1722 masquerade_entire_domain.
1723
1724 The masquerade name is not normally canonified, so it is important
1725 that it be your One True Name, that is, fully qualified and not a
1726 CNAME.  However, if you use a CNAME, the receiving side may canonify
1727 it for you, so don't think you can cheat CNAME mapping this way.
1728
1729 Normally the only addresses that are masqueraded are those that come
1730 from this host (that is, are either unqualified or in class {w}, the list
1731 of local domain names).  You can augment this list, which is realized
1732 by class {M} using
1733
1734         MASQUERADE_DOMAIN(`otherhost.domain')
1735
1736 The effect of this is that although mail to user@otherhost.domain
1737 will not be delivered locally, any mail including any user@otherhost.domain
1738 will, when relayed, be rewritten to have the MASQUERADE_AS address.
1739 This can be a space-separated list of names.
1740
1741 If these names are in a file, you can use
1742
1743         MASQUERADE_DOMAIN_FILE(`filename')
1744
1745 to read the list of names from the indicated file (i.e., to add
1746 elements to class {M}).
1747
1748 To exempt hosts or subdomains from being masqueraded, you can use
1749
1750         MASQUERADE_EXCEPTION(`host.domain')
1751
1752 This can come handy if you want to masquerade a whole domain
1753 except for one (or a few) host(s).  If these names are in a file,
1754 you can use
1755
1756         MASQUERADE_EXCEPTION_FILE(`filename')
1757
1758 Normally only header addresses are masqueraded.  If you want to
1759 masquerade the envelope as well, use
1760
1761         FEATURE(`masquerade_envelope')
1762
1763 There are always users that need to be "exposed" -- that is, their
1764 internal site name should be displayed instead of the masquerade name.
1765 Root is an example (which has been "exposed" by default prior to 8.10).
1766 You can add users to this list using
1767
1768         EXPOSED_USER(`usernames')
1769
1770 This adds users to class {E}; you could also use
1771
1772         EXPOSED_USER_FILE(`filename')
1773
1774 You can also arrange to relay all unqualified names (that is, names
1775 without @host) to a relay host.  For example, if you have a central
1776 email server, you might relay to that host so that users don't have
1777 to have .forward files or aliases.  You can do this using
1778
1779         define(`LOCAL_RELAY', `mailer:hostname')
1780
1781 The ``mailer:'' can be omitted, in which case the mailer defaults to
1782 "relay".  There are some user names that you don't want relayed, perhaps
1783 because of local aliases.  A common example is root, which may be
1784 locally aliased.  You can add entries to this list using
1785
1786         LOCAL_USER(`usernames')
1787
1788 This adds users to class {L}; you could also use
1789
1790         LOCAL_USER_FILE(`filename')
1791
1792 If you want all incoming mail sent to a centralized hub, as for a
1793 shared /var/spool/mail scheme, use
1794
1795         define(`MAIL_HUB', `mailer:hostname')
1796
1797 Again, ``mailer:'' defaults to "relay".  If you define both LOCAL_RELAY
1798 and MAIL_HUB _AND_ you have FEATURE(`stickyhost'), unqualified names will
1799 be sent to the LOCAL_RELAY and other local names will be sent to MAIL_HUB.
1800 Note: there is a (long standing) bug which keeps this combination from
1801 working for addresses of the form user+detail.
1802 Names in class {L} will be delivered locally, so you MUST have aliases or
1803 .forward files for them.
1804
1805 For example, if you are on machine mastodon.CS.Berkeley.EDU and you have
1806 FEATURE(`stickyhost'), the following combinations of settings will have the
1807 indicated effects:
1808
1809 email sent to....       eric                      eric@mastodon.CS.Berkeley.EDU
1810
1811 LOCAL_RELAY set to      mail.CS.Berkeley.EDU      (delivered locally)
1812 mail.CS.Berkeley.EDU      (no local aliasing)       (aliasing done)
1813
1814 MAIL_HUB set to         mammoth.CS.Berkeley.EDU   mammoth.CS.Berkeley.EDU
1815 mammoth.CS.Berkeley.EDU   (aliasing done)           (aliasing done)
1816
1817 Both LOCAL_RELAY and    mail.CS.Berkeley.EDU      mammoth.CS.Berkeley.EDU
1818 MAIL_HUB set as above     (no local aliasing)       (aliasing done)
1819
1820 If you do not have FEATURE(`stickyhost') set, then LOCAL_RELAY and
1821 MAIL_HUB act identically, with MAIL_HUB taking precedence.
1822
1823 If you want all outgoing mail to go to a central relay site, define
1824 SMART_HOST as well.  Briefly:
1825
1826         LOCAL_RELAY applies to unqualified names (e.g., "eric").
1827         MAIL_HUB applies to names qualified with the name of the
1828                 local host (e.g., "eric@mastodon.CS.Berkeley.EDU").
1829         SMART_HOST applies to names qualified with other hosts or
1830                 bracketed addresses (e.g., "eric@mastodon.CS.Berkeley.EDU"
1831                 or "eric@[127.0.0.1]").
1832
1833 However, beware that other relays (e.g., UUCP_RELAY, BITNET_RELAY,
1834 DECNET_RELAY, and FAX_RELAY) take precedence over SMART_HOST, so if you
1835 really want absolutely everything to go to a single central site you will
1836 need to unset all the other relays -- or better yet, find or build a
1837 minimal config file that does this.
1838
1839 For duplicate suppression to work properly, the host name is best
1840 specified with a terminal dot:
1841
1842         define(`MAIL_HUB', `host.domain.')
1843               note the trailing dot ---^
1844
1845
1846 +-------------------------------------------+
1847 | USING LDAP FOR ALIASES, MAPS, AND CLASSES |
1848 +-------------------------------------------+
1849
1850 LDAP can be used for aliases, maps, and classes by either specifying your
1851 own LDAP map specification or using the built-in default LDAP map
1852 specification.  The built-in default specifications all provide lookups
1853 which match against either the machine's fully qualified hostname (${j}) or
1854 a "cluster".  The cluster allows you to share LDAP entries among a large
1855 number of machines without having to enter each of the machine names into
1856 each LDAP entry.  To set the LDAP cluster name to use for a particular
1857 machine or set of machines, set the confLDAP_CLUSTER m4 variable to a
1858 unique name.  For example:
1859
1860         define(`confLDAP_CLUSTER', `Servers')
1861
1862 Here, the word `Servers' will be the cluster name.  As an example, assume
1863 that smtp.sendmail.org, etrn.sendmail.org, and mx.sendmail.org all belong
1864 to the Servers cluster.
1865
1866 Some of the LDAP LDIF examples below show use of the Servers cluster.
1867 Every entry must have either a sendmailMTAHost or sendmailMTACluster
1868 attribute or it will be ignored.  Be careful as mixing clusters and
1869 individual host records can have surprising results (see the CAUTION
1870 sections below).
1871
1872 See the file cf/sendmail.schema for the actual LDAP schemas.  Note that
1873 this schema (and therefore the lookups and examples below) is experimental
1874 at this point as it has had little public review.  Therefore, it may change
1875 in future versions.  Feedback via sendmail@sendmail.org is encouraged.
1876
1877 -------
1878 Aliases
1879 -------
1880
1881 The ALIAS_FILE (O AliasFile) option can be set to use LDAP for alias
1882 lookups.  To use the default schema, simply use:
1883
1884         define(`ALIAS_FILE', `ldap:')
1885
1886 By doing so, you will use the default schema which expands to a map
1887 declared as follows:
1888
1889         ldap -k (&(objectClass=sendmailMTAAliasObject)
1890                   (sendmailMTAAliasGrouping=aliases)
1891                   (|(sendmailMTACluster=${sendmailMTACluster})
1892                     (sendmailMTAHost=$j))
1893                   (sendmailMTAKey=%0))
1894              -v sendmailMTAAliasValue,sendmailMTAAliasSearch:FILTER:sendmailMTAAliasObject,sendmailMTAAliasURL:URL:sendmailMTAAliasObject
1895
1896
1897 NOTE: The macros shown above ${sendmailMTACluster} and $j are not actually
1898 used when the binary expands the `ldap:' token as the AliasFile option is
1899 not actually macro-expanded when read from the sendmail.cf file.
1900
1901 Example LDAP LDIF entries might be:
1902
1903         dn: sendmailMTAKey=sendmail-list, dc=sendmail, dc=org
1904         objectClass: sendmailMTA
1905         objectClass: sendmailMTAAlias
1906         objectClass: sendmailMTAAliasObject
1907         sendmailMTAAliasGrouping: aliases
1908         sendmailMTAHost: etrn.sendmail.org
1909         sendmailMTAKey: sendmail-list
1910         sendmailMTAAliasValue: ca@example.org
1911         sendmailMTAAliasValue: eric
1912         sendmailMTAAliasValue: gshapiro@example.com
1913
1914         dn: sendmailMTAKey=owner-sendmail-list, dc=sendmail, dc=org
1915         objectClass: sendmailMTA
1916         objectClass: sendmailMTAAlias
1917         objectClass: sendmailMTAAliasObject
1918         sendmailMTAAliasGrouping: aliases
1919         sendmailMTAHost: etrn.sendmail.org
1920         sendmailMTAKey: owner-sendmail-list
1921         sendmailMTAAliasValue: eric
1922
1923         dn: sendmailMTAKey=postmaster, dc=sendmail, dc=org
1924         objectClass: sendmailMTA
1925         objectClass: sendmailMTAAlias
1926         objectClass: sendmailMTAAliasObject
1927         sendmailMTAAliasGrouping: aliases
1928         sendmailMTACluster: Servers
1929         sendmailMTAKey: postmaster
1930         sendmailMTAAliasValue: eric
1931
1932 Here, the aliases sendmail-list and owner-sendmail-list will be available
1933 only on etrn.sendmail.org but the postmaster alias will be available on
1934 every machine in the Servers cluster (including etrn.sendmail.org).
1935
1936 CAUTION: aliases are additive so that entries like these:
1937
1938         dn: sendmailMTAKey=bob, dc=sendmail, dc=org
1939         objectClass: sendmailMTA
1940         objectClass: sendmailMTAAlias
1941         objectClass: sendmailMTAAliasObject
1942         sendmailMTAAliasGrouping: aliases
1943         sendmailMTACluster: Servers
1944         sendmailMTAKey: bob
1945         sendmailMTAAliasValue: eric
1946
1947         dn: sendmailMTAKey=bobetrn, dc=sendmail, dc=org
1948         objectClass: sendmailMTA
1949         objectClass: sendmailMTAAlias
1950         objectClass: sendmailMTAAliasObject
1951         sendmailMTAAliasGrouping: aliases
1952         sendmailMTAHost: etrn.sendmail.org
1953         sendmailMTAKey: bob
1954         sendmailMTAAliasValue: gshapiro
1955
1956 would mean that on all of the hosts in the cluster, mail to bob would go to
1957 eric EXCEPT on etrn.sendmail.org in which case it would go to BOTH eric and
1958 gshapiro.
1959
1960 If you prefer not to use the default LDAP schema for your aliases, you can
1961 specify the map parameters when setting ALIAS_FILE.  For example:
1962
1963         define(`ALIAS_FILE', `ldap:-k (&(objectClass=mailGroup)(mail=%0)) -v mgrpRFC822MailMember')
1964
1965 ----
1966 Maps
1967 ----
1968
1969 FEATURE()'s which take an optional map definition argument (e.g., access,
1970 mailertable, virtusertable, etc.) can instead take the special keyword
1971 `LDAP', e.g.:
1972
1973         FEATURE(`access_db', `LDAP')
1974         FEATURE(`virtusertable', `LDAP')
1975
1976 When this keyword is given, that map will use LDAP lookups consisting of
1977 the objectClass sendmailMTAClassObject, the attribute sendmailMTAMapName
1978 with the map name, a search attribute of sendmailMTAKey, and the value
1979 attribute sendmailMTAMapValue.
1980
1981 The values for sendmailMTAMapName are:
1982
1983         FEATURE()               sendmailMTAMapName
1984         ---------               ------------------
1985         access_db               access
1986         authinfo                authinfo
1987         bitdomain               bitdomain
1988         domaintable             domain
1989         genericstable           generics
1990         mailertable             mailer
1991         uucpdomain              uucpdomain
1992         virtusertable           virtuser
1993
1994 For example, FEATURE(`mailertable', `LDAP') would use the map definition:
1995
1996         Kmailertable ldap -k (&(objectClass=sendmailMTAMapObject)
1997                                (sendmailMTAMapName=mailer)
1998                                (|(sendmailMTACluster=${sendmailMTACluster})
1999                                  (sendmailMTAHost=$j))
2000                                (sendmailMTAKey=%0))
2001                           -1 -v sendmailMTAMapValue,sendmailMTAMapSearch:FILTER:sendmailMTAMapObject,sendmailMTAMapURL:URL:sendmailMTAMapObject
2002
2003 An example LDAP LDIF entry using this map might be:
2004
2005         dn: sendmailMTAMapName=mailer, dc=sendmail, dc=org
2006         objectClass: sendmailMTA
2007         objectClass: sendmailMTAMap
2008         sendmailMTACluster: Servers
2009         sendmailMTAMapName: mailer
2010
2011         dn: sendmailMTAKey=example.com, sendmailMTAMapName=mailer, dc=sendmail, dc=org
2012         objectClass: sendmailMTA
2013         objectClass: sendmailMTAMap
2014         objectClass: sendmailMTAMapObject
2015         sendmailMTAMapName: mailer
2016         sendmailMTACluster: Servers
2017         sendmailMTAKey: example.com
2018         sendmailMTAMapValue: relay:[smtp.example.com]
2019
2020 CAUTION: If your LDAP database contains the record above and *ALSO* a host
2021 specific record such as:
2022
2023         dn: sendmailMTAKey=example.com@etrn, sendmailMTAMapName=mailer, dc=sendmail, dc=org
2024         objectClass: sendmailMTA
2025         objectClass: sendmailMTAMap
2026         objectClass: sendmailMTAMapObject
2027         sendmailMTAMapName: mailer
2028         sendmailMTAHost: etrn.sendmail.org
2029         sendmailMTAKey: example.com
2030         sendmailMTAMapValue: relay:[mx.example.com]
2031
2032 then these entries will give unexpected results.  When the lookup is done
2033 on etrn.sendmail.org, the effect is that there is *NO* match at all as maps
2034 require a single match.  Since the host etrn.sendmail.org is also in the
2035 Servers cluster, LDAP would return two answers for the example.com map key
2036 in which case sendmail would treat this as no match at all.
2037
2038 If you prefer not to use the default LDAP schema for your maps, you can
2039 specify the map parameters when using the FEATURE().  For example:
2040
2041         FEATURE(`access_db', `ldap:-1 -k (&(objectClass=mapDatabase)(key=%0)) -v value')
2042
2043 -------
2044 Classes
2045 -------
2046
2047 Normally, classes can be filled via files or programs.  As of 8.12, they
2048 can also be filled via map lookups using a new syntax:
2049
2050         F{ClassName}mapkey@mapclass:mapspec
2051
2052 mapkey is optional and if not provided the map key will be empty.  This can
2053 be used with LDAP to read classes from LDAP.  Note that the lookup is only
2054 done when sendmail is initially started.  Use the special value `@LDAP' to
2055 use the default LDAP schema.  For example:
2056
2057         RELAY_DOMAIN_FILE(`@LDAP')
2058
2059 would put all of the attribute sendmailMTAClassValue values of LDAP records
2060 with objectClass sendmailMTAClass and an attribute sendmailMTAClassName of
2061 'R' into class $={R}.  In other words, it is equivalent to the LDAP map
2062 specification:
2063
2064         F{R}@ldap:-k (&(objectClass=sendmailMTAClass)
2065                        (sendmailMTAClassName=R)
2066                        (|(sendmailMTACluster=${sendmailMTACluster})
2067                          (sendmailMTAHost=$j)))
2068                   -v sendmailMTAClassValue,sendmailMTAClassSearch:FILTER:sendmailMTAClass,sendmailMTAClassURL:URL:sendmailMTAClass
2069
2070 NOTE: The macros shown above ${sendmailMTACluster} and $j are not actually
2071 used when the binary expands the `@LDAP' token as class declarations are
2072 not actually macro-expanded when read from the sendmail.cf file.
2073
2074 This can be used with class related commands such as RELAY_DOMAIN_FILE(),
2075 MASQUERADE_DOMAIN_FILE(), etc:
2076
2077         Command                         sendmailMTAClassName
2078         -------                         --------------------
2079         CANONIFY_DOMAIN_FILE()          Canonify
2080         EXPOSED_USER_FILE()             E
2081         GENERICS_DOMAIN_FILE()          G
2082         LDAPROUTE_DOMAIN_FILE()         LDAPRoute
2083         LDAPROUTE_EQUIVALENT_FILE()     LDAPRouteEquiv
2084         LOCAL_USER_FILE()               L
2085         MASQUERADE_DOMAIN_FILE()        M
2086         MASQUERADE_EXCEPTION_FILE()     N
2087         RELAY_DOMAIN_FILE()             R
2088         VIRTUSER_DOMAIN_FILE()          VirtHost
2089
2090 You can also add your own as any 'F'ile class of the form:
2091
2092         F{ClassName}@LDAP
2093           ^^^^^^^^^
2094 will use "ClassName" for the sendmailMTAClassName.
2095
2096 An example LDAP LDIF entry would look like:
2097
2098         dn: sendmailMTAClassName=R, dc=sendmail, dc=org
2099         objectClass: sendmailMTA
2100         objectClass: sendmailMTAClass
2101         sendmailMTACluster: Servers
2102         sendmailMTAClassName: R
2103         sendmailMTAClassValue: sendmail.org
2104         sendmailMTAClassValue: example.com
2105         sendmailMTAClassValue: 10.56.23
2106
2107 CAUTION: If your LDAP database contains the record above and *ALSO* a host
2108 specific record such as:
2109
2110         dn: sendmailMTAClassName=R@etrn.sendmail.org, dc=sendmail, dc=org
2111         objectClass: sendmailMTA
2112         objectClass: sendmailMTAClass
2113         sendmailMTAHost: etrn.sendmail.org
2114         sendmailMTAClassName: R
2115         sendmailMTAClassValue: example.com
2116
2117 the result will be similar to the aliases caution above.  When the lookup
2118 is done on etrn.sendmail.org, $={R} would contain all of the entries (from
2119 both the cluster match and the host match).  In other words, the effective
2120 is additive.
2121
2122 If you prefer not to use the default LDAP schema for your classes, you can
2123 specify the map parameters when using the class command.  For example:
2124
2125         VIRTUSER_DOMAIN_FILE(`@ldap:-k (&(objectClass=virtHosts)(host=*)) -v host')
2126
2127 Remember, macros can not be used in a class declaration as the binary does
2128 not expand them.
2129
2130
2131 +--------------+
2132 | LDAP ROUTING |
2133 +--------------+
2134
2135 FEATURE(`ldap_routing') can be used to implement the IETF Internet Draft
2136 LDAP Schema for Intranet Mail Routing
2137 (draft-lachman-laser-ldap-mail-routing-01).  This feature enables
2138 LDAP-based rerouting of a particular address to either a different host
2139 or a different address.  The LDAP lookup is first attempted on the full
2140 address (e.g., user@example.com) and then on the domain portion
2141 (e.g., @example.com).  Be sure to setup your domain for LDAP routing using
2142 LDAPROUTE_DOMAIN(), e.g.:
2143
2144         LDAPROUTE_DOMAIN(`example.com')
2145
2146 Additionally, you can specify equivalent domains for LDAP routing using
2147 LDAPROUTE_EQUIVALENT() and LDAPROUTE_EQUIVALENT_FILE().  'Equivalent'
2148 hostnames are mapped to $M (the masqueraded hostname for the server) before
2149 the LDAP query.  For example, if the mail is addressed to
2150 user@host1.example.com, normally the LDAP lookup would only be done for
2151 'user@host1.example.com' and '@host1.example.com'.   However, if
2152 LDAPROUTE_EQUIVALENT(`host1.example.com') is used, the lookups would also be
2153 done on 'user@example.com' and '@example.com' after attempting the
2154 host1.example.com lookups.
2155
2156 By default, the feature will use the schemas as specified in the draft
2157 and will not reject addresses not found by the LDAP lookup.  However,
2158 this behavior can be changed by giving additional arguments to the FEATURE()
2159 command:
2160
2161  FEATURE(`ldap_routing', <mailHost>, <mailRoutingAddress>, <bounce>,
2162                  <detail>, <nodomain>, <tempfail>)
2163
2164 where <mailHost> is a map definition describing how to lookup an alternative
2165 mail host for a particular address; <mailRoutingAddress> is a map definition
2166 describing how to lookup an alternative address for a particular address;
2167 the <bounce> argument, if present and not the word "passthru", dictates
2168 that mail should be bounced if neither a mailHost nor mailRoutingAddress
2169 is found, if set to "sendertoo", the sender will be rejected if not
2170 found in LDAP; and <detail> indicates what actions to take if the address
2171 contains +detail information -- `strip' tries the lookup with the +detail
2172 and if no matches are found, strips the +detail and tries the lookup again;
2173 `preserve', does the same as `strip' but if a mailRoutingAddress match is
2174 found, the +detail information is copied to the new address; the <nodomain>
2175 argument, if present, will prevent the @domain lookup if the full
2176 address is not found in LDAP; the <tempfail> argument, if set to
2177 "tempfail", instructs the rules to give an SMTP 4XX temporary
2178 error if the LDAP server gives the MTA a temporary failure, or if set to
2179 "queue" (the default), the MTA will locally queue the mail.
2180
2181 The default <mailHost> map definition is:
2182
2183         ldap -1 -T<TMPF> -v mailHost -k (&(objectClass=inetLocalMailRecipient)
2184                                  (mailLocalAddress=%0))
2185
2186 The default <mailRoutingAddress> map definition is:
2187
2188         ldap -1 -T<TMPF> -v mailRoutingAddress
2189                          -k (&(objectClass=inetLocalMailRecipient)
2190                               (mailLocalAddress=%0))
2191
2192 Note that neither includes the LDAP server hostname (-h server) or base DN
2193 (-b o=org,c=COUNTRY), both necessary for LDAP queries.  It is presumed that
2194 your .mc file contains a setting for the confLDAP_DEFAULT_SPEC option with
2195 these settings.  If this is not the case, the map definitions should be
2196 changed as described above.  The "-T<TMPF>" is required in any user
2197 specified map definition to catch temporary errors.
2198
2199 The following possibilities exist as a result of an LDAP lookup on an
2200 address:
2201
2202         mailHost is     mailRoutingAddress is   Results in
2203         -----------     ---------------------   ----------
2204         set to a        set                     mail delivered to
2205         "local" host                            mailRoutingAddress
2206
2207         set to a        not set                 delivered to
2208         "local" host                            original address
2209
2210         set to a        set                     mailRoutingAddress
2211         remote host                             relayed to mailHost
2212
2213         set to a        not set                 original address
2214         remote host                             relayed to mailHost
2215
2216         not set         set                     mail delivered to
2217                                                 mailRoutingAddress
2218
2219         not set         not set                 delivered to
2220                                                 original address *OR*
2221                                                 bounced as unknown user
2222
2223 The term "local" host above means the host specified is in class {w}.  If
2224 the result would mean sending the mail to a different host, that host is
2225 looked up in the mailertable before delivery.
2226
2227 Note that the last case depends on whether the third argument is given
2228 to the FEATURE() command.  The default is to deliver the message to the
2229 original address.
2230
2231 The LDAP entries should be set up with an objectClass of
2232 inetLocalMailRecipient and the address be listed in a mailLocalAddress
2233 attribute.  If present, there must be only one mailHost attribute and it
2234 must contain a fully qualified host name as its value.  Similarly, if
2235 present, there must be only one mailRoutingAddress attribute and it must
2236 contain an RFC 822 compliant address.  Some example LDAP records (in LDIF
2237 format):
2238
2239         dn: uid=tom, o=example.com, c=US
2240         objectClass: inetLocalMailRecipient
2241         mailLocalAddress: tom@example.com
2242         mailRoutingAddress: thomas@mailhost.example.com
2243
2244 This would deliver mail for tom@example.com to thomas@mailhost.example.com.
2245
2246         dn: uid=dick, o=example.com, c=US
2247         objectClass: inetLocalMailRecipient
2248         mailLocalAddress: dick@example.com
2249         mailHost: eng.example.com
2250
2251 This would relay mail for dick@example.com to the same address but redirect
2252 the mail to MX records listed for the host eng.example.com (unless the
2253 mailertable overrides).
2254
2255         dn: uid=harry, o=example.com, c=US
2256         objectClass: inetLocalMailRecipient
2257         mailLocalAddress: harry@example.com
2258         mailHost: mktmail.example.com
2259         mailRoutingAddress: harry@mkt.example.com
2260
2261 This would relay mail for harry@example.com to the MX records listed for
2262 the host mktmail.example.com using the new address harry@mkt.example.com
2263 when talking to that host.
2264
2265         dn: uid=virtual.example.com, o=example.com, c=US
2266         objectClass: inetLocalMailRecipient
2267         mailLocalAddress: @virtual.example.com
2268         mailHost: server.example.com
2269         mailRoutingAddress: virtual@example.com
2270
2271 This would send all mail destined for any username @virtual.example.com to
2272 the machine server.example.com's MX servers and deliver to the address
2273 virtual@example.com on that relay machine.
2274
2275
2276 +---------------------------------+
2277 | ANTI-SPAM CONFIGURATION CONTROL |
2278 +---------------------------------+
2279
2280 The primary anti-spam features available in sendmail are:
2281
2282 * Relaying is denied by default.
2283 * Better checking on sender information.
2284 * Access database.
2285 * Header checks.
2286
2287 Relaying (transmission of messages from a site outside your host (class
2288 {w}) to another site except yours) is denied by default.  Note that this
2289 changed in sendmail 8.9; previous versions allowed relaying by default.
2290 If you really want to revert to the old behaviour, you will need to use
2291 FEATURE(`promiscuous_relay').  You can allow certain domains to relay
2292 through your server by adding their domain name or IP address to class
2293 {R} using RELAY_DOMAIN() and RELAY_DOMAIN_FILE() or via the access database
2294 (described below).  Note that IPv6 addresses must be prefaced with "IPv6:".
2295 The file consists (like any other file based class) of entries listed on
2296 separate lines, e.g.,
2297
2298         sendmail.org
2299         128.32
2300         IPv6:2002:c0a8:02c7
2301         IPv6:2002:c0a8:51d2::23f4
2302         host.mydomain.com
2303         [UNIX:localhost]
2304
2305 Notice: the last entry allows relaying for connections via a UNIX
2306 socket to the MTA/MSP.  This might be necessary if your configuration
2307 doesn't allow relaying by other means in that case, e.g., by having
2308 localhost.$m in class {R} (make sure $m is not just a top level
2309 domain).
2310
2311 If you use
2312
2313         FEATURE(`relay_entire_domain')
2314
2315 then any host in any of your local domains (that is, class {m})
2316 will be relayed (that is, you will accept mail either to or from any
2317 host in your domain).
2318
2319 You can also allow relaying based on the MX records of the host
2320 portion of an incoming recipient address by using
2321
2322         FEATURE(`relay_based_on_MX')
2323
2324 For example, if your server receives a recipient of user@domain.com
2325 and domain.com lists your server in its MX records, the mail will be
2326 accepted for relay to domain.com.  This feature may cause problems
2327 if MX lookups for the recipient domain are slow or time out.  In that
2328 case, mail will be temporarily rejected.  It is usually better to
2329 maintain a list of hosts/domains for which the server acts as relay.
2330 Note also that this feature will stop spammers from using your host
2331 to relay spam but it will not stop outsiders from using your server
2332 as a relay for their site (that is, they set up an MX record pointing
2333 to your mail server, and you will relay mail addressed to them
2334 without any prior arrangement).  Along the same lines,
2335
2336         FEATURE(`relay_local_from')
2337
2338 will allow relaying if the sender specifies a return path (i.e.
2339 MAIL FROM: <user@domain>) domain which is a local domain.  This is a
2340 dangerous feature as it will allow spammers to spam using your mail
2341 server by simply specifying a return address of user@your.domain.com.
2342 It should not be used unless absolutely necessary.
2343 A slightly better solution is
2344
2345         FEATURE(`relay_mail_from')
2346
2347 which allows relaying if the mail sender is listed as RELAY in the
2348 access map.  If an optional argument `domain' (this is the literal
2349 word `domain', not a placeholder) is given, the domain portion of
2350 the mail sender is also checked to allowing relaying.  This option
2351 only works together with the tag From: for the LHS of the access
2352 map entries.  This feature allows spammers to abuse your mail server
2353 by specifying a return address that you enabled in your access file.
2354 This may be harder to figure out for spammers, but it should not
2355 be used unless necessary.  Instead use SMTP AUTH or STARTTLS to
2356 allow relaying for roaming users.
2357
2358
2359 If source routing is used in the recipient address (e.g.,
2360 RCPT TO: <user%site.com@othersite.com>), sendmail will check
2361 user@site.com for relaying if othersite.com is an allowed relay host
2362 in either class {R}, class {m} if FEATURE(`relay_entire_domain') is used,
2363 or the access database if FEATURE(`access_db') is used.  To prevent
2364 the address from being stripped down, use:
2365
2366         FEATURE(`loose_relay_check')
2367
2368 If you think you need to use this feature, you probably do not.  This
2369 should only be used for sites which have no control over the addresses
2370 that they provide a gateway for.  Use this FEATURE with caution as it
2371 can allow spammers to relay through your server if not setup properly.
2372
2373 NOTICE: It is possible to relay mail through a system which the anti-relay
2374 rules do not prevent: the case of a system that does use FEATURE(`nouucp',
2375 `nospecial') (system A) and relays local messages to a mail hub (e.g., via
2376 LOCAL_RELAY or LUSER_RELAY) (system B).  If system B doesn't use
2377 FEATURE(`nouucp') at all, addresses of the form
2378 <example.net!user@local.host> would be relayed to <user@example.net>.
2379 System A doesn't recognize `!' as an address separator and therefore
2380 forwards it to the mail hub which in turns relays it because it came from
2381 a trusted local host.  So if a mailserver allows UUCP (bang-format)
2382 addresses, all systems from which it allows relaying should do the same
2383 or reject those addresses.
2384
2385 As of 8.9, sendmail will refuse mail if the MAIL FROM: parameter has
2386 an unresolvable domain (i.e., one that DNS, your local name service,
2387 or special case rules in ruleset 3 cannot locate).  This also applies
2388 to addresses that use domain literals, e.g., <user@[1.2.3.4]>, if the
2389 IP address can't be mapped to a host name.  If you want to continue
2390 to accept such domains, e.g., because you are inside a firewall that
2391 has only a limited view of the Internet host name space (note that you
2392 will not be able to return mail to them unless you have some "smart
2393 host" forwarder), use
2394
2395         FEATURE(`accept_unresolvable_domains')
2396
2397 Alternatively, you can allow specific addresses by adding them to
2398 the access map, e.g.,
2399
2400         From:unresolvable.domain        OK
2401         From:[1.2.3.4]                  OK
2402         From:[1.2.4]                    OK
2403
2404 Notice: domains which are temporarily unresolvable are (temporarily)
2405 rejected with a 451 reply code.  If those domains should be accepted
2406 (which is discouraged) then you can use
2407
2408         LOCAL_CONFIG
2409         C{ResOk}TEMP
2410
2411 sendmail will also refuse mail if the MAIL FROM: parameter is not
2412 fully qualified (i.e., contains a domain as well as a user).  If you
2413 want to continue to accept such senders, use
2414
2415         FEATURE(`accept_unqualified_senders')
2416
2417 Setting the DaemonPortOptions modifier 'u' overrides the default behavior,
2418 i.e., unqualified addresses are accepted even without this FEATURE.  If
2419 this FEATURE is not used, the DaemonPortOptions modifier 'f' can be used
2420 to enforce fully qualified domain names.
2421
2422 An ``access'' database can be created to accept or reject mail from
2423 selected domains.  For example, you may choose to reject all mail
2424 originating from known spammers.  To enable such a database, use
2425
2426         FEATURE(`access_db')
2427
2428 Notice: the access database is applied to the envelope addresses
2429 and the connection information, not to the header.
2430
2431 The FEATURE macro can accept as second parameter the key file
2432 definition for the database; for example
2433
2434         FEATURE(`access_db', `hash -T<TMPF> /etc/mail/access_map')
2435
2436 Notice: If a second argument is specified it must contain the option
2437 `-T<TMPF>' as shown above.  The optional third and fourth parameters
2438 may be `skip' or `lookupdotdomain'.  The former enables SKIP as
2439 value part (see below), the latter is another way to enable the
2440 feature of the same name (see above).
2441
2442 Remember, since /etc/mail/access is a database, after creating the text
2443 file as described below, you must use makemap to create the database
2444 map.  For example:
2445
2446         makemap hash /etc/mail/access < /etc/mail/access
2447
2448 The table itself uses e-mail addresses, domain names, and network
2449 numbers as keys.  Note that IPv6 addresses must be prefaced with "IPv6:".
2450 For example,
2451
2452         From:spammer@aol.com                    REJECT
2453         From:cyberspammer.com                   REJECT
2454         Connect:cyberspammer.com                REJECT
2455         Connect:TLD                             REJECT
2456         Connect:192.168.212                     REJECT
2457         Connect:IPv6:2002:c0a8:02c7             RELAY
2458         Connect:IPv6:2002:c0a8:51d2::23f4       REJECT
2459
2460 would refuse mail from spammer@aol.com, any user from cyberspammer.com
2461 (or any host within the cyberspammer.com domain), any host in the entire
2462 top level domain TLD, 192.168.212.* network, and the IPv6 address
2463 2002:c0a8:51d2::23f4.  It would allow relay for the IPv6 network
2464 2002:c0a8:02c7::/48.
2465
2466 Entries in the access map should be tagged according to their type.
2467 Three tags are available:
2468
2469         Connect:        connection information (${client_addr}, ${client_name})
2470         From:           envelope sender
2471         To:             envelope recipient
2472
2473 Notice: untagged entries are deprecated.
2474
2475 If the required item is looked up in a map, it will be tried first
2476 with the corresponding tag in front, then (as fallback to enable
2477 backward compatibility) without any tag, unless the specific feature
2478 requires a tag.  For example,
2479
2480         From:spammer@some.dom   REJECT
2481         To:friend.domain        RELAY
2482         Connect:friend.domain   OK
2483         Connect:from.domain     RELAY
2484         From:good@another.dom   OK
2485         From:another.dom        REJECT
2486
2487 This would deny mails from spammer@some.dom but you could still
2488 send mail to that address even if FEATURE(`blacklist_recipients')
2489 is enabled.  Your system will allow relaying to friend.domain, but
2490 not from it (unless enabled by other means).  Connections from that
2491 domain will be allowed even if it ends up in one of the DNS based
2492 rejection lists.  Relaying is enabled from from.domain but not to
2493 it (since relaying is based on the connection information for
2494 outgoing relaying, the tag Connect: must be used; for incoming
2495 relaying, which is based on the recipient address, To: must be
2496 used).  The last two entries allow mails from good@another.dom but
2497 reject mail from all other addresses with another.dom as domain
2498 part.
2499
2500
2501 The value part of the map can contain:
2502
2503         OK              Accept mail even if other rules in the running
2504                         ruleset would reject it, for example, if the domain
2505                         name is unresolvable.  "Accept" does not mean
2506                         "relay", but at most acceptance for local
2507                         recipients.  That is, OK allows less than RELAY.
2508         RELAY           Accept mail addressed to the indicated domain or
2509                         received from the indicated domain for relaying
2510                         through your SMTP server.  RELAY also serves as
2511                         an implicit OK for the other checks.
2512         REJECT          Reject the sender or recipient with a general
2513                         purpose message.
2514         DISCARD         Discard the message completely using the
2515                         $#discard mailer.  If it is used in check_compat,
2516                         it affects only the designated recipient, not
2517                         the whole message as it does in all other cases.
2518                         This should only be used if really necessary.
2519         SKIP            This can only be used for host/domain names
2520                         and IP addresses/nets.  It will abort the current
2521                         search for this entry without accepting or rejecting
2522                         it but causing the default action.
2523         ### any text    where ### is an RFC 821 compliant error code and
2524                         "any text" is a message to return for the command.
2525                         The string should be quoted to avoid surprises,
2526                         e.g., sendmail may remove spaces otherwise.
2527                         This type is deprecated, use one of the two
2528                         ERROR:  entries below instead.
2529         ERROR:### any text
2530                         as above, but useful to mark error messages as such.
2531         ERROR:D.S.N:### any text
2532                         where D.S.N is an RFC 1893 compliant error code
2533                         and the rest as above.
2534         QUARANTINE:any text
2535                         Quarantine the message using the given text as the
2536                         quarantining reason.
2537
2538 For example:
2539
2540         From:cyberspammer.com   ERROR:"550 We don't accept mail from spammers"
2541         From:okay.cyberspammer.com      OK
2542         Connect:sendmail.org            RELAY
2543         To:sendmail.org                 RELAY
2544         Connect:128.32                  RELAY
2545         Connect:128.32.2                SKIP
2546         Connect:IPv6:1:2:3:4:5:6:7      RELAY
2547         Connect:suspicious.example.com  QUARANTINE:Mail from suspicious host
2548         Connect:[127.0.0.3]             OK
2549         Connect:[IPv6:1:2:3:4:5:6:7:8]  OK
2550
2551 would accept mail from okay.cyberspammer.com, but would reject mail
2552 from all other hosts at cyberspammer.com with the indicated message.
2553 It would allow relaying mail from and to any hosts in the sendmail.org
2554 domain, and allow relaying from the IPv6 1:2:3:4:5:6:7:* network
2555 and from the 128.32.*.* network except for the 128.32.2.* network,
2556 which shows how SKIP is useful to exempt subnets/subdomains.  The
2557 last two entries are for checks against ${client_name} if the IP
2558 address doesn't resolve to a hostname (or is considered as "may be
2559 forged").  That is, using square brackets means these are host
2560 names, not network numbers.
2561
2562 Warning: if you change the RFC 821 compliant error code from the default
2563 value of 550, then you should probably also change the RFC 1893 compliant
2564 error code to match it.  For example, if you use
2565
2566         To:user@example.com     ERROR:450 mailbox full
2567
2568 the error returned would be "450 5.0.0 mailbox full" which is wrong.
2569 Use "ERROR:4.2.2:450 mailbox full" instead.
2570
2571 Note, UUCP users may need to add hostname.UUCP to the access database
2572 or class {R}.
2573
2574 If you also use:
2575
2576         FEATURE(`relay_hosts_only')
2577
2578 then the above example will allow relaying for sendmail.org, but not
2579 hosts within the sendmail.org domain.  Note that this will also require
2580 hosts listed in class {R} to be fully qualified host names.
2581
2582 You can also use the access database to block sender addresses based on
2583 the username portion of the address.  For example:
2584
2585         From:FREE.STEALTH.MAILER@       ERROR:550 Spam not accepted
2586
2587 Note that you must include the @ after the username to signify that
2588 this database entry is for checking only the username portion of the
2589 sender address.
2590
2591 If you use:
2592
2593         FEATURE(`blacklist_recipients')
2594
2595 then you can add entries to the map for local users, hosts in your
2596 domains, or addresses in your domain which should not receive mail:
2597
2598         To:badlocaluser@        ERROR:550 Mailbox disabled for badlocaluser
2599         To:host.my.TLD          ERROR:550 That host does not accept mail
2600         To:user@other.my.TLD    ERROR:550 Mailbox disabled for this recipient
2601
2602 This would prevent a recipient of badlocaluser in any of the local
2603 domains (class {w}), any user at host.my.TLD, and the single address
2604 user@other.my.TLD from receiving mail.  Please note: a local username
2605 must be now tagged with an @ (this is consistent with the check of
2606 the sender address, and hence it is possible to distinguish between
2607 hostnames and usernames).  Enabling this feature will keep you from
2608 sending mails to all addresses that have an error message or REJECT
2609 as value part in the access map.  Taking the example from above:
2610
2611         spammer@aol.com         REJECT
2612         cyberspammer.com        REJECT
2613
2614 Mail can't be sent to spammer@aol.com or anyone at cyberspammer.com.
2615 That's why tagged entries should be used.
2616
2617 There are several DNS based blacklists, the first of which was
2618 the RBL (``Realtime Blackhole List'') run by the MAPS project,
2619 see http://mail-abuse.org/.  These are databases of spammers
2620 maintained in DNS.  To use such a database, specify
2621
2622         FEATURE(`dnsbl')
2623
2624 This will cause sendmail to reject mail from any site in the original
2625 Realtime Blackhole List database.  This default DNS blacklist,
2626 blackholes.mail-abuse.org, is a service offered by the Mail Abuse
2627 Prevention System (MAPS).  As of July 31, 2001, MAPS is a subscription
2628 service, so using that network address won't work if you haven't
2629 subscribed.  Contact MAPS to subscribe (http://mail-abuse.org/).
2630
2631 You can specify an alternative RBL server to check by specifying an
2632 argument to the FEATURE.  The default error message is
2633
2634         Rejected: IP-ADDRESS listed at SERVER
2635
2636 where IP-ADDRESS and SERVER are replaced by the appropriate
2637 information.  A second argument can be used to specify a different
2638 text.  By default, temporary lookup failures are ignored and hence
2639 cause the connection not to be rejected by the DNS based rejection
2640 list.  This behavior can be changed by specifying a third argument,
2641 which must be either `t' or a full error message.  For example:
2642
2643         FEATURE(`dnsbl', `dnsbl.example.com', `',
2644         `"451 Temporary lookup failure for " $&{client_addr} " in dnsbl.example.com"')
2645
2646 If `t' is used, the error message is:
2647
2648         451 Temporary lookup failure of IP-ADDRESS at SERVER
2649
2650 where IP-ADDRESS and SERVER are replaced by the appropriate
2651 information.
2652
2653 This FEATURE can be included several times to query different
2654 DNS based rejection lists, e.g., the dial-up user list (see
2655 http://mail-abuse.org/dul/).
2656
2657 Notice: to avoid checking your own local domains against those
2658 blacklists, use the access_db feature and add:
2659
2660         Connect:10.1            OK
2661         Connect:127.0.0.1       RELAY
2662
2663 to the access map, where 10.1 is your local network.  You may
2664 want to use "RELAY" instead of "OK" to allow also relaying
2665 instead of just disabling the DNS lookups in the blacklists.
2666
2667
2668 The features described above make use of the check_relay, check_mail,
2669 and check_rcpt rulesets.  Note that check_relay checks the SMTP
2670 client hostname and IP address when the connection is made to your
2671 server.  It does not check if a mail message is being relayed to
2672 another server.  That check is done in check_rcpt.  If you wish to
2673 include your own checks, you can put your checks in the rulesets
2674 Local_check_relay, Local_check_mail, and Local_check_rcpt.  For
2675 example if you wanted to block senders with all numeric usernames
2676 (i.e. 2312343@bigisp.com), you would use Local_check_mail and the
2677 regex map:
2678
2679         LOCAL_CONFIG
2680         Kallnumbers regex -a@MATCH ^[0-9]+$
2681
2682         LOCAL_RULESETS
2683         SLocal_check_mail
2684         # check address against various regex checks
2685         R$*                             $: $>Parse0 $>3 $1
2686         R$+ < @ bigisp.com. > $*        $: $(allnumbers $1 $)
2687         R@MATCH                         $#error $: 553 Header Error
2688
2689 These rules are called with the original arguments of the corresponding
2690 check_* ruleset.  If the local ruleset returns $#OK, no further checking
2691 is done by the features described above and the mail is accepted.  If
2692 the local ruleset resolves to a mailer (such as $#error or $#discard),
2693 the appropriate action is taken.  Other results starting with $# are
2694 interpreted by sendmail and may lead to unspecified behavior.  Note: do
2695 NOT create a mailer with the name OK.  Return values that do not start
2696 with $# are ignored, i.e., normal processing continues.
2697
2698 Delay all checks
2699 ----------------
2700
2701 By using FEATURE(`delay_checks') the rulesets check_mail and check_relay
2702 will not be called when a client connects or issues a MAIL command,
2703 respectively.  Instead, those rulesets will be called by the check_rcpt
2704 ruleset; they will be skipped if a sender has been authenticated using
2705 a "trusted" mechanism, i.e., one that is defined via TRUST_AUTH_MECH().
2706 If check_mail returns an error then the RCPT TO command will be rejected
2707 with that error.  If it returns some other result starting with $# then
2708 check_relay will be skipped.  If the sender address (or a part of it) is
2709 listed in the access map and it has a RHS of OK or RELAY, then check_relay
2710 will be skipped.  This has an interesting side effect: if your domain is
2711 my.domain and you have
2712
2713         my.domain       RELAY
2714
2715 in the access map, then any e-mail with a sender address of
2716 <user@my.domain> will not be rejected by check_relay even though
2717 it would match the hostname or IP address.  This allows spammers
2718 to get around DNS based blacklist by faking the sender address.  To
2719 avoid this problem you have to use tagged entries:
2720
2721         To:my.domain            RELAY
2722         Connect:my.domain       RELAY
2723
2724 if you need those entries at all (class {R} may take care of them).
2725
2726 FEATURE(`delay_checks') can take an optional argument:
2727
2728         FEATURE(`delay_checks', `friend')
2729                  enables spamfriend test
2730         FEATURE(`delay_checks', `hater')
2731                  enables spamhater test
2732
2733 If such an argument is given, the recipient will be looked up in the
2734 access map (using the tag Spam:).  If the argument is `friend', then
2735 the default behavior is to apply the other rulesets and make a SPAM
2736 friend the exception.  The rulesets check_mail and check_relay will be
2737 skipped only if the recipient address is found and has RHS FRIEND.  If
2738 the argument is `hater', then the default behavior is to skip the rulesets
2739 check_mail and check_relay and make a SPAM hater the exception.  The
2740 other two rulesets will be applied only if the recipient address is
2741 found and has RHS HATER.
2742
2743 This allows for simple exceptions from the tests, e.g., by activating
2744 the friend option and having
2745
2746         Spam:abuse@     FRIEND
2747
2748 in the access map, mail to abuse@localdomain will get through (where
2749 "localdomain" is any domain in class {w}).  It is also possible to
2750 specify a full address or an address with +detail:
2751
2752         Spam:abuse@my.domain    FRIEND
2753         Spam:me+abuse@          FRIEND
2754         Spam:spam.domain        FRIEND
2755
2756 Note: The required tag has been changed in 8.12 from To: to Spam:.
2757 This change is incompatible to previous versions.  However, you can
2758 (for now) simply add the new entries to the access map, the old
2759 ones will be ignored.  As soon as you removed the old entries from
2760 the access map, specify a third parameter (`n') to this feature and
2761 the backward compatibility rules will not be in the generated .cf
2762 file.
2763
2764 Header Checks
2765 -------------
2766
2767 You can also reject mail on the basis of the contents of headers.
2768 This is done by adding a ruleset call to the 'H' header definition command
2769 in sendmail.cf.  For example, this can be used to check the validity of
2770 a Message-ID: header:
2771
2772         LOCAL_CONFIG
2773         HMessage-Id: $>CheckMessageId
2774
2775         LOCAL_RULESETS
2776         SCheckMessageId
2777         R< $+ @ $+ >            $@ OK
2778         R$*                     $#error $: 553 Header Error
2779
2780 The alternative format:
2781
2782         HSubject: $>+CheckSubject
2783
2784 that is, $>+ instead of $>, gives the full Subject: header including
2785 comments to the ruleset (comments in parentheses () are stripped
2786 by default).
2787
2788 A default ruleset for headers which don't have a specific ruleset
2789 defined for them can be given by:
2790
2791         H*: $>CheckHdr
2792
2793 Notice:
2794 1. All rules act on tokens as explained in doc/op/op.{me,ps,txt}.
2795 That may cause problems with simple header checks due to the
2796 tokenization.  It might be simpler to use a regex map and apply it
2797 to $&{currHeader}.
2798 2. There are no default rulesets coming with this distribution of
2799 sendmail.  You can either write your own or you can search the
2800 WWW for examples, e.g.,  http://www.digitalanswers.org/check_local/
2801 3. When using a default ruleset for headers, the name of the header 
2802 currently being checked can be found in the $&{hdr_name} macro.
2803
2804 After all of the headers are read, the check_eoh ruleset will be called for
2805 any final header-related checks.  The ruleset is called with the number of
2806 headers and the size of all of the headers in bytes separated by $|.  One
2807 example usage is to reject messages which do not have a Message-Id:
2808 header.  However, the Message-Id: header is *NOT* a required header and is
2809 not a guaranteed spam indicator.  This ruleset is an example and should
2810 probably not be used in production.
2811
2812         LOCAL_CONFIG
2813         Kstorage macro
2814         HMessage-Id: $>CheckMessageId
2815
2816         LOCAL_RULESETS
2817         SCheckMessageId
2818         # Record the presence of the header
2819         R$*                     $: $(storage {MessageIdCheck} $@ OK $) $1
2820         R< $+ @ $+ >            $@ OK
2821         R$*                     $#error $: 553 Header Error
2822
2823         Scheck_eoh
2824         # Check the macro
2825         R$*                     $: < $&{MessageIdCheck} >
2826         # Clear the macro for the next message
2827         R$*                     $: $(storage {MessageIdCheck} $) $1
2828         # Has a Message-Id: header
2829         R< $+ >                 $@ OK
2830         # Allow missing Message-Id: from local mail
2831         R$*                     $: < $&{client_name} >
2832         R< >                    $@ OK
2833         R< $=w >                $@ OK
2834         # Otherwise, reject the mail
2835         R$*                     $#error $: 553 Header Error
2836
2837
2838 +--------------------+
2839 | CONNECTION CONTROL |
2840 +--------------------+
2841
2842 The features ratecontrol and conncontrol allow to establish connection
2843 limits per client IP address or net.  These features can limit the
2844 rate of connections (connections per time unit) or the number of
2845 incoming SMTP connections, respectively.  If enabled, appropriate
2846 rulesets are called at the end of check_relay, i.e., after DNS
2847 blacklists and generic access_db operations.  The features require
2848 FEATURE(`access_db') to be listed earlier in the mc file.
2849
2850 Note: FEATURE(`delay_checks') delays those connection control checks
2851 after a recipient address has been received, hence making these
2852 connection control features less useful.  To run the checks as early
2853 as possible, specify the parameter `nodelay', e.g.,
2854
2855         FEATURE(`ratecontrol', `nodelay')
2856
2857 In that case, FEATURE(`delay_checks') has no effect on connection
2858 control (and it must be specified earlier in the mc file).
2859
2860 An optional second argument `terminate' specifies whether the
2861 rulesets should return the error code 421 which will cause
2862 sendmail to terminate the session with that error if it is
2863 returned from check_relay, i.e., not delayed as explained in
2864 the previous paragraph.  Example:
2865
2866         FEATURE(`ratecontrol', `nodelay', `terminate')
2867
2868
2869 +----------+
2870 | STARTTLS |
2871 +----------+
2872
2873 In this text, cert will be used as an abbreviation for X.509 certificate,
2874 DN (CN) is the distinguished (common) name of a cert, and CA is a
2875 certification authority, which signs (issues) certs.
2876
2877 For STARTTLS to be offered by sendmail you need to set at least
2878 these variables (the file names and paths are just examples):
2879
2880         define(`confCACERT_PATH', `/etc/mail/certs/')
2881         define(`confCACERT', `/etc/mail/certs/CA.cert.pem')
2882         define(`confSERVER_CERT', `/etc/mail/certs/my.cert.pem')
2883         define(`confSERVER_KEY', `/etc/mail/certs/my.key.pem')
2884
2885 On systems which do not have the compile flag HASURANDOM set (see
2886 sendmail/README) you also must set confRAND_FILE.
2887
2888 See doc/op/op.{me,ps,txt} for more information about these options,
2889 especially the sections ``Certificates for STARTTLS'' and ``PRNG for
2890 STARTTLS''.
2891
2892 Macros related to STARTTLS are:
2893
2894 ${cert_issuer} holds the DN of the CA (the cert issuer).
2895 ${cert_subject} holds the DN of the cert (called the cert subject).
2896 ${cn_issuer} holds the CN of the CA (the cert issuer).
2897 ${cn_subject} holds the CN of the cert (called the cert subject).
2898 ${tls_version} the TLS/SSL version used for the connection, e.g., TLSv1,
2899         TLSv1/SSLv3, SSLv3, SSLv2.
2900 ${cipher} the cipher used for the connection, e.g., EDH-DSS-DES-CBC3-SHA,
2901         EDH-RSA-DES-CBC-SHA, DES-CBC-MD5, DES-CBC3-SHA.
2902 ${cipher_bits} the keylength (in bits) of the symmetric encryption algorithm
2903         used for the connection.
2904 ${verify} holds the result of the verification of the presented cert.
2905         Possible values are:
2906         OK       verification succeeded.
2907         NO       no cert presented.
2908         NOT      no cert requested.
2909         FAIL     cert presented but could not be verified,
2910                  e.g., the cert of the signing CA is missing.
2911         NONE     STARTTLS has not been performed.
2912         TEMP     temporary error occurred.
2913         PROTOCOL protocol error occurred (SMTP level).
2914         SOFTWARE STARTTLS handshake failed.
2915 ${server_name} the name of the server of the current outgoing SMTP
2916         connection.
2917 ${server_addr} the address of the server of the current outgoing SMTP
2918         connection.
2919
2920 Relaying
2921 --------
2922
2923 SMTP STARTTLS can allow relaying for remote SMTP clients which have
2924 successfully authenticated themselves.  If the verification of the cert
2925 failed (${verify} != OK), relaying is subject to the usual rules.
2926 Otherwise the DN of the issuer is looked up in the access map using the
2927 tag CERTISSUER.  If the resulting value is RELAY, relaying is allowed.
2928 If it is SUBJECT, the DN of the cert subject is looked up next in the
2929 access map using the tag CERTSUBJECT.  If the value is RELAY, relaying
2930 is allowed.
2931
2932 To make things a bit more flexible (or complicated), the values for
2933 ${cert_issuer} and ${cert_subject} can be optionally modified by regular
2934 expressions defined in the m4 variables _CERT_REGEX_ISSUER_ and
2935 _CERT_REGEX_SUBJECT_, respectively.  To avoid problems with those macros in
2936 rulesets and map lookups, they are modified as follows: each non-printable
2937 character and the characters '<', '>', '(', ')', '"', '+', ' ' are replaced
2938 by their HEX value with a leading '+'.  For example:
2939
2940 /C=US/ST=California/O=endmail.org/OU=private/CN=Darth Mail (Cert)/Email=
2941 darth+cert@endmail.org
2942
2943 is encoded as:
2944
2945 /C=US/ST=California/O=endmail.org/OU=private/CN=
2946 Darth+20Mail+20+28Cert+29/Email=darth+2Bcert@endmail.org
2947
2948 (line breaks have been inserted for readability).
2949
2950 The  macros  which are subject to this encoding are ${cert_subject},
2951 ${cert_issuer},  ${cn_subject},  and ${cn_issuer}.
2952
2953 Examples:
2954
2955 To allow relaying for everyone who can present a cert signed by
2956
2957 /C=US/ST=California/O=endmail.org/OU=private/CN=
2958 Darth+20Mail+20+28Cert+29/Email=darth+2Bcert@endmail.org
2959
2960 simply use:
2961
2962 CertIssuer:/C=US/ST=California/O=endmail.org/OU=private/CN=
2963 Darth+20Mail+20+28Cert+29/Email=darth+2Bcert@endmail.org        RELAY
2964
2965 To allow relaying only for a subset of machines that have a cert signed by
2966
2967 /C=US/ST=California/O=endmail.org/OU=private/CN=
2968 Darth+20Mail+20+28Cert+29/Email=darth+2Bcert@endmail.org
2969
2970 use:
2971
2972 CertIssuer:/C=US/ST=California/O=endmail.org/OU=private/CN=
2973 Darth+20Mail+20+28Cert+29/Email=darth+2Bcert@endmail.org        SUBJECT
2974 CertSubject:/C=US/ST=California/O=endmail.org/OU=private/CN=
2975 DeathStar/Email=deathstar@endmail.org           RELAY
2976
2977 Notes:
2978 - line breaks have been inserted after "CN=" for readability,
2979   each tagged entry must be one (long) line in the access map.
2980 - if OpenSSL 0.9.7 or newer is used then the "Email=" part of a DN
2981   is replaced by "emailAddress=".
2982
2983 Of course it is also possible to write a simple ruleset that allows
2984 relaying for everyone who can present a cert that can be verified, e.g.,
2985
2986 LOCAL_RULESETS
2987 SLocal_check_rcpt
2988 R$*     $: $&{verify}
2989 ROK     $# OK
2990
2991 Allowing Connections
2992 --------------------
2993
2994 The rulesets tls_server, tls_client, and tls_rcpt are used to decide whether
2995 an SMTP connection is accepted (or should continue).
2996
2997 tls_server is called when sendmail acts as client after a STARTTLS command
2998 (should) have been issued.  The parameter is the value of ${verify}.
2999
3000 tls_client is called when sendmail acts as server, after a STARTTLS command
3001 has been issued, and from check_mail.  The parameter is the value of
3002 ${verify} and STARTTLS or MAIL, respectively.
3003
3004 Both rulesets behave the same.  If no access map is in use, the connection
3005 will be accepted unless ${verify} is SOFTWARE, in which case the connection
3006 is always aborted.  For tls_server/tls_client, ${client_name}/${server_name}
3007 is looked up in the access map using the tag TLS_Srv/TLS_Clt, which is done
3008 with the ruleset LookUpDomain.  If no entry is found, ${client_addr}
3009 (${server_addr}) is looked up in the access map (same tag, ruleset
3010 LookUpAddr).  If this doesn't result in an entry either, just the tag is
3011 looked up in the access map (included the trailing colon).  Notice:
3012 requiring that e-mail is sent to a server only encrypted, e.g., via
3013
3014 TLS_Srv:secure.domain   ENCR:112
3015
3016 doesn't necessarily mean that e-mail sent to that domain is encrypted.
3017 If the domain has multiple MX servers, e.g.,
3018
3019 secure.domain.  IN MX 10        mail.secure.domain.
3020 secure.domain.  IN MX 50        mail.other.domain.
3021
3022 then mail to user@secure.domain may go unencrypted to mail.other.domain.
3023 tls_rcpt can be used to address this problem.
3024
3025 tls_rcpt is called before a RCPT TO: command is sent.  The parameter is the
3026 current recipient.  This ruleset is only defined if FEATURE(`access_db')
3027 is selected.  A recipient address user@domain is looked up in the access
3028 map in four formats: TLS_Rcpt:user@domain, TLS_Rcpt:user@, TLS_Rcpt:domain,
3029 and TLS_Rcpt:; the first match is taken.
3030
3031 The result of the lookups is then used to call the ruleset TLS_connection,
3032 which checks the requirement specified by the RHS in the access map against
3033 the actual parameters of the current TLS connection, esp. ${verify} and
3034 ${cipher_bits}.  Legal RHSs in the access map are:
3035
3036 VERIFY          verification must have succeeded
3037 VERIFY:bits     verification must have succeeded and ${cipher_bits} must
3038                 be greater than or equal bits.
3039 ENCR:bits       ${cipher_bits} must be greater than or equal bits.
3040
3041 The RHS can optionally be prefixed by TEMP+ or PERM+ to select a temporary
3042 or permanent error.  The default is a temporary error code (403 4.7.0)
3043 unless the macro TLS_PERM_ERR is set during generation of the .cf file.
3044
3045 If a certain level of encryption is required, then it might also be
3046 possible that this level is provided by the security layer from a SASL
3047 algorithm, e.g., DIGEST-MD5.
3048
3049 Furthermore, there can be a list of extensions added.  Such a list
3050 starts with '+' and the items are separated by '++'.  Allowed
3051 extensions are:
3052
3053 CN:name         name must match ${cn_subject}
3054 CN              ${server_name} must match ${cn_subject}
3055 CS:name         name must match ${cert_subject}
3056 CI:name         name must match ${cert_issuer}
3057
3058 Example: e-mail sent to secure.example.com should only use an encrypted
3059 connection.  E-mail received from hosts within the laptop.example.com domain
3060 should only be accepted if they have been authenticated.  The host which
3061 receives e-mail for darth@endmail.org must present a cert that uses the
3062 CN smtp.endmail.org.
3063
3064 TLS_Srv:secure.example.com      ENCR:112
3065 TLS_Clt:laptop.example.com      PERM+VERIFY:112
3066 TLS_Rcpt:darth@endmail.org      ENCR:112+CN:smtp.endmail.org
3067
3068
3069 Disabling STARTTLS And Setting SMTP Server Features
3070 ---------------------------------------------------
3071
3072 By default STARTTLS is used whenever possible.  However, there are
3073 some broken MTAs that don't properly implement STARTTLS.  To be able
3074 to send to (or receive from) those MTAs, the ruleset try_tls
3075 (srv_features) can be used that work together with the access map.
3076 Entries for the access map must be tagged with Try_TLS (Srv_Features)
3077 and refer to the hostname or IP address of the connecting system.
3078 A default case can be specified by using just the tag.  For example,
3079 the following entries in the access map:
3080
3081         Try_TLS:broken.server   NO
3082         Srv_Features:my.domain  v
3083         Srv_Features:           V
3084
3085 will turn off STARTTLS when sending to broken.server (or any host
3086 in that domain), and request a client certificate during the TLS
3087 handshake only for hosts in my.domain.  The valid entries on the RHS
3088 for Srv_Features are listed in the Sendmail Installation and
3089 Operations Guide.
3090
3091
3092 Received: Header
3093 ----------------
3094
3095 The Received: header reveals whether STARTTLS has been used.  It contains an
3096 extra line:
3097
3098 (version=${tls_version} cipher=${cipher} bits=${cipher_bits} verify=${verify})
3099
3100
3101 +---------------------+
3102 | SMTP AUTHENTICATION |
3103 +---------------------+
3104
3105 The macros ${auth_authen}, ${auth_author}, and ${auth_type} can be
3106 used in anti-relay rulesets to allow relaying for those users that
3107 authenticated themselves.  A very simple example is:
3108
3109 SLocal_check_rcpt
3110 R$*             $: $&{auth_type}
3111 R$+             $# OK
3112
3113 which checks whether a user has successfully authenticated using
3114 any available mechanism.  Depending on the setup of the Cyrus SASL
3115 library, more sophisticated rulesets might be required, e.g.,
3116
3117 SLocal_check_rcpt
3118 R$*             $: $&{auth_type} $| $&{auth_authen}
3119 RDIGEST-MD5 $| $+@$=w   $# OK
3120
3121 to allow relaying for users that authenticated using DIGEST-MD5
3122 and have an identity in the local domains.
3123
3124 The ruleset trust_auth is used to determine whether a given AUTH=
3125 parameter (that is passed to this ruleset) should be trusted.  This
3126 ruleset may make use of the other ${auth_*} macros.  Only if the
3127 ruleset resolves to the error mailer, the AUTH= parameter is not
3128 trusted.  A user supplied ruleset Local_trust_auth can be written
3129 to modify the default behavior, which only trust the AUTH=
3130 parameter if it is identical to the authenticated user.
3131
3132 Per default, relaying is allowed for any user who authenticated
3133 via a "trusted" mechanism, i.e., one that is defined via
3134 TRUST_AUTH_MECH(`list of mechanisms')
3135 For example:
3136 TRUST_AUTH_MECH(`KERBEROS_V4 DIGEST-MD5')
3137
3138 If the selected mechanism provides a security layer the number of
3139 bits used for the key of the symmetric cipher is stored in the
3140 macro ${auth_ssf}.
3141
3142 Providing SMTP AUTH Data when sendmail acts as Client
3143 -----------------------------------------------------
3144
3145 If sendmail acts as client, it needs some information how to
3146 authenticate against another MTA.  This information can be provided
3147 by the ruleset authinfo or by the option DefaultAuthInfo.  The
3148 authinfo ruleset looks up {server_name} using the tag AuthInfo: in
3149 the access map.  If no entry is found, {server_addr} is looked up
3150 in the same way and finally just the tag AuthInfo: to provide
3151 default values.  Note: searches for domain parts or IP nets are
3152 only performed if the access map is used; if the authinfo feature
3153 is used then only up to three lookups are performed (two exact
3154 matches, one default).
3155
3156 Note: If your daemon does client authentication when sending, and
3157 if it uses either PLAIN or LOGIN authentication, then you *must*
3158 prevent ordinary users from seeing verbose output.  Do NOT install
3159 sendmail set-user-ID.  Use PrivacyOptions to turn off verbose output
3160 ("goaway" works for this).
3161
3162 Notice: the default configuration file causes the option DefaultAuthInfo
3163 to fail since the ruleset authinfo is in the .cf file. If you really
3164 want to use DefaultAuthInfo (it is deprecated) then you have to
3165 remove the ruleset.
3166
3167 The RHS for an AuthInfo: entry in the access map should consists of a
3168 list of tokens, each of which has the form: "TDstring" (including
3169 the quotes).  T is a tag which describes the item, D is a delimiter,
3170 either ':' for simple text or '=' for a base64 encoded string.
3171 Valid values for the tag are:
3172
3173         U       user (authorization) id
3174         I       authentication id
3175         P       password
3176         R       realm
3177         M       list of mechanisms delimited by spaces
3178
3179 Example entries are:
3180
3181 AuthInfo:other.dom "U:user" "I:user" "P:secret" "R:other.dom" "M:DIGEST-MD5"
3182 AuthInfo:host.more.dom "U:user" "P=c2VjcmV0"
3183
3184 User id or authentication id must exist as well as the password.  All
3185 other entries have default values.  If one of user or authentication
3186 id is missing, the existing value is used for the missing item.
3187 If "R:" is not specified, realm defaults to $j.  The list of mechanisms
3188 defaults to those specified by AuthMechanisms.
3189
3190 Since this map contains sensitive information, either the access
3191 map must be unreadable by everyone but root (or the trusted user)
3192 or FEATURE(`authinfo') must be used which provides a separate map.
3193 Notice: It is not checked whether the map is actually
3194 group/world-unreadable, this is left to the user.
3195
3196 +--------------------------------+
3197 | ADDING NEW MAILERS OR RULESETS |
3198 +--------------------------------+
3199
3200 Sometimes you may need to add entirely new mailers or rulesets.  They
3201 should be introduced with the constructs MAILER_DEFINITIONS and
3202 LOCAL_RULESETS respectively.  For example:
3203
3204         MAILER_DEFINITIONS
3205         Mmymailer, ...
3206         ...
3207
3208         LOCAL_RULESETS
3209         Smyruleset
3210         ...
3211
3212 Local additions for the rulesets srv_features, try_tls, tls_rcpt,
3213 tls_client, and tls_server can be made using LOCAL_SRV_FEATURES,
3214 LOCAL_TRY_TLS, LOCAL_TLS_RCPT, LOCAL_TLS_CLIENT, and LOCAL_TLS_SERVER,
3215 respectively.  For example, to add a local ruleset that decides
3216 whether to try STARTTLS in a sendmail client, use:
3217
3218         LOCAL_TRY_TLS
3219         R...
3220
3221 Note: you don't need to add a name for the ruleset, it is implicitly
3222 defined by using the appropriate macro.
3223
3224
3225 +-------------------------+
3226 | ADDING NEW MAIL FILTERS |
3227 +-------------------------+
3228
3229 Sendmail supports mail filters to filter incoming SMTP messages according
3230 to the "Sendmail Mail Filter API" documentation.  These filters can be
3231 configured in your mc file using the two commands:
3232
3233         MAIL_FILTER(`name', `equates')
3234         INPUT_MAIL_FILTER(`name', `equates')
3235
3236 The first command, MAIL_FILTER(), simply defines a filter with the given
3237 name and equates.  For example:
3238
3239         MAIL_FILTER(`archive', `S=local:/var/run/archivesock, F=R')
3240
3241 This creates the equivalent sendmail.cf entry:
3242
3243         Xarchive, S=local:/var/run/archivesock, F=R
3244
3245 The INPUT_MAIL_FILTER() command performs the same actions as MAIL_FILTER
3246 but also populates the m4 variable `confINPUT_MAIL_FILTERS' with the name
3247 of the filter such that the filter will actually be called by sendmail.
3248
3249 For example, the two commands:
3250
3251         INPUT_MAIL_FILTER(`archive', `S=local:/var/run/archivesock, F=R')
3252         INPUT_MAIL_FILTER(`spamcheck', `S=inet:2525@localhost, F=T')
3253
3254 are equivalent to the three commands:
3255
3256         MAIL_FILTER(`archive', `S=local:/var/run/archivesock, F=R')
3257         MAIL_FILTER(`spamcheck', `S=inet:2525@localhost, F=T')
3258         define(`confINPUT_MAIL_FILTERS', `archive, spamcheck')
3259
3260 In general, INPUT_MAIL_FILTER() should be used unless you need to define
3261 more filters than you want to use for `confINPUT_MAIL_FILTERS'.
3262
3263 Note that setting `confINPUT_MAIL_FILTERS' after any INPUT_MAIL_FILTER()
3264 commands will clear the list created by the prior INPUT_MAIL_FILTER()
3265 commands.
3266
3267
3268 +-------------------------+
3269 | QUEUE GROUP DEFINITIONS |
3270 +-------------------------+
3271
3272 In addition to the queue directory (which is the default queue group
3273 called "mqueue"), sendmail can deal with multiple queue groups, which
3274 are collections of queue directories with the same behaviour.  Queue
3275 groups can be defined using the command:
3276
3277         QUEUE_GROUP(`name', `equates')
3278
3279 For details about queue groups, please see doc/op/op.{me,ps,txt}.
3280
3281 +-------------------------------+
3282 | NON-SMTP BASED CONFIGURATIONS |
3283 +-------------------------------+
3284
3285 These configuration files are designed primarily for use by
3286 SMTP-based sites.  They may not be well tuned for UUCP-only or
3287 UUCP-primarily nodes (the latter is defined as a small local net
3288 connected to the rest of the world via UUCP).  However, there is
3289 one hook to handle some special cases.
3290
3291 You can define a ``smart host'' that understands a richer address syntax
3292 using:
3293
3294         define(`SMART_HOST', `mailer:hostname')
3295
3296 In this case, the ``mailer:'' defaults to "relay".  Any messages that
3297 can't be handled using the usual UUCP rules are passed to this host.
3298
3299 If you are on a local SMTP-based net that connects to the outside
3300 world via UUCP, you can use LOCAL_NET_CONFIG to add appropriate rules.
3301 For example:
3302
3303         define(`SMART_HOST', `uucp-new:uunet')
3304         LOCAL_NET_CONFIG
3305         R$* < @ $* .$m. > $*    $#smtp $@ $2.$m. $: $1 < @ $2.$m. > $3
3306
3307 This will cause all names that end in your domain name ($m) to be sent
3308 via SMTP; anything else will be sent via uucp-new (smart UUCP) to uunet.
3309 If you have FEATURE(`nocanonify'), you may need to omit the dots after
3310 the $m.  If you are running a local DNS inside your domain which is
3311 not otherwise connected to the outside world, you probably want to
3312 use:
3313
3314         define(`SMART_HOST', `smtp:fire.wall.com')
3315         LOCAL_NET_CONFIG
3316         R$* < @ $* . > $*       $#smtp $@ $2. $: $1 < @ $2. > $3
3317
3318 That is, send directly only to things you found in your DNS lookup;
3319 anything else goes through SMART_HOST.
3320
3321 You may need to turn off the anti-spam rules in order to accept
3322 UUCP mail with FEATURE(`promiscuous_relay') and
3323 FEATURE(`accept_unresolvable_domains').
3324
3325
3326 +-----------+
3327 | WHO AM I? |
3328 +-----------+
3329
3330 Normally, the $j macro is automatically defined to be your fully
3331 qualified domain name (FQDN).  Sendmail does this by getting your
3332 host name using gethostname and then calling gethostbyname on the
3333 result.  For example, in some environments gethostname returns
3334 only the root of the host name (such as "foo"); gethostbyname is
3335 supposed to return the FQDN ("foo.bar.com").  In some (fairly rare)
3336 cases, gethostbyname may fail to return the FQDN.  In this case
3337 you MUST define confDOMAIN_NAME to be your fully qualified domain
3338 name.  This is usually done using:
3339
3340         Dmbar.com
3341         define(`confDOMAIN_NAME', `$w.$m')dnl
3342
3343
3344 +-----------------------------------+
3345 | ACCEPTING MAIL FOR MULTIPLE NAMES |
3346 +-----------------------------------+
3347
3348 If your host is known by several different names, you need to augment
3349 class {w}.  This is a list of names by which your host is known, and
3350 anything sent to an address using a host name in this list will be
3351 treated as local mail.  You can do this in two ways:  either create the
3352 file /etc/mail/local-host-names containing a list of your aliases (one per
3353 line), and use ``FEATURE(`use_cw_file')'' in the .mc file, or add
3354 ``LOCAL_DOMAIN(`alias.host.name')''.  Be sure you use the fully-qualified
3355 name of the host, rather than a short name.
3356
3357 If you want to have different address in different domains, take
3358 a look at the virtusertable feature, which is also explained at
3359 http://www.sendmail.org/virtual-hosting.html
3360
3361
3362 +--------------------+
3363 | USING MAILERTABLES |
3364 +--------------------+
3365
3366 To use FEATURE(`mailertable'), you will have to create an external
3367 database containing the routing information for various domains.
3368 For example, a mailertable file in text format might be:
3369
3370         .my.domain              xnet:%1.my.domain
3371         uuhost1.my.domain       uucp-new:uuhost1
3372         .bitnet                 smtp:relay.bit.net
3373
3374 This should normally be stored in /etc/mail/mailertable.  The actual
3375 database version of the mailertable is built using:
3376
3377         makemap hash /etc/mail/mailertable < /etc/mail/mailertable
3378
3379 The semantics are simple.  Any LHS entry that does not begin with
3380 a dot matches the full host name indicated.  LHS entries beginning
3381 with a dot match anything ending with that domain name (including
3382 the leading dot) -- that is, they can be thought of as having a
3383 leading ".+" regular expression pattern for a non-empty sequence of
3384 characters.  Matching is done in order of most-to-least qualified
3385 -- for example, even though ".my.domain" is listed first in the
3386 above example, an entry of "uuhost1.my.domain" will match the second
3387 entry since it is more explicit.  Note: e-mail to "user@my.domain"
3388 does not match any entry in the above table.  You need to have
3389 something like:
3390
3391         my.domain               esmtp:host.my.domain
3392
3393 The RHS should always be a "mailer:host" pair.  The mailer is the
3394 configuration name of a mailer (that is, an M line in the
3395 sendmail.cf file).  The "host" will be the hostname passed to
3396 that mailer.  In domain-based matches (that is, those with leading
3397 dots) the "%1" may be used to interpolate the wildcarded part of
3398 the host name.  For example, the first line above sends everything
3399 addressed to "anything.my.domain" to that same host name, but using
3400 the (presumably experimental) xnet mailer.
3401
3402 In some cases you may want to temporarily turn off MX records,
3403 particularly on gateways.  For example, you may want to MX
3404 everything in a domain to one machine that then forwards it
3405 directly.  To do this, you might use the DNS configuration:
3406
3407         *.domain.       IN      MX      0       relay.machine
3408
3409 and on relay.machine use the mailertable:
3410
3411         .domain         smtp:[gateway.domain]
3412
3413 The [square brackets] turn off MX records for this host only.
3414 If you didn't do this, the mailertable would use the MX record
3415 again, which would give you an MX loop.  Note that the use of
3416 wildcard MX records is almost always a bad idea.  Please avoid
3417 using them if possible.
3418
3419
3420 +--------------------------------+
3421 | USING USERDB TO MAP FULL NAMES |
3422 +--------------------------------+
3423
3424 The user database was not originally intended for mapping full names
3425 to login names (e.g., Eric.Allman => eric), but some people are using
3426 it that way.  (it is recommended that you set up aliases for this
3427 purpose instead -- since you can specify multiple alias files, this
3428 is fairly easy.)  The intent was to locate the default maildrop at
3429 a site, but allow you to override this by sending to a specific host.
3430
3431 If you decide to set up the user database in this fashion, it is
3432 imperative that you not use FEATURE(`stickyhost') -- otherwise,
3433 e-mail sent to Full.Name@local.host.name will be rejected.
3434
3435 To build the internal form of the user database, use:
3436
3437         makemap btree /etc/mail/userdb < /etc/mail/userdb.txt
3438
3439 As a general rule, it is an extremely bad idea to using full names
3440 as e-mail addresses, since they are not in any sense unique.  For
3441 example, the UNIX software-development community has at least two
3442 well-known Peter Deutsches, and at one time Bell Labs had two
3443 Stephen R. Bournes with offices along the same hallway.  Which one
3444 will be forced to suffer the indignity of being Stephen_R_Bourne_2?
3445 The less famous of the two, or the one that was hired later?
3446
3447 Finger should handle full names (and be fuzzy).  Mail should use
3448 handles, and not be fuzzy.
3449
3450
3451 +--------------------------------+
3452 | MISCELLANEOUS SPECIAL FEATURES |
3453 +--------------------------------+
3454
3455 Plussed users
3456         Sometimes it is convenient to merge configuration on a
3457         centralized mail machine, for example, to forward all
3458         root mail to a mail server.  In this case it might be
3459         useful to be able to treat the root addresses as a class
3460         of addresses with subtle differences.  You can do this
3461         using plussed users.  For example, a client might include
3462         the alias:
3463
3464                 root:  root+client1@server
3465
3466         On the server, this will match an alias for "root+client1".
3467         If that is not found, the alias "root+*" will be tried,
3468         then "root".
3469
3470
3471 +----------------+
3472 | SECURITY NOTES |
3473 +----------------+
3474
3475 A lot of sendmail security comes down to you.  Sendmail 8 is much
3476 more careful about checking for security problems than previous
3477 versions, but there are some things that you still need to watch
3478 for.  In particular:
3479
3480 * Make sure the aliases file is not writable except by trusted
3481   system personnel.  This includes both the text and database
3482   version.
3483
3484 * Make sure that other files that sendmail reads, such as the
3485   mailertable, are only writable by trusted system personnel.
3486
3487 * The queue directory should not be world writable PARTICULARLY
3488   if your system allows "file giveaways" (that is, if a non-root
3489   user can chown any file they own to any other user).
3490
3491 * If your system allows file giveaways, DO NOT create a publically
3492   writable directory for forward files.  This will allow anyone
3493   to steal anyone else's e-mail.  Instead, create a script that
3494   copies the .forward file from users' home directories once a
3495   night (if you want the non-NFS-mounted forward directory).
3496
3497 * If your system allows file giveaways, you'll find that
3498   sendmail is much less trusting of :include: files -- in
3499   particular, you'll have to have /SENDMAIL/ANY/SHELL/ in
3500   /etc/shells before they will be trusted (that is, before
3501   files and programs listed in them will be honored).
3502
3503 In general, file giveaways are a mistake -- if you can turn them
3504 off, do so.
3505
3506
3507 +--------------------------------+
3508 | TWEAKING CONFIGURATION OPTIONS |
3509 +--------------------------------+
3510
3511 There are a large number of configuration options that don't normally
3512 need to be changed.  However, if you feel you need to tweak them,
3513 you can define the following M4 variables. Note that some of these
3514 variables require formats that are defined in RFC 2821 or RFC 2822.
3515 Before changing them you need to make sure you do not violate those
3516 (and other relevant) RFCs.
3517
3518 This list is shown in four columns:  the name you define, the default
3519 value for that definition, the option or macro that is affected
3520 (either Ox for an option or Dx for a macro), and a brief description.
3521 Greater detail of the semantics can be found in the Installation
3522 and Operations Guide.
3523
3524 Some options are likely to be deprecated in future versions -- that is,
3525 the option is only included to provide back-compatibility.  These are
3526 marked with "*".
3527
3528 Remember that these options are M4 variables, and hence may need to
3529 be quoted.  In particular, arguments with commas will usually have to
3530 be ``double quoted, like this phrase'' to avoid having the comma
3531 confuse things.  This is common for alias file definitions and for
3532 the read timeout.
3533
3534 M4 Variable Name        Configuration   [Default] & Description
3535 ================        =============   =======================
3536 confMAILER_NAME         $n macro        [MAILER-DAEMON] The sender name used
3537                                         for internally generated outgoing
3538                                         messages.
3539 confDOMAIN_NAME         $j macro        If defined, sets $j.  This should
3540                                         only be done if your system cannot
3541                                         determine your local domain name,
3542                                         and then it should be set to
3543                                         $w.Foo.COM, where Foo.COM is your
3544                                         domain name.
3545 confCF_VERSION          $Z macro        If defined, this is appended to the
3546                                         configuration version name.
3547 confLDAP_CLUSTER        ${sendmailMTACluster} macro
3548                                         If defined, this is the LDAP
3549                                         cluster to use for LDAP searches
3550                                         as described above in ``USING LDAP
3551                                         FOR ALIASES, MAPS, AND CLASSES''.
3552 confFROM_HEADER         From:           [$?x$x <$g>$|$g$.] The format of an
3553                                         internally generated From: address.
3554 confRECEIVED_HEADER     Received:
3555                 [$?sfrom $s $.$?_($?s$|from $.$_)
3556                         $.$?{auth_type}(authenticated)
3557                         $.by $j ($v/$Z)$?r with $r$. id $i$?u
3558                         for $u; $|;
3559                         $.$b]
3560                                         The format of the Received: header
3561                                         in messages passed through this host.
3562                                         It is unwise to try to change this.
3563 confMESSAGEID_HEADER    Message-Id:     [<$t.$i@$j>] The format of an
3564                                         internally generated Message-Id:
3565                                         header.
3566 confCW_FILE             Fw class        [/etc/mail/local-host-names] Name
3567                                         of file used to get the local
3568                                         additions to class {w} (local host
3569                                         names).
3570 confCT_FILE             Ft class        [/etc/mail/trusted-users] Name of
3571                                         file used to get the local additions
3572                                         to class {t} (trusted users).
3573 confCR_FILE             FR class        [/etc/mail/relay-domains] Name of
3574                                         file used to get the local additions
3575                                         to class {R} (hosts allowed to relay).
3576 confTRUSTED_USERS       Ct class        [no default] Names of users to add to
3577                                         the list of trusted users.  This list
3578                                         always includes root, uucp, and daemon.
3579                                         See also FEATURE(`use_ct_file').
3580 confTRUSTED_USER        TrustedUser     [no default] Trusted user for file
3581                                         ownership and starting the daemon.
3582                                         Not to be confused with
3583                                         confTRUSTED_USERS (see above).
3584 confSMTP_MAILER         -               [esmtp] The mailer name used when
3585                                         SMTP connectivity is required.
3586                                         One of "smtp", "smtp8",
3587                                         "esmtp", or "dsmtp".
3588 confUUCP_MAILER         -               [uucp-old] The mailer to be used by
3589                                         default for bang-format recipient
3590                                         addresses.  See also discussion of
3591                                         class {U}, class {Y}, and class {Z}
3592                                         in the MAILER(`uucp') section.
3593 confLOCAL_MAILER        -               [local] The mailer name used when
3594                                         local connectivity is required.
3595                                         Almost always "local".
3596 confRELAY_MAILER        -               [relay] The default mailer name used
3597                                         for relaying any mail (e.g., to a
3598                                         BITNET_RELAY, a SMART_HOST, or
3599                                         whatever).  This can reasonably be
3600                                         "uucp-new" if you are on a
3601                                         UUCP-connected site.
3602 confSEVEN_BIT_INPUT     SevenBitInput   [False] Force input to seven bits?
3603 confEIGHT_BIT_HANDLING  EightBitMode    [pass8] 8-bit data handling
3604 confALIAS_WAIT          AliasWait       [10m] Time to wait for alias file
3605                                         rebuild until you get bored and
3606                                         decide that the apparently pending
3607                                         rebuild failed.
3608 confMIN_FREE_BLOCKS     MinFreeBlocks   [100] Minimum number of free blocks on
3609                                         queue filesystem to accept SMTP mail.
3610                                         (Prior to 8.7 this was minfree/maxsize,
3611                                         where minfree was the number of free
3612                                         blocks and maxsize was the maximum
3613                                         message size.  Use confMAX_MESSAGE_SIZE
3614                                         for the second value now.)
3615 confMAX_MESSAGE_SIZE    MaxMessageSize  [infinite] The maximum size of messages
3616                                         that will be accepted (in bytes).
3617 confBLANK_SUB           BlankSub        [.] Blank (space) substitution
3618                                         character.
3619 confCON_EXPENSIVE       HoldExpensive   [False] Avoid connecting immediately
3620                                         to mailers marked expensive.
3621 confCHECKPOINT_INTERVAL CheckpointInterval
3622                                         [10] Checkpoint queue files every N
3623                                         recipients.
3624 confDELIVERY_MODE       DeliveryMode    [background] Default delivery mode.
3625 confERROR_MODE          ErrorMode       [print] Error message mode.
3626 confERROR_MESSAGE       ErrorHeader     [undefined] Error message header/file.
3627 confSAVE_FROM_LINES     SaveFromLine    Save extra leading From_ lines.
3628 confTEMP_FILE_MODE      TempFileMode    [0600] Temporary file mode.
3629 confMATCH_GECOS         MatchGECOS      [False] Match GECOS field.
3630 confMAX_HOP             MaxHopCount     [25] Maximum hop count.
3631 confIGNORE_DOTS*        IgnoreDots      [False; always False in -bs or -bd
3632                                         mode] Ignore dot as terminator for
3633                                         incoming messages?
3634 confBIND_OPTS           ResolverOptions [undefined] Default options for DNS
3635                                         resolver.
3636 confMIME_FORMAT_ERRORS* SendMimeErrors  [True] Send error messages as MIME-
3637                                         encapsulated messages per RFC 1344.
3638 confFORWARD_PATH        ForwardPath     [$z/.forward.$w:$z/.forward]
3639                                         The colon-separated list of places to
3640                                         search for .forward files.  N.B.: see
3641                                         the Security Notes section.
3642 confMCI_CACHE_SIZE      ConnectionCacheSize
3643                                         [2] Size of open connection cache.
3644 confMCI_CACHE_TIMEOUT   ConnectionCacheTimeout
3645                                         [5m] Open connection cache timeout.
3646 confHOST_STATUS_DIRECTORY HostStatusDirectory
3647                                         [undefined] If set, host status is kept
3648                                         on disk between sendmail runs in the
3649                                         named directory tree.  This need not be
3650                                         a full pathname, in which case it is
3651                                         interpreted relative to the queue
3652                                         directory.
3653 confSINGLE_THREAD_DELIVERY  SingleThreadDelivery
3654                                         [False] If this option and the
3655                                         HostStatusDirectory option are both
3656                                         set, single thread deliveries to other
3657                                         hosts.  That is, don't allow any two
3658                                         sendmails on this host to connect
3659                                         simultaneously to any other single
3660                                         host.  This can slow down delivery in
3661                                         some cases, in particular since a
3662                                         cached but otherwise idle connection
3663                                         to a host will prevent other sendmails
3664                                         from connecting to the other host.
3665 confUSE_ERRORS_TO*      UseErrorsTo     [False] Use the Errors-To: header to
3666                                         deliver error messages.  This should
3667                                         not be necessary because of general
3668                                         acceptance of the envelope/header
3669                                         distinction.
3670 confLOG_LEVEL           LogLevel        [9] Log level.
3671 confME_TOO              MeToo           [True] Include sender in group
3672                                         expansions.  This option is
3673                                         deprecated and will be removed from
3674                                         a future version.
3675 confCHECK_ALIASES       CheckAliases    [False] Check RHS of aliases when
3676                                         running newaliases.  Since this does
3677                                         DNS lookups on every address, it can
3678                                         slow down the alias rebuild process
3679                                         considerably on large alias files.
3680 confOLD_STYLE_HEADERS*  OldStyleHeaders [True] Assume that headers without
3681                                         special chars are old style.
3682 confPRIVACY_FLAGS       PrivacyOptions  [authwarnings] Privacy flags.
3683 confCOPY_ERRORS_TO      PostmasterCopy  [undefined] Address for additional
3684                                         copies of all error messages.
3685 confQUEUE_FACTOR        QueueFactor     [600000] Slope of queue-only function.
3686 confQUEUE_FILE_MODE     QueueFileMode   [undefined] Default permissions for
3687                                         queue files (octal).  If not set,
3688                                         sendmail uses 0600 unless its real
3689                                         and effective uid are different in
3690                                         which case it uses 0644.
3691 confDONT_PRUNE_ROUTES   DontPruneRoutes [False] Don't prune down route-addr
3692                                         syntax addresses to the minimum
3693                                         possible.
3694 confSAFE_QUEUE*         SuperSafe       [True] Commit all messages to disk
3695                                         before forking.
3696 confTO_INITIAL          Timeout.initial [5m] The timeout waiting for a response
3697                                         on the initial connect.
3698 confTO_CONNECT          Timeout.connect [0] The timeout waiting for an initial
3699                                         connect() to complete.  This can only
3700                                         shorten connection timeouts; the kernel
3701                                         silently enforces an absolute maximum
3702                                         (which varies depending on the system).
3703 confTO_ICONNECT         Timeout.iconnect
3704                                         [undefined] Like Timeout.connect, but
3705                                         applies only to the very first attempt
3706                                         to connect to a host in a message.
3707                                         This allows a single very fast pass
3708                                         followed by more careful delivery
3709                                         attempts in the future.
3710 confTO_ACONNECT         Timeout.aconnect
3711                                         [0] The overall timeout waiting for
3712                                         all connection for a single delivery
3713                                         attempt to succeed.  If 0, no overall
3714                                         limit is applied.
3715 confTO_HELO             Timeout.helo    [5m] The timeout waiting for a response
3716                                         to a HELO or EHLO command.
3717 confTO_MAIL             Timeout.mail    [10m] The timeout waiting for a
3718                                         response to the MAIL command.
3719 confTO_RCPT             Timeout.rcpt    [1h] The timeout waiting for a response
3720                                         to the RCPT command.
3721 confTO_DATAINIT         Timeout.datainit
3722                                         [5m] The timeout waiting for a 354
3723                                         response from the DATA command.
3724 confTO_DATABLOCK &nb