op.me
上传用户:xu_441
上传日期:2007-01-04
资源大小:1640k
文件大小:225k
源码类别:

Email客户端

开发平台:

Unix_Linux

  1. ." Copyright (c) 1998, 1999 Sendmail, Inc. and its suppliers.
  2. ." All rights reserved.
  3. ." Copyright (c) 1983, 1995 Eric P. Allman.  All rights reserved.
  4. ." Copyright (c) 1983, 1993
  5. ." The Regents of the University of California.  All rights reserved.
  6. ."
  7. ." By using this file, you agree to the terms and conditions set
  8. ." forth in the LICENSE file which can be found at the top level of
  9. ." the sendmail distribution.
  10. ."
  11. ."
  12. ." $Id: op.me,v 8.293 1999/12/09 21:48:40 gshapiro Exp $
  13. ."
  14. ." eqn op.me | pic | troff -me
  15. .eh 'SMM:08-%''Sendmail Installation and Operation Guide'
  16. .oh 'Sendmail Installation and Operation Guide''SMM:08-%'
  17. ." SD is lib if sendmail is installed in /usr/lib, sbin if in /usr/sbin
  18. .ds SD sbin
  19. ." SB is bin if newaliases/mailq are installed in /usr/bin, ucb if in /usr/ucb
  20. .ds SB bin
  21. .nr si 3n
  22. .de $0
  23. .(x
  24. .in \$3u*3n
  25. .ti -3n
  26. \$2.  \$1
  27. .)x
  28. ..
  29. .de $C
  30. .(x
  31. .in 0
  32. \$1 \$2.  \$3
  33. .)x
  34. ..
  35. .sc
  36. .+c
  37. .(l C
  38. .sz 16
  39. .b SENDMAILus-6TMs0d
  40. .sz 12
  41. .sp
  42. .b "INSTALLATION AND OPERATION GUIDE"
  43. .sz 10
  44. .sp
  45. .r
  46. Eric Allman
  47. Sendmail, Inc.
  48. eric@Sendmail.COM
  49. .sp
  50. .de Ve
  51. Version \$2
  52. ..
  53. .Ve $Revision: 8.293 $
  54. .rm Ve
  55. .sp
  56. For Sendmail Version 8.10
  57. .)l
  58. .(f
  59. Sendmail is a trademark of Sendmail, Inc.
  60. .)f
  61. .sp 2
  62. .pp
  63. .i Sendmail us-2TMs0d
  64. implements a general purpose internetwork mail routing facility
  65. under the UNIX(rg
  66. operating system.
  67. It is not tied to any one transport protocol *-
  68. its function may be likened to a crossbar switch,
  69. relaying messages from one domain into another.
  70. In the process,
  71. it can do a limited amount of message header editing
  72. to put the message into a format that is appropriate
  73. for the receiving domain.
  74. All of this is done under the control of a configuration file.
  75. .pp
  76. Due to the requirements of flexibility
  77. for
  78. .i sendmail ,
  79. the configuration file can seem somewhat unapproachable.
  80. However, there are only a few basic configurations
  81. for most sites,
  82. for which standard configuration files have been supplied.
  83. Most other configurations
  84. can be built by adjusting an existing configuration file
  85. incrementally.
  86. .pp
  87. .i Sendmail
  88. is based on
  89. RFC821 (Simple Mail Transport Protocol),
  90. RFC822 (Internet Mail Headers Format),
  91. RFC1123 (Internet Host Requirements),
  92. RFC2045 (MIME),
  93. RFC1869 (SMTP Service Extensions),
  94. RFC1652 (SMTP 8BITMIME Extension),
  95. RFC1870 (SMTP SIZE Extension),
  96. RFC1891 (SMTP Delivery Status Notifications),
  97. RFC1892 (Multipart/Report),
  98. RFC1893 (Mail System Status Codes),
  99. RFC1894 (Delivery Status Notifications),
  100. RFC1985 (SMTP Service Extension for Remote Message Queue Starting),
  101. RFC2033 (Local Message Transmission Protocol),
  102. RFC2476 (Message Submission),
  103. and
  104. RFC2554 (SMTP Service Extension for Authentication).
  105. However, since
  106. .i sendmail
  107. is designed to work in a wider world,
  108. in many cases it can be configured to exceed these protocols.
  109. These cases are described herein.
  110. .pp
  111. Although
  112. .i sendmail
  113. is intended to run
  114. without the need for monitoring,
  115. it has a number of features
  116. that may be used to monitor or adjust the operation
  117. under unusual circumstances.
  118. These features are described.
  119. .pp
  120. Section one describes how to do a basic
  121. .i sendmail
  122. installation.
  123. Section two
  124. explains the day-to-day information you should know
  125. to maintain your mail system.
  126. If you have a relatively normal site,
  127. these two sections should contain sufficient information
  128. for you to install
  129. .i sendmail
  130. and keep it happy.
  131. Section three
  132. describes some parameters that may be safely tweaked.
  133. Section four
  134. has information regarding the command line arguments.
  135. Section five
  136. contains the nitty-gritty information about the configuration
  137. file.
  138. This section is for masochists
  139. and people who must write their own configuration file.
  140. Section six
  141. describes configuration that can be done at compile time.
  142. The appendixes give a brief
  143. but detailed explanation of a number of features
  144. not described in the rest of the paper.
  145. .pp
  146. ."XXX
  147. .b DISCLAIMER:
  148. This documentation is under modification.
  149. .bp
  150. .rs
  151. .sp |4i
  152. .ce 2
  153. This page intentionally left blank;
  154. replace it with a blank sheet for double-sided output.
  155. .bp 7
  156. .sh 1 "BASIC INSTALLATION"
  157. .pp
  158. There are two basic steps to installing
  159. .i sendmail .
  160. First, you have to compile and install the binary.
  161. If
  162. .i sendmail
  163. has already been ported to your operating system
  164. that should be simple.
  165. Second, you must build a run-time configuration file.
  166. This is a file that
  167. .i sendmail
  168. reads when it starts up
  169. that describes the mailers it knows about,
  170. how to parse addresses,
  171. how to rewrite the message header,
  172. and the settings of various options.
  173. Although the configuration file can be quite complex,
  174. a configuration can usually be built
  175. using an M4-based configuration language.
  176. .pp
  177. The remainder of this section will describe the installation of
  178. .i sendmail
  179. assuming you can use one of the existing configurations
  180. and that the standard installation parameters are acceptable.
  181. All pathnames and examples
  182. are given from the root of the
  183. .i sendmail
  184. subtree,
  185. normally
  186. .i /usr/src/usr.*(SD/sendmail
  187. on 4.4BSD.
  188. .pp
  189. If you are loading this off the tape,
  190. continue with the next section.
  191. If you have a running binary already on your system,
  192. you should probably skip to section 1.2.
  193. .sh 2 "Compiling Sendmail"
  194. .pp
  195. All
  196. .i sendmail
  197. source is in the
  198. .i sendmail
  199. subdirectory.
  200. To compile sendmail,
  201. .q cd
  202. into the
  203. .i sendmail
  204. directory and type
  205. .(b
  206. &./Build
  207. .)b
  208. This will leave the binary in an appropriately named subdirectory,
  209. e.g.,
  210. obj.BSD-OS.2.1.i386.
  211. It works for multiple object versions
  212. compiled out of the same directory.
  213. .sh 3 "Tweaking the Build Invocation"
  214. .pp
  215. You can give parameters on the
  216. .i Build
  217. command.
  218. In most cases these are only used when the
  219. .i obj.*
  220. directory is first created.
  221. These commands include:
  222. .nr ii 0.5i
  223. .ip "-L fIlibdirsfP"
  224. A list of directories to search for libraries.
  225. .ip "-I fIincdirsfP"
  226. A list of directories to search for include files.
  227. .ip "-E fIenvarfP=fIvaluefP"
  228. Set an environment variable to an indicated
  229. .i value
  230. before compiling.
  231. .ip "-c"
  232. Create a new
  233. .i obj.*
  234. tree before running.
  235. .ip "-f fIsiteconfigfP"
  236. Read the indicated site configuration file.
  237. If this parameter is not specified,
  238. .i Build
  239. includes
  240. .i all
  241. of the files
  242. .i $BUILDTOOLS/Site/site.$oscf.m4
  243. and
  244. .i $BUILDTOOLS/Site/site.config.m4 ,
  245. where $BUILDTOOLS is normally
  246. .i &../devtools
  247. and $oscf is the same name as used on the
  248. .i obj.*
  249. directory.
  250. See below for a description of the site configuration file.
  251. .ip "-S"
  252. Skip auto-configuration.
  253. .i Build
  254. will avoid auto-detecting libraries if this is set.
  255. All libraries and map definitions must be specified
  256. in the site configuration file.
  257. .lp
  258. Any other parameters are passed to the
  259. .i make
  260. program.
  261. .sh 3 "Creating a Site Configuration File"
  262. ."XXX
  263. .pp
  264. (This section is not yet complete.
  265. For now, see the file devtools/README for details.)
  266. .sh 3 "Tweaking the Makefile"
  267. .pp
  268. ." .b "XXX This should all be in the Site Configuration File section."
  269. .i Sendmail
  270. supports two different formats
  271. for the local (on disk) version of databases,
  272. notably the
  273. .i aliases
  274. database.
  275. At least one of these should be defined if at all possible.
  276. .nr ii 1i
  277. .ip NDBM
  278. The ``new DBM'' format,
  279. available on nearly all systems around today.
  280. This was the preferred format prior to 4.4BSD.
  281. It allows such complex things as multiple databases
  282. and closing a currently open database.
  283. .ip NEWDB
  284. The Berkeley DB package.
  285. If you have this, use it.
  286. It allows
  287. long records,
  288. multiple open databases,
  289. real in-memory caching,
  290. and so forth.
  291. You can define this in conjunction with
  292. .sm NDBM ;
  293. if you do,
  294. old alias databases are read,
  295. but when a new database is created it will be in NEWDB format.
  296. As a nasty hack,
  297. if you have NEWDB, NDBM, and NIS defined,
  298. and if the alias file name includes the substring
  299. .q /yp/ ,
  300. .i sendmail
  301. will create both new and old versions of the alias file
  302. during a
  303. .i newalias
  304. command.
  305. This is required because the Sun NIS/YP system
  306. reads the DBM version of the alias file.
  307. It's ugly as sin,
  308. but it works.
  309. .lp
  310. If neither of these are defined,
  311. .i sendmail
  312. reads the alias file into memory on every invocation.
  313. This can be slow and should be avoided.
  314. There are also several methods for remote database access:
  315. .ip NIS
  316. Sun's Network Information Services (formerly YP).
  317. .ip NISPLUS
  318. Sun's NIS+ services.
  319. .ip NETINFO
  320. NeXT's NetInfo service.
  321. .ip HESIOD
  322. Hesiod service (from Athena).
  323. .lp
  324. Other compilation flags are set in conf.h
  325. and should be predefined for you
  326. unless you are porting to a new environment.
  327. .sh 3 "Compilation and installation"
  328. .pp
  329. After making the local system configuration described above,
  330. You should be able to compile and install the system.
  331. The script
  332. .q Build
  333. is the best approach on most systems:
  334. .(b
  335. &./Build
  336. .)b
  337. This will use
  338. .i uname (1)
  339. to create a custom Makefile for your environment.
  340. .pp
  341. If you are installing in the standard places,
  342. you should be able to install using
  343. .(b
  344. &./Build install
  345. .)b
  346. This should install the binary in
  347. /usr/*(SD
  348. and create links from
  349. /usr/*(SB/newaliases
  350. and
  351. /usr/*(SB/mailq
  352. to
  353. /usr/*(SD/sendmail.
  354. On 4.4BSD systems it will also format and install man pages.
  355. .sh 2 "Configuration Files"
  356. .pp
  357. .i Sendmail
  358. cannot operate without a configuration file.
  359. The configuration defines the mail delivery mechanisms understood at this site,
  360. how to access them,
  361. how to forward email to remote mail systems,
  362. and a number of tuning parameters.
  363. This configuration file is detailed
  364. in the later portion of this document.
  365. .pp
  366. The
  367. .i sendmail
  368. configuration can be daunting at first.
  369. The world is complex,
  370. and the mail configuration reflects that.
  371. The distribution includes an m4-based configuration package
  372. that hides a lot of the complexity.
  373. .pp
  374. These configuration files are simpler than old versions
  375. largely because the world has become simpler;
  376. in particular,
  377. text-based host files are officially eliminated,
  378. obviating the need to
  379. .q hide
  380. hosts behind a registered internet gateway.
  381. .pp
  382. These files also assume that most of your neighbors
  383. use domain-based UUCP addressing;
  384. that is,
  385. instead of naming hosts as
  386. .q host!user
  387. they will use
  388. .q host.domain!user .
  389. The configuration files can be customized to work around this,
  390. but it is more complex.
  391. .pp
  392. Our configuration files are processed by
  393. .i m4
  394. to facilitate local customization;
  395. the directory
  396. .i cf
  397. of the
  398. .i sendmail
  399. distribution directory
  400. contains the source files.
  401. This directory contains several subdirectories:
  402. .nr ii 1i
  403. .ip cf
  404. Both site-dependent and site-independent descriptions of hosts.
  405. These can be literal host names
  406. (e.g.,
  407. .q ucbvax.mc )
  408. when the hosts are gateways
  409. or more general descriptions
  410. (such as
  411. .q "generic-solaris2.mc"
  412. as a general description of an SMTP-connected host
  413. running Solaris 2.x.
  414. Files ending
  415. .b &.mc
  416. (``Master Configuration'')
  417. are the input descriptions;
  418. the output is in the corresponding
  419. .b &.cf
  420. file.
  421. The general structure of these files is described below.
  422. .ip domain
  423. Site-dependent subdomain descriptions.
  424. These are tied to the way your organization wants to do addressing.
  425. For example,
  426. .b domain/CS.Berkeley.EDU.m4
  427. is our description for hosts in the CS.Berkeley.EDU subdomain.
  428. These are referenced using the
  429. .sm DOMAIN
  430. .b m4
  431. macro in the
  432. .b &.mc
  433. file.
  434. .ip feature
  435. Definitions of specific features that some particular host in your site
  436. might want.
  437. These are referenced using the
  438. .sm FEATURE
  439. .b m4
  440. macro.
  441. An example feature is
  442. use_cw_file
  443. (which tells
  444. .i sendmail
  445. to read an /etc/mail/local-host-names file on startup
  446. to find the set of local names).
  447. .ip hack
  448. Local hacks, referenced using the
  449. .sm HACK
  450. .b m4
  451. macro.
  452. Try to avoid these.
  453. The point of having them here is to make it clear that they smell.
  454. .ip m4
  455. Site-independent
  456. .i m4 (1)
  457. include files that have information common to all configuration files.
  458. This can be thought of as a
  459. .q #include
  460. directory.
  461. .ip mailer
  462. Definitions of mailers,
  463. referenced using the
  464. .sm MAILER
  465. .b m4
  466. macro.
  467. The mailer types that are known in this distribution are
  468. fax,
  469. local,
  470. smtp,
  471. uucp,
  472. and usenet.
  473. For example, to include support for the UUCP-based mailers,
  474. use
  475. .q MAILER(uucp) .
  476. .ip ostype
  477. Definitions describing various operating system environments
  478. (such as the location of support files).
  479. These are referenced using the
  480. .sm OSTYPE
  481. .b m4
  482. macro.
  483. .ip sh
  484. Shell files used by the
  485. .b m4
  486. build process.
  487. You shouldn't have to mess with these.
  488. .ip siteconfig
  489. Local UUCP connectivity information.
  490. This directory has been supplanted by the mailertable feature;
  491. any new configurations should use that feature to do UUCP
  492. (and other) routing.
  493. .pp
  494. If you are in a new domain
  495. (e.g., a company),
  496. you will probably want to create a
  497. cf/domain
  498. file for your domain.
  499. This consists primarily of relay definitions
  500. and features you want enabled site-wide:
  501. for example, Berkeley's domain definition
  502. defines relays for
  503. BitNET
  504. and UUCP.
  505. These are specific to Berkeley,
  506. and should be fully-qualified internet-style domain names.
  507. Please check to make certain they are reasonable for your domain.
  508. .pp
  509. Subdomains at Berkeley are also represented in the
  510. cf/domain
  511. directory.
  512. For example,
  513. the domain
  514. CS.Berkeley.EDU
  515. is the Computer Science subdomain,
  516. EECS.Berkeley.EDU
  517. is the Electrical Engineering and Computer Sciences subdomain,
  518. and
  519. S2K.Berkeley.EDU
  520. is the Sequoia 2000 subdomain.
  521. You will probably have to add an entry to this directory
  522. to be appropriate for your domain.
  523. .pp
  524. You will have to use or create
  525. .b &.mc
  526. files in the
  527. .i cf/cf
  528. subdirectory for your hosts.
  529. This is detailed in the
  530. cf/README
  531. file.
  532. .sh 2 "Details of Installation Files"
  533. .pp
  534. This subsection describes the files that
  535. comprise the
  536. .i sendmail
  537. installation.
  538. .sh 3 "/usr/*(SD/sendmail"
  539. .pp
  540. The binary for
  541. .i sendmail
  542. is located in /usr/*(SD**.
  543. .(f
  544. **This is usually
  545. /usr/sbin
  546. on 4.4BSD and newer systems;
  547. many systems install it in
  548. /usr/lib.
  549. I understand it is in /usr/ucblib
  550. on System V Release 4.
  551. .)f
  552. It should be setuid root.
  553. For security reasons,
  554. /, /usr, and /usr/*(SD
  555. should be owned by root, mode 755**.
  556. .(f
  557. **Some vendors ship them owned by bin;
  558. this creates a security hole that is not actually related to
  559. .i sendmail .
  560. Other important directories that should have restrictive ownerships
  561. and permissions are
  562. /bin, /usr/bin, /etc, /etc/mail, /usr/etc, /lib, and /usr/lib.
  563. .)f
  564. .sh 3 "/etc/mail/sendmail.cf"
  565. .pp
  566. This is the configuration file for
  567. .i sendmail **.
  568. .(f
  569. **Actually, the pathname varies depending on the operating system;
  570. /etc/mail is the preferred directory.
  571. Some older systems install it in
  572. .b /usr/lib/sendmail.cf ,
  573. and I've also seen it in
  574. .b /usr/ucblib .
  575. If you want to move this file,
  576. add -D_PATH_SENDMAILCF=e"/file/namee"
  577. to the flags passed to the C compiler.
  578. Moving this file is not recommended:
  579. other programs and scripts know of this location.
  580. .)f
  581. This is the only non-library file name compiled into
  582. .i sendmail **.
  583. .(f
  584. **The system libraries can reference other files;
  585. in particular, system library subroutines that
  586. .i sendmail
  587. calls probably reference
  588. .i /etc/passwd
  589. and
  590. .i /etc/resolv.conf .
  591. .)f
  592. .pp
  593. The configuration file is normally created
  594. using the distribution files described above.
  595. If you have a particularly unusual system configuration
  596. you may need to create a special version.
  597. The format of this file is detailed in later sections
  598. of this document.
  599. .sh 3 "/usr/*(SB/newaliases"
  600. .pp
  601. The
  602. .i newaliases
  603. command should just be a link to
  604. .i sendmail :
  605. .(b
  606. rm -f /usr/*(SB/newaliases
  607. ln -s /usr/*(SD/sendmail /usr/*(SB/newaliases
  608. .)b
  609. This can be installed in whatever search path you prefer
  610. for your system.
  611. .sh 3 "/usr/*(SB/hoststat"
  612. .pp
  613. The
  614. .i hoststat
  615. command should just be a link to
  616. .i sendmail ,
  617. in a fashion similar to
  618. .i newaliases .
  619. This command lists the status of the last mail transaction
  620. with all remote hosts.  The
  621. .b -v
  622. flag will prevent the status display from being truncated.
  623. It functions only when the
  624. .b HostStatusDirectory
  625. option is set.
  626. .sh 3 "/usr/*(SB/purgestat"
  627. .pp
  628. This command is also a link to
  629. .i sendmail .
  630. It flushes all information that is stored in the
  631. .b HostStatusDirectory
  632. tree.
  633. .sh 3 "/var/spool/mqueue"
  634. .pp
  635. The directory
  636. .i /var/spool/mqueue
  637. should be created to hold the mail queue.
  638. This directory should be mode 700
  639. and owned by root.
  640. .pp
  641. The actual path of this directory
  642. is defined in the
  643. .b Q
  644. option of the
  645. .i sendmail.cf
  646. file.
  647. To use multiple queues,
  648. supply a value ending with an asterisk.
  649. For example,
  650. .i /var/spool/mqueue/q*
  651. will use all of the directories or symbolic links to directories
  652. beginning with `q' in
  653. .i /var/spool/mqueue
  654. as queue directories.
  655. Do not change the queue directory structure
  656. while sendmail is running.
  657. .pp
  658. If these directories have subdirectories or symbolic links to directories
  659. named `qf', `df', and `xf', then these will be used for the different
  660. queue file types.
  661. That is, the data files are stored in the `df' subdirectory,
  662. the transcript files are stored in the `xf' subdirectory, and
  663. all others are stored in the `qf' subdirectory.
  664. .sh 3 "/var/spool/mqueue/.hoststat"
  665. .pp
  666. This is a typical value for the
  667. .b HostStatusDirectory
  668. option,
  669. containing one file per host
  670. that this sendmail has chatted with recently.
  671. It is normally a subdirectory of
  672. .i mqueue .
  673. .sh 3 "/etc/mail/aliases*"
  674. .pp
  675. The system aliases are held in
  676. .q /etc/mail/aliases .
  677. A sample is given in
  678. .q sendmail/aliases
  679. which includes some aliases which
  680. .i must
  681. be defined:
  682. .(b
  683. cp lib/aliases /etc/mail/aliases
  684. .i "edit /etc/mail/aliases"
  685. .)b
  686. You should extend this file with any aliases that are apropos to your system.
  687. .pp
  688. Normally
  689. .i sendmail
  690. looks at a database version of the files,
  691. stored either in
  692. .q /etc/mail/aliases.dir
  693. and
  694. .q /etc/mail/aliases.pag
  695. or
  696. .q /etc/mail/aliases.db
  697. depending on which database package you are using.
  698. The actual path of this file
  699. is defined in the
  700. .b AliasFile
  701. option of the
  702. .i sendmail.cf
  703. file.
  704. .sh 3 "/etc/rc or /etc/init.d/sendmail"
  705. .pp
  706. It will be necessary to start up the
  707. .i sendmail
  708. daemon when your system reboots.
  709. This daemon performs two functions:
  710. it listens on the SMTP socket for connections
  711. (to receive mail from a remote system)
  712. and it processes the queue periodically
  713. to insure that mail gets delivered when hosts come up.
  714. .pp
  715. Add the following lines to
  716. .q /etc/rc
  717. (or
  718. .q /etc/rc.local
  719. as appropriate)
  720. in the area where it is starting up the daemons
  721. on a BSD-base system,
  722. or on a System-V-based system
  723. in one of the startup files, typically
  724. .q /etc/init.d/sendmail :
  725. .(b
  726. if [ -f /usr/*(SD/sendmail -a -f /etc/mail/sendmail.cf ]; then
  727. (cd /var/spool/mqueue; rm -f [lnx]f*)
  728. /usr/*(SD/sendmail -bd -q30m &
  729. echo -n ' sendmail' >/dev/console
  730. fi
  731. .)b
  732. The
  733. .q cd
  734. and
  735. .q rm
  736. commands insure that all lock files have been removed;
  737. extraneous lock files may be left around
  738. if the system goes down in the middle of processing a message.
  739. The line that actually invokes
  740. .i sendmail
  741. has two flags:
  742. .q -bd
  743. causes it to listen on the SMTP port,
  744. and
  745. .q -q30m
  746. causes it to run the queue every half hour.
  747. .pp
  748. Some people use a more complex startup script,
  749. removing zero length qf files and df files for which there is no qf file.
  750. For example, see Figure 1
  751. for an example of a complex script which does this clean up.
  752. .(z
  753. .hl
  754. #!/bin/sh
  755. # remove zero length qf files
  756. for qffile in qf*
  757. do
  758. if [ -r $qffile ]
  759. then
  760. if [ ! -s $qffile ]
  761. then
  762. echo -n " <zero: $qffile>" > /dev/console
  763. rm -f $qffile
  764. fi
  765. fi
  766. done
  767. # rename tf files to be qf if the qf does not exist
  768. for tffile in tf*
  769. do
  770. qffile=`echo $tffile | sed 's/t/q/'`
  771. if [ -r $tffile -a ! -f $qffile ]
  772. then
  773. echo -n " <recovering: $tffile>" > /dev/console
  774. mv $tffile $qffile
  775. else
  776. if [ -f $tffile ]
  777. then
  778. echo -n " <extra: $tffile>" > /dev/console
  779. rm -f $tffile
  780. fi
  781. fi
  782. done
  783. # remove df files with no corresponding qf files
  784. for dffile in df*
  785. do
  786. qffile=`echo $dffile | sed 's/d/q/'`
  787. if [ -r $dffile -a ! -f $qffile ]
  788. then
  789. echo -n " <incomplete: $dffile>" > /dev/console
  790. mv $dffile `echo $dffile | sed 's/d/D/'`
  791. fi
  792. done
  793. # announce files that have been saved during disaster recovery
  794. for xffile in [A-Z]f*
  795. do
  796. if [ -f $xffile ]
  797. then
  798. echo -n " <panic: $xffile>" > /dev/console
  799. fi
  800. done
  801. .sp
  802. .ce
  803. Figure 1 (em A complex startup script
  804. .hl
  805. .)z
  806. .pp
  807. If you are not running a version of UNIX
  808. that supports Berkeley TCP/IP,
  809. do not include the
  810. .b -bd
  811. flag.
  812. .sh 3 "/etc/mail/helpfile"
  813. .pp
  814. This is the help file used by the SMTP
  815. .b HELP
  816. command.
  817. It should be copied from
  818. .q sendmail/helpfile :
  819. .(b
  820. cp sendmail/helpfile /etc/mail/helpfile
  821. .)b
  822. The actual path of this file
  823. is defined in the
  824. .b HelpFile
  825. option of the
  826. .i sendmail.cf
  827. file.
  828. .sh 3 "/etc/mail/statistics"
  829. .pp
  830. If you wish to collect statistics
  831. about your mail traffic,
  832. you should create the file
  833. .q /etc/mail/statistics :
  834. .(b
  835. cp /dev/null /etc/mail/statistics
  836. chmod 644 /etc/mail/statistics
  837. .)b
  838. This file does not grow.
  839. It is printed with the program
  840. .q mailstats/mailstats.c.
  841. The actual path of this file
  842. is defined in the
  843. .b S
  844. option of the
  845. .i sendmail.cf
  846. file.
  847. .sh 3 "/usr/*(SB/mailq"
  848. .pp
  849. If
  850. .i sendmail
  851. is invoked as
  852. .q mailq,
  853. it will simulate the
  854. .b -bp
  855. flag
  856. (i.e.,
  857. .i sendmail
  858. will print the contents of the mail queue;
  859. see below).
  860. This should be a link to /usr/*(SD/sendmail.
  861. .sh 1 "NORMAL OPERATIONS"
  862. .sh 2 "The System Log"
  863. .pp
  864. The system log is supported by the
  865. .i syslogd |(8)
  866. program.
  867. All messages from
  868. .i sendmail
  869. are logged under the
  870. .sm LOG_MAIL
  871. facility**.
  872. .(f
  873. **Except on Ultrix,
  874. which does not support facilities in the syslog.
  875. .)f
  876. .sh 3 "Format"
  877. .pp
  878. Each line in the system log
  879. consists of a timestamp,
  880. the name of the machine that generated it
  881. (for logging from several machines
  882. over the local area network),
  883. the word
  884. .q sendmail: ,
  885. and a message**.
  886. .(f
  887. **This format may vary slightly if your vendor has changed
  888. the syntax.
  889. .)f
  890. Most messages are a sequence of
  891. .i name c
  892. =c
  893. .i value
  894. pairs.
  895. .pp
  896. The two most common lines are logged when a message is processed.
  897. The first logs the receipt of a message;
  898. there will be exactly one of these per message.
  899. Some fields may be omitted if they do not contain interesting information.
  900. Fields are:
  901. .ip from
  902. The envelope sender address.
  903. .ip size
  904. The size of the message in bytes.
  905. .ip class
  906. The class (i.e., numeric precedence) of the message.
  907. .ip pri
  908. The initial message priority (used for queue sorting).
  909. .ip nrcpts
  910. The number of envelope recipients for this message
  911. (after aliasing and forwarding).
  912. .ip msgid
  913. The message id of the message (from the header).
  914. .ip proto
  915. The protocol used to receive this message (e.g., ESMTP or UUCP)
  916. .ip relay
  917. The machine from which it was received.
  918. .lp
  919. There is also one line logged per delivery attempt
  920. (so there can be several per message if delivery is deferred
  921. or there are multiple recipients).
  922. Fields are:
  923. .ip to
  924. A comma-separated list of the recipients to this mailer.
  925. .ip ctladdr
  926. The ``controlling user'', that is, the name of the user
  927. whose credentials we use for delivery.
  928. .ip delay
  929. The total delay between the time this message was received
  930. and the time it was delivered.
  931. .ip xdelay
  932. The amount of time needed in this delivery attempt
  933. (normally indicative of the speed of the connection).
  934. .ip mailer
  935. The name of the mailer used to deliver to this recipient.
  936. .ip relay
  937. The name of the host that actually accepted (or rejected) this recipient.
  938. .ip stat
  939. The delivery status.
  940. .lp
  941. Not all fields are present in all messages;
  942. for example, the relay is not listed for local deliveries.
  943. .sh 3 "Levels"
  944. .pp
  945. If you have
  946. .i syslogd |(8)
  947. or an equivalent installed,
  948. you will be able to do logging.
  949. There is a large amount of information that can be logged.
  950. The log is arranged as a succession of levels.
  951. At the lowest level
  952. only extremely strange situations are logged.
  953. At the highest level,
  954. even the most mundane and uninteresting events
  955. are recorded for posterity.
  956. As a convention,
  957. log levels under ten
  958. are considered generally
  959. .q useful;
  960. log levels above 64
  961. are reserved for debugging purposes.
  962. Levels from 11-64 are reserved for verbose information
  963. that some sites might want.
  964. .pp
  965. A complete description of the log levels
  966. is given in section
  967. ." XREF
  968. 4.6.
  969. .sh 2 "Dumping State"
  970. .pp
  971. You can ask
  972. .i sendmail
  973. to log a dump of the open files
  974. and the connection cache
  975. by sending it a
  976. .sm SIGUSR1
  977. signal.
  978. The results are logged at
  979. .sm LOG_DEBUG
  980. priority.
  981. .sh 2 "The Mail Queue"
  982. .pp
  983. Sometimes a host cannot handle a message immediately.
  984. For example, it may be down or overloaded, causing it to refuse connections.
  985. The sending host is then expected to save this message in
  986. its mail queue
  987. and attempt to deliver it later.
  988. .pp
  989. Under normal conditions the mail queue will be processed transparently.
  990. However, you may find that manual intervention is sometimes necessary.
  991. For example,
  992. if a major host is down for a period of time
  993. the queue may become clogged.
  994. Although
  995. .i sendmail
  996. ought to recover gracefully when the host comes up,
  997. you may find performance unacceptably bad in the meantime.
  998. .sh 3 "Printing the queue"
  999. .pp
  1000. The contents of the queue can be printed
  1001. using the
  1002. .i mailq
  1003. command
  1004. (or by specifying the
  1005. .b -bp
  1006. flag to
  1007. .i sendmail ):
  1008. .(b
  1009. mailq
  1010. .)b
  1011. This will produce a listing of the queue id's,
  1012. the size of the message,
  1013. the date the message entered the queue,
  1014. and the sender and recipients.
  1015. .sh 3 "Forcing the queue"
  1016. .pp
  1017. .i Sendmail
  1018. should run the queue automatically
  1019. at intervals.
  1020. When using multiple queues,
  1021. a separate process will be created to
  1022. run each of the queues
  1023. unless the queue run is initiated by a user
  1024. with the verbose flag.
  1025. The algorithm is to read and sort the queue,
  1026. and then to attempt to process all jobs in order.
  1027. When it attempts to run the job,
  1028. .i sendmail
  1029. first checks to see if the job is locked.
  1030. If so, it ignores the job.
  1031. .pp
  1032. There is no attempt to insure that only one queue processor
  1033. exists at any time,
  1034. since there is no guarantee that a job cannot take forever
  1035. to process
  1036. (however,
  1037. .i sendmail
  1038. does include heuristics to try to abort jobs
  1039. that are taking absurd amounts of time;
  1040. technically, this violates RFC 821, but is blessed by RFC 1123).
  1041. Due to the locking algorithm,
  1042. it is impossible for one job to freeze the entire queue.
  1043. However,
  1044. an uncooperative recipient host
  1045. or a program recipient
  1046. that never returns
  1047. can accumulate many processes in your system.
  1048. Unfortunately,
  1049. there is no completely general way to solve this.
  1050. .pp
  1051. In some cases,
  1052. you may find that a major host going down
  1053. for a couple of days
  1054. may create a prohibitively large queue.
  1055. This will result in
  1056. .i sendmail
  1057. spending an inordinate amount of time
  1058. sorting the queue.
  1059. This situation can be fixed by moving the queue to a temporary place
  1060. and creating a new queue.
  1061. The old queue can be run later when the offending host returns to service.
  1062. .pp
  1063. To do this,
  1064. it is acceptable to move the entire queue directory:
  1065. .(b
  1066. cd /var/spool
  1067. mv mqueue omqueue; mkdir mqueue; chmod 700 mqueue
  1068. .)b
  1069. You should then kill the existing daemon
  1070. (since it will still be processing in the old queue directory)
  1071. and create a new daemon.
  1072. .pp
  1073. To run the old mail queue,
  1074. run the following command:
  1075. .(b
  1076. /usr/*(SD/sendmail -oQ/var/spool/omqueue -q
  1077. .)b
  1078. The
  1079. .b -oQ
  1080. flag specifies an alternate queue directory
  1081. and the
  1082. .b -q
  1083. flag says to just run every job in the queue.
  1084. If you have a tendency toward voyeurism,
  1085. you can use the
  1086. .b -v
  1087. flag to watch what is going on.
  1088. .pp
  1089. When the queue is finally emptied,
  1090. you can remove the directory:
  1091. .(b
  1092. rmdir /var/spool/omqueue
  1093. .)b
  1094. .sh 2 "Disk Based Connection Information"
  1095. .pp
  1096. .i Sendmail
  1097. stores a large amount of information about each remote system it
  1098. has connected to in memory. It is now possible to preserve some
  1099. of this information on disk as well, by using the
  1100. .b HostStatusDirectory
  1101. option, so that it may be shared between several invocations of
  1102. .i sendmail .
  1103. This allows mail to be queued immediately or skipped during a queue run if
  1104. there has been a recent failure in connecting to a remote machine.
  1105. .pp
  1106. Additionally enabling
  1107. .b SingleThreadDelivery
  1108. has the added effect of single-threading mail delivery to a destination.
  1109. This can be quite helpful
  1110. if the remote machine is running an SMTP server that is easily overloaded
  1111. or cannot accept more than a single connection at a time,
  1112. but can cause some messages to be punted to a future queue run.
  1113. It also applies to
  1114. .i all
  1115. hosts, so setting this because you have one machine on site
  1116. that runs some software that is easily overrun
  1117. can cause mail to other hosts to be slowed down.
  1118. If this option is set,
  1119. you probably want to set the
  1120. .b MinQueueAge
  1121. option as well and run the queue fairly frequently;
  1122. this way jobs that are skipped because another
  1123. .i sendmail
  1124. is talking to the same host will be tried again quickly
  1125. rather than being delayed for a long time.
  1126. .pp
  1127. The disk based host information is stored in a subdirectory of the
  1128. .b mqueue
  1129. directory called
  1130. .b &.hoststat **.
  1131. .(f
  1132. **This is the usual value of the
  1133. .b HostStatusDirectory
  1134. option;
  1135. it can, of course, go anywhere you like in your filesystem.
  1136. .)f
  1137. Removing this directory and its subdirectories has an effect similar to
  1138. the
  1139. .i purgestat
  1140. command and is completely safe.
  1141. The information in these directories can
  1142. be perused with the
  1143. .i hoststat
  1144. command, which will indicate the host name, the last access, and the
  1145. status of that access.
  1146. An asterisk in the left most column indicates that a
  1147. .i sendmail
  1148. process currently has the host locked for mail delivery.
  1149. .pp
  1150. The disk based connection information is treated the same way as memory based
  1151. connection information for the purpose of timeouts.
  1152. By default, information about host failures is valid for 30 minutes.
  1153. This can be adjusted with
  1154. the
  1155. .b Timeout.hoststatus
  1156. option.
  1157. .pp
  1158. The connection information stored on disk may be purged at any time
  1159. with the
  1160. .i purgestat
  1161. command or by invoking sendmail with the
  1162. .b -bH
  1163. switch.
  1164. The connection information may be viewed with the
  1165. .i hoststat
  1166. command or by invoking sendmail with the
  1167. .b -bh
  1168. switch.
  1169. .sh 2 "The Service Switch"
  1170. .pp
  1171. The implementation of certain system services
  1172. such as host and user name lookup
  1173. is controlled by the service switch.
  1174. If the host operating system supports such a switch
  1175. .i sendmail
  1176. will use the native version.
  1177. Ultrix, Solaris, and DEC OSF/1 are examples of such systems**.
  1178. .(f
  1179. **HP-UX 10 has service switch support,
  1180. but since the APIs are apparently not available in the libraries
  1181. .i sendmail
  1182. does not use the native service switch in this release.
  1183. .)f
  1184. .pp
  1185. If the underlying operating system does not support a service switch
  1186. (e.g., SunOS 4.X, HP-UX, BSD)
  1187. then
  1188. .i sendmail
  1189. will provide a stub implementation.
  1190. The
  1191. .b ServiceSwitchFile
  1192. option points to the name of a file that has the service definitions.
  1193. Each line has the name of a service
  1194. and the possible implementations of that service.
  1195. For example, the file:
  1196. .(b
  1197. hosts dns files nis
  1198. aliases files nis
  1199. .)b
  1200. will ask
  1201. .i sendmail
  1202. to look for hosts in the Domain Name System first.
  1203. If the requested host name is not found,
  1204. it tries local files,
  1205. and if that fails it tries NIS.
  1206. Similarly,
  1207. when looking for aliases
  1208. it will try the local files first
  1209. followed by NIS.
  1210. .pp
  1211. Service switches are not completely integrated.
  1212. For example, despite the fact that the host entry listed in the above example
  1213. specifies to look in NIS,
  1214. on SunOS this won't happen because the system implementation of
  1215. .i gethostbyname |(3)
  1216. doesn't understand this.
  1217. If there is enough demand
  1218. .i sendmail
  1219. may reimplement
  1220. .i gethostbyname |(3),
  1221. .i gethostbyaddr |(3),
  1222. .i getpwent |(3),
  1223. and the other system routines that would be necessary
  1224. to make this work seamlessly.
  1225. .sh 2 "The Alias Database"
  1226. .pp
  1227. After recipient addresses are read from the SMTP connection
  1228. or command line
  1229. they are parsed by ruleset 0,
  1230. which must resolve to a
  1231. {c
  1232. .i mailer ,
  1233. .i host ,
  1234. .i address }
  1235. triple.
  1236. If the flags selected by the
  1237. .i mailer
  1238. include the
  1239. .b A
  1240. (aliasable) flag,
  1241. the
  1242. .i address
  1243. part of the triple is looked up as the key
  1244. (i.e., the left hand side)
  1245. into the alias database.
  1246. If there is a match, the address is deleted from the send queue
  1247. and all addresses on the right hand side of the alias
  1248. are added in place of the alias that was found.
  1249. This is a recursive operation,
  1250. so aliases found in the right hand side of the alias
  1251. are similarly expanded.
  1252. .pp
  1253. The alias database exists in two forms.
  1254. One is a text form,
  1255. maintained in the file
  1256. .i /etc/mail/aliases.
  1257. The aliases are of the form
  1258. .(b
  1259. name: name1, name2, ...
  1260. .)b
  1261. Only local names may be aliased;
  1262. e.g.,
  1263. .(b
  1264. eric@prep.ai.MIT.EDU: eric@CS.Berkeley.EDU
  1265. .)b
  1266. will not have the desired effect
  1267. (except on prep.ai.MIT.EDU,
  1268. and they probably don't want me)**.
  1269. .(f
  1270. **Actually, any mailer that has the `A' mailer flag set
  1271. will permit aliasing;
  1272. this is normally limited to the local mailer.
  1273. .)f
  1274. Aliases may be continued by starting any continuation lines
  1275. with a space or a tab or by putting a backslash directly before
  1276. the newline.
  1277. Blank lines and lines beginning with a sharp sign
  1278. (c
  1279. .q # )
  1280. are comments.
  1281. .pp
  1282. The second form is processed by the
  1283. .i ndbm |(3)**
  1284. .(f
  1285. **The
  1286. .i gdbm
  1287. package does not work.
  1288. .)f
  1289. or the Berkeley DB library.
  1290. This form is in the file
  1291. .i /etc/mail/aliases.db
  1292. (if using NEWDB)
  1293. or
  1294. .i /etc/mail/aliases.dir
  1295. and
  1296. .i /etc/mail/aliases.pag
  1297. (if using NDBM).
  1298. This is the form that
  1299. .i sendmail
  1300. actually uses to resolve aliases.
  1301. This technique is used to improve performance.
  1302. .pp
  1303. The control of search order is actually set by the service switch.
  1304. Essentially, the entry
  1305. .(b
  1306. O AliasFile=switch:aliases
  1307. .)b
  1308. is always added as the first alias entry;
  1309. also, the first alias file name without a class
  1310. (e.g., without
  1311. .q nis:
  1312. on the front)
  1313. will be used as the name of the file for a ``files'' entry
  1314. in the aliases switch.
  1315. For example, if the configuration file contains
  1316. .(b
  1317. O AliasFile=/etc/mail/aliases
  1318. .)b
  1319. and the service switch contains
  1320. .(b
  1321. aliases nis files nisplus
  1322. .)b
  1323. then aliases will first be searched in the NIS database,
  1324. then in /etc/mail/aliases,
  1325. then in the NIS+ database.
  1326. .pp
  1327. You can also use
  1328. .sm NIS -based
  1329. alias files.
  1330. For example, the specification:
  1331. .(b
  1332. O AliasFile=/etc/mail/aliases
  1333. O AliasFile=nis:mail.aliases@my.nis.domain
  1334. .)b
  1335. will first search the /etc/mail/aliases file
  1336. and then the map named
  1337. .q mail.aliases
  1338. in
  1339. .q my.nis.domain .
  1340. Warning: if you build your own
  1341. .sm NIS -based
  1342. alias files,
  1343. be sure to provide the
  1344. .b -l
  1345. flag to
  1346. .i makedbm (8)
  1347. to map upper case letters in the keys to lower case;
  1348. otherwise, aliases with upper case letters in their names
  1349. won't match incoming addresses.
  1350. .pp
  1351. Additional flags can be added after the colon
  1352. exactly like a
  1353. .b K
  1354. line (em for example:
  1355. .(b
  1356. O AliasFile=nis:-N mail.aliases@my.nis.domain
  1357. .)b
  1358. will search the appropriate NIS map and always include null bytes in the key.
  1359. Also:
  1360. .(b
  1361. O AliasFile=nis:-f mail.aliases@my.nis.domain
  1362. .)b
  1363. will prevent sendmail from downcasing the key before the alias lookup.
  1364. .sh 3 "Rebuilding the alias database"
  1365. .pp
  1366. The
  1367. .i hash
  1368. or
  1369. .i dbm
  1370. version of the database
  1371. may be rebuilt explicitly by executing the command
  1372. .(b
  1373. newaliases
  1374. .)b
  1375. This is equivalent to giving
  1376. .i sendmail
  1377. the
  1378. .b -bi
  1379. flag:
  1380. .(b
  1381. /usr/*(SD/sendmail -bi
  1382. .)b
  1383. .pp
  1384. If the
  1385. .b RebuildAliases
  1386. (old
  1387. .b D )
  1388. option is specified in the configuration,
  1389. .i sendmail
  1390. will rebuild the alias database automatically
  1391. if possible
  1392. when it is out of date.
  1393. Auto-rebuild can be dangerous
  1394. on heavily loaded machines
  1395. with large alias files;
  1396. if it might take more than the rebuild timeout
  1397. (option
  1398. .b AliasWait ,
  1399. old
  1400. .b a ,
  1401. which is normally five minutes)
  1402. to rebuild the database,
  1403. there is a chance that several processes will start the rebuild process
  1404. simultaneously.
  1405. .pp
  1406. If you have multiple aliases databases specified,
  1407. the
  1408. .b -bi
  1409. flag rebuilds all the database types it understands
  1410. (for example, it can rebuild NDBM databases but not NIS databases).
  1411. .sh 3 "Potential problems"
  1412. .pp
  1413. There are a number of problems that can occur
  1414. with the alias database.
  1415. They all result from a
  1416. .i sendmail
  1417. process accessing the DBM version
  1418. while it is only partially built.
  1419. This can happen under two circumstances:
  1420. One process accesses the database
  1421. while another process is rebuilding it,
  1422. or the process rebuilding the database dies
  1423. (due to being killed or a system crash)
  1424. before completing the rebuild.
  1425. .pp
  1426. Sendmail has three techniques to try to relieve these problems.
  1427. First, it ignores interrupts while rebuilding the database;
  1428. this avoids the problem of someone aborting the process
  1429. leaving a partially rebuilt database.
  1430. Second,
  1431. it locks the database source file during the rebuild (em
  1432. but that may not work over NFS or if the file is unwritable.
  1433. Third,
  1434. at the end of the rebuild
  1435. it adds an alias of the form
  1436. .(b
  1437. @: @
  1438. .)b
  1439. (which is not normally legal).
  1440. Before
  1441. .i sendmail
  1442. will access the database,
  1443. it checks to insure that this entry exists**.
  1444. .(f
  1445. **The
  1446. .b AliasWait
  1447. option is required in the configuration
  1448. for this action to occur.
  1449. This should normally be specified.
  1450. .)f
  1451. .sh 3 "List owners"
  1452. .pp
  1453. If an error occurs on sending to a certain address,
  1454. say
  1455. .q fIxfP ,
  1456. .i sendmail
  1457. will look for an alias
  1458. of the form
  1459. .q owner-fIxfP
  1460. to receive the errors.
  1461. This is typically useful
  1462. for a mailing list
  1463. where the submitter of the list
  1464. has no control over the maintenance of the list itself;
  1465. in this case the list maintainer would be the owner of the list.
  1466. For example:
  1467. .(b
  1468. unix-wizards: eric@ucbarpa, wnj@monet, nosuchuser,
  1469. sam@matisse
  1470. owner-unix-wizards: unix-wizards-request
  1471. unix-wizards-request: eric@ucbarpa
  1472. .)b
  1473. would cause
  1474. .q eric@ucbarpa
  1475. to get the error that will occur
  1476. when someone sends to
  1477. unix-wizards
  1478. due to the inclusion of
  1479. .q nosuchuser
  1480. on the list.
  1481. .pp
  1482. List owners also cause the envelope sender address to be modified.
  1483. The contents of the owner alias are used if they point to a single user,
  1484. otherwise the name of the alias itself is used.
  1485. For this reason, and to obey Internet conventions,
  1486. the
  1487. .q owner-
  1488. address normally points at the
  1489. .q -request
  1490. address; this causes messages to go out with the typical Internet convention
  1491. of using ``c
  1492. .i list -request''
  1493. as the return address.
  1494. .sh 2 "User Information Database"
  1495. .pp
  1496. If you have a version of
  1497. .i sendmail
  1498. with the user information database
  1499. compiled in,
  1500. and you have specified one or more databases using the
  1501. .b U
  1502. option,
  1503. the databases will be searched for a
  1504. .i user :maildrop
  1505. entry.
  1506. If found, the mail will be sent to the specified address.
  1507. .sh 2 "Per-User Forwarding (.forward Files)"
  1508. .pp
  1509. As an alternative to the alias database,
  1510. any user may put a file with the name
  1511. .q .forward
  1512. in his or her home directory.
  1513. If this file exists,
  1514. .i sendmail
  1515. redirects mail for that user
  1516. to the list of addresses listed in the .forward file.
  1517. For example, if the home directory for user
  1518. .q mckusick
  1519. has a .forward file with contents:
  1520. .(b
  1521. mckusick@ernie
  1522. kirk@calder
  1523. .)b
  1524. then any mail arriving for
  1525. .q mckusick
  1526. will be redirected to the specified accounts.
  1527. .pp
  1528. Actually, the configuration file defines a sequence of filenames to check.
  1529. By default, this is the user's .forward file,
  1530. but can be defined to be more generally using the
  1531. .b ForwardPath
  1532. option.
  1533. If you change this,
  1534. you will have to inform your user base of the change;
  1535. &.forward is pretty well incorporated into the collective subconscious.
  1536. .sh 2 "Special Header Lines"
  1537. .pp
  1538. Several header lines have special interpretations
  1539. defined by the configuration file.
  1540. Others have interpretations built into
  1541. .i sendmail
  1542. that cannot be changed without changing the code.
  1543. These builtins are described here.
  1544. .sh 3 "Errors-To:"
  1545. .pp
  1546. If errors occur anywhere during processing,
  1547. this header will cause error messages to go to
  1548. the listed addresses.
  1549. This is intended for mailing lists.
  1550. .pp
  1551. The Errors-To: header was created in the bad old days
  1552. when UUCP didn't understand the distinction between an envelope and a header;
  1553. this was a hack to provide what should now be passed
  1554. as the envelope sender address.
  1555. It should go away.
  1556. It is only used if the
  1557. .b UseErrorsTo
  1558. option is set.
  1559. .pp
  1560. The Errors-To: header is officially deprecated
  1561. and will go away in a future release.
  1562. .sh 3 "Apparently-To:"
  1563. .pp
  1564. RFC 822 requires at least one recipient field
  1565. (To:, Cc:, or Bcc: line)
  1566. in every message.
  1567. If a message comes in with no recipients listed in the message
  1568. then
  1569. .i sendmail
  1570. will adjust the header based on the
  1571. .q NoRecipientAction
  1572. option.
  1573. One of the possible actions is to add an
  1574. .q "Apparently-To:"
  1575. header line for any recipients it is aware of.
  1576. .pp
  1577. The Apparently-To: header is non-standard
  1578. and is deprecated.
  1579. .sh 3 "Precedence"
  1580. .pp
  1581. The Precedence: header can be used as a crude control of message priority.
  1582. It tweaks the sort order in the queue
  1583. and can be configured to change the message timeout values.
  1584. .sh 2 "IDENT Protocol Support"
  1585. .pp
  1586. .i Sendmail
  1587. supports the IDENT protocol as defined in RFC 1413.
  1588. Although this enhances identification
  1589. of the author of an email message
  1590. by doing a ``call back'' to the originating system to include
  1591. the owner of a particular TCP connection
  1592. in the audit trail
  1593. it is in no sense perfect;
  1594. a determined forger can easily spoof the IDENT protocol.
  1595. The following description is excerpted from RFC 1413:
  1596. .ba +5
  1597. .lp
  1598. 6.  Security Considerations
  1599. .lp
  1600. The information returned by this protocol is at most as trustworthy
  1601. as the host providing it OR the organization operating the host.  For
  1602. example, a PC in an open lab has few if any controls on it to prevent
  1603. a user from having this protocol return any identifier the user
  1604. wants.  Likewise, if the host has been compromised the information
  1605. returned may be completely erroneous and misleading.
  1606. .lp
  1607. The Identification Protocol is not intended as an authorization or
  1608. access control protocol.  At best, it provides some additional
  1609. auditing information with respect to TCP connections.  At worst, it
  1610. can provide misleading, incorrect, or maliciously incorrect
  1611. information.
  1612. .lp
  1613. The use of the information returned by this protocol for other than
  1614. auditing is strongly discouraged.  Specifically, using Identification
  1615. Protocol information to make access control decisions - either as the
  1616. primary method (i.e., no other checks) or as an adjunct to other
  1617. methods may result in a weakening of normal host security.
  1618. .lp
  1619. An Identification server may reveal information about users,
  1620. entities, objects or processes which might normally be considered
  1621. private.  An Identification server provides service which is a rough
  1622. analog of the CallerID services provided by some phone companies and
  1623. many of the same privacy considerations and arguments that apply to
  1624. the CallerID service apply to Identification.  If you wouldn't run a
  1625. "finger" server due to privacy considerations you may not want to run
  1626. this protocol.
  1627. .ba
  1628. .lp
  1629. In some cases your system may not work properly with IDENT support
  1630. due to a bug in the TCP/IP implementation.
  1631. The symptoms will be that for some hosts
  1632. the SMTP connection will be closed
  1633. almost immediately.
  1634. If this is true or if you do not want to use IDENT,
  1635. you should set the IDENT timeout to zero;
  1636. this will disable the IDENT protocol.
  1637. .sh 1 "ARGUMENTS"
  1638. .pp
  1639. The complete list of arguments to
  1640. .i sendmail
  1641. is described in detail in Appendix A.
  1642. Some important arguments are described here.
  1643. .sh 2 "Queue Interval"
  1644. .pp
  1645. The amount of time between forking a process
  1646. to run through the queue
  1647. is defined by the
  1648. .b -q
  1649. flag.
  1650. If you run with delivery mode set to
  1651. .b i
  1652. or
  1653. .b b
  1654. this can be relatively large,
  1655. since it will only be relevant
  1656. when a host that was down comes back up.
  1657. If you run in
  1658. .b q
  1659. mode
  1660. it should be relatively short,
  1661. since it defines the maximum amount of time that a message
  1662. may sit in the queue.
  1663. (See also the MinQueueAge option.)
  1664. .pp
  1665. RFC 1123 section 5.3.1.1 says that this value should be at least 30 minutes
  1666. (although that probably doesn't make sense if you use ``queue-only'' mode).
  1667. .sh 2 "Daemon Mode"
  1668. .pp
  1669. If you allow incoming mail over an IPC connection,
  1670. you should have a daemon running.
  1671. This should be set by your
  1672. .i /etc/rc
  1673. file using the
  1674. .b -bd
  1675. flag.
  1676. The
  1677. .b -bd
  1678. flag and the
  1679. .b -q
  1680. flag may be combined in one call:
  1681. .(b
  1682. /usr/*(SD/sendmail -bd -q30m
  1683. .)b
  1684. .pp
  1685. An alternative approach is to invoke sendmail from
  1686. .i inetd (8)
  1687. (use the
  1688. .b -bs
  1689. flag to ask sendmail to speak SMTP on its standard input and output).
  1690. This works and allows you to wrap
  1691. .i sendmail
  1692. in a TCP wrapper program,
  1693. but may be a bit slower since the configuration file
  1694. has to be re-read on every message that comes in.
  1695. If you do this, you still need to have a
  1696. .i sendmail
  1697. running to flush the queue:
  1698. .(b
  1699. /usr/*(SD/sendmail -q30m
  1700. .)b
  1701. .sh 2 "Forcing the Queue"
  1702. .pp
  1703. In some cases you may find that the queue has gotten clogged for some reason.
  1704. You can force a queue run
  1705. using the
  1706. .b -q
  1707. flag (with no value).
  1708. It is entertaining to use the
  1709. .b -v
  1710. flag (verbose)
  1711. when this is done to watch what happens:
  1712. .(b
  1713. /usr/*(SD/sendmail -q -v
  1714. .)b
  1715. .pp
  1716. You can also limit the jobs to those with a particular queue identifier,
  1717. sender, or recipient
  1718. using one of the queue modifiers.
  1719. For example,
  1720. .q -qRberkeley
  1721. restricts the queue run to jobs that have the string
  1722. .q berkeley
  1723. somewhere in one of the recipient addresses.
  1724. Similarly,
  1725. .q -qSstring
  1726. limits the run to particular senders and
  1727. .q -qIstring
  1728. limits it to particular queue identifiers.
  1729. .sh 2 "Debugging"
  1730. .pp
  1731. There are a fairly large number of debug flags
  1732. built into
  1733. .i sendmail .
  1734. Each debug flag has a number and a level,
  1735. where higher levels means to print out more information.
  1736. The convention is that levels greater than nine are
  1737. .q absurd,
  1738. i.e.,
  1739. they print out so much information that you wouldn't normally
  1740. want to see them except for debugging that particular piece of code.
  1741. Debug flags are set using the
  1742. .b -d
  1743. option;
  1744. the syntax is:
  1745. .(b
  1746. .ta w'debug-option  'u
  1747. debug-flag: fB-dfP debug-list
  1748. debug-list: debug-option [ , debug-option ]*
  1749. debug-option: debug-range [ . debug-level ]
  1750. debug-range: integer | integer - integer
  1751. debug-level: integer
  1752. .)b
  1753. where spaces are for reading ease only.
  1754. For example,
  1755. .(b
  1756. -d12 Set flag 12 to level 1
  1757. -d12.3 Set flag 12 to level 3
  1758. -d3-17 Set flags 3 through 17 to level 1
  1759. -d3-17.4 Set flags 3 through 17 to level 4
  1760. .)b
  1761. For a complete list of the available debug flags
  1762. you will have to look at the code
  1763. (they are too dynamic to keep this documentation up to date).
  1764. .sh 2 "Changing the Values of Options"
  1765. .pp
  1766. Options can be overridden using the
  1767. .b -o
  1768. or
  1769. .b -O
  1770. command line flags.
  1771. For example,
  1772. .(b
  1773. /usr/*(SD/sendmail -oT2m
  1774. .)b
  1775. sets the
  1776. .b T
  1777. (timeout) option to two minutes
  1778. for this run only;
  1779. the equivalent line using the long option name is
  1780. .(b
  1781. /usr/*(SD/sendmail -OTimeout.queuereturn=2m
  1782. .)b
  1783. .pp
  1784. Some options have security implications.
  1785. Sendmail allows you to set these,
  1786. but relinquishes its setuid root permissions thereafter**.
  1787. .(f
  1788. **That is, it sets its effective uid to the real uid;
  1789. thus, if you are executing as root,
  1790. as from root's crontab file or during system startup
  1791. the root permissions will still be honored.
  1792. .)f
  1793. .sh 2 "Trying a Different Configuration File"
  1794. .pp
  1795. An alternative configuration file
  1796. can be specified using the
  1797. .b -C
  1798. flag; for example,
  1799. .(b
  1800. /usr/*(SD/sendmail -Ctest.cf -oQ/tmp/mqueue
  1801. .)b
  1802. uses the configuration file
  1803. .i test.cf
  1804. instead of the default
  1805. .i /etc/mail/sendmail.cf.
  1806. If the
  1807. .b -C
  1808. flag has no value
  1809. it defaults to
  1810. .i sendmail.cf
  1811. in the current directory.
  1812. .pp
  1813. .i Sendmail
  1814. gives up its setuid root permissions
  1815. when you use this flag, so it is common to use a publicly writable directory
  1816. (such as /tmp)
  1817. as the spool directory (QueueDirectory or Q option) while testing.
  1818. .sh 2 "Logging Traffic"
  1819. .pp
  1820. Many SMTP implementations do not fully implement the protocol.
  1821. For example, some personal computer based SMTPs
  1822. do not understand continuation lines in reply codes.
  1823. These can be very hard to trace.
  1824. If you suspect such a problem, you can set traffic logging using the
  1825. .b -X
  1826. flag.
  1827. For example,
  1828. .(b
  1829. /usr/*(SD/sendmail -X /tmp/traffic -bd
  1830. .)b
  1831. will log all traffic in the file
  1832. .i /tmp/traffic .
  1833. .pp
  1834. This logs a lot of data very quickly and should
  1835. .b NEVER
  1836. be used
  1837. during normal operations.
  1838. After starting up such a daemon,
  1839. force the errant implementation to send a message to your host.
  1840. All message traffic in and out of
  1841. .i sendmail ,
  1842. including the incoming SMTP traffic,
  1843. will be logged in this file.
  1844. .sh 2 "Testing Configuration Files"
  1845. .pp
  1846. When you build a configuration table,
  1847. you can do a certain amount of testing
  1848. using the
  1849. .q "test mode"
  1850. of
  1851. .i sendmail .
  1852. For example,
  1853. you could invoke
  1854. .i sendmail
  1855. as:
  1856. .(b
  1857. sendmail -bt -Ctest.cf
  1858. .)b
  1859. which would read the configuration file
  1860. .q test.cf
  1861. and enter test mode.
  1862. In this mode,
  1863. you enter lines of the form:
  1864. .(b
  1865. rwset address
  1866. .)b
  1867. where
  1868. .i rwset
  1869. is the rewriting set you want to use
  1870. and
  1871. .i address
  1872. is an address to apply the set to.
  1873. Test mode shows you the steps it takes
  1874. as it proceeds,
  1875. finally showing you the address it ends up with.
  1876. You may use a comma separated list of rwsets
  1877. for sequential application of rules to an input.
  1878. For example:
  1879. .(b
  1880. 3,1,21,4 monet:bollard
  1881. .)b
  1882. first applies ruleset three to the input
  1883. .q monet:bollard.
  1884. Ruleset one is then applied to the output of ruleset three,
  1885. followed similarly by rulesets twenty-one and four.
  1886. .pp
  1887. If you need more detail,
  1888. you can also use the
  1889. .q -d21
  1890. flag to turn on more debugging.
  1891. For example,
  1892. .(b
  1893. sendmail -bt -d21.99
  1894. .)b
  1895. turns on an incredible amount of information;
  1896. a single word address
  1897. is probably going to print out several pages worth of information.
  1898. .pp
  1899. You should be warned that internally,
  1900. .i sendmail
  1901. applies ruleset 3 to all addresses.
  1902. In test mode
  1903. you will have to do that manually.
  1904. For example, older versions allowed you to use
  1905. .(b
  1906. 0 bruce@broadcast.sony.com
  1907. .)b
  1908. This version requires that you use:
  1909. .(b
  1910. 3,0 bruce@broadcast.sony.com
  1911. .)b
  1912. .pp
  1913. As of version 8.7,
  1914. some other syntaxes are available in test mode:
  1915. .bu
  1916. &.D|x|value
  1917. defines macro
  1918. .i x
  1919. to have the indicated
  1920. .i value .
  1921. This is useful when debugging rules that use the
  1922. .b $& c
  1923. .i x
  1924. syntax.
  1925. .bu
  1926. &.C|c|value
  1927. adds the indicated
  1928. .i value
  1929. to class
  1930. .i c .
  1931. .bu
  1932. &.S|ruleset
  1933. dumps the contents of the indicated ruleset.
  1934. .bu
  1935. -d|debug-spec
  1936. is equivalent to the command-line flag.
  1937. .sh 2 "Persistent Host Status Information"
  1938. .pp
  1939. When
  1940. .b HostStatusDirectory
  1941. is enabled,
  1942. information about the status of hosts is maintained on disk
  1943. and can thus be shared between different instantiations of
  1944. .i sendmail .
  1945. The status of the last connection with each remote host
  1946. may be viewed with the command:
  1947. .(b
  1948. sendmail -bh
  1949. .)b
  1950. This information may be flushed with the command:
  1951. .(b
  1952. sendmail -bH
  1953. .)b
  1954. Flushing the information prevents new
  1955. .i sendmail
  1956. processes from loading it,
  1957. but does not prevent existing processes from using the status information
  1958. that they already have.
  1959. .sh 1 "TUNING"
  1960. .pp
  1961. There are a number of configuration parameters
  1962. you may want to change,
  1963. depending on the requirements of your site.
  1964. Most of these are set
  1965. using an option in the configuration file.
  1966. For example,
  1967. the line
  1968. .q "O Timeout.queuereturn=5d"
  1969. sets option
  1970. .q Timeout.queuereturn
  1971. to the value
  1972. .q 5d
  1973. (five days).
  1974. .pp
  1975. Most of these options have appropriate defaults for most sites.
  1976. However,
  1977. sites having very high mail loads may find they need to tune them
  1978. as appropriate for their mail load.
  1979. In particular,
  1980. sites experiencing a large number of small messages,
  1981. many of which are delivered to many recipients,
  1982. may find that they need to adjust the parameters
  1983. dealing with queue priorities.
  1984. .pp
  1985. All versions of
  1986. .i sendmail
  1987. prior to 8.7
  1988. had single character option names.
  1989. As of 8.7,
  1990. options have long (multi-character names).
  1991. Although old short names are still accepted,
  1992. most new options do not have short equivalents.
  1993. .pp
  1994. This section only describes the options you are most likely
  1995. to want to tweak;
  1996. read section
  1997. ."XREF
  1998. 5
  1999. for more details.
  2000. .sh 2 "Timeouts"
  2001. .pp
  2002. All time intervals are set
  2003. using a scaled syntax.
  2004. For example,
  2005. .q 10m
  2006. represents ten minutes, whereas
  2007. .q 2h30m
  2008. represents two and a half hours.
  2009. The full set of scales is:
  2010. .(b
  2011. .ta 4n
  2012. s seconds
  2013. m minutes
  2014. h hours
  2015. d days
  2016. w weeks
  2017. .)b
  2018. .sh 3 "Queue interval"
  2019. .pp
  2020. The argument to the
  2021. .b -q
  2022. flag
  2023. specifies how often a sub-daemon will run the queue.
  2024. This is typically set to between fifteen minutes
  2025. and one hour.
  2026. RFC 1123 section 5.3.1.1 recommends that this be at least 30 minutes.
  2027. .sh 3 "Read timeouts"
  2028. .pp
  2029. Timeouts all have option names
  2030. .q Timeout.fIsuboptionfP .
  2031. The recognized
  2032. .i suboption s,
  2033. their default values, and the minimum values
  2034. allowed by RFC 1123 section 5.3.2 are:
  2035. .nr ii 1i
  2036. .ip connect
  2037. The time to wait for an SMTP connection to open
  2038. (the
  2039. .i connect (2)
  2040. system call)
  2041. [0, unspecified].
  2042. If zero, uses the kernel default.
  2043. In no case can this option extend the timeout
  2044. longer than the kernel provides, but it can shorten it.
  2045. This is to get around kernels that provide an absurdly long connection timeout
  2046. (90 minutes in one case).
  2047. .ip iconnect
  2048. The same as
  2049. .i connect,
  2050. except it applies only to the initial attempt to connect to a host
  2051. for a given message
  2052. [0, unspecified].
  2053. The concept is that this should be very short (a few seconds);
  2054. hosts that are well connected and responsive will thus be serviced immediately.
  2055. Hosts that are slow will not hold up other deliveries in the initial
  2056. delivery attempt.
  2057. .ip initial
  2058. The wait for the initial 220 greeting message
  2059. [5m, 5m].
  2060. .ip helo
  2061. The wait for a reply from a HELO or EHLO command
  2062. [5m, unspecified].
  2063. This may require a host name lookup, so
  2064. five minutes is probably a reasonable minimum.
  2065. .ip mail(dg
  2066. The wait for a reply from a MAIL command
  2067. [10m, 5m].
  2068. .ip rcpt(dg
  2069. The wait for a reply from a RCPT command
  2070. [1h, 5m].
  2071. This should be long
  2072. because it could be pointing at a list
  2073. that takes a long time to expand
  2074. (see below).
  2075. .ip datainit(dg
  2076. The wait for a reply from a DATA command
  2077. [5m, 2m].
  2078. .ip datablock(dg(dd
  2079. The wait for reading a data block
  2080. (that is, the body of the message).
  2081. [1h, 3m].
  2082. This should be long because it also applies to programs
  2083. piping input to
  2084. .i sendmail
  2085. which have no guarantee of promptness.
  2086. .ip datafinal(dg
  2087. The wait for a reply from the dot terminating a message.
  2088. [1h, 10m].
  2089. If this is shorter than the time actually needed
  2090. for the receiver to deliver the message,
  2091. duplicates will be generated.
  2092. This is discussed in RFC 1047.
  2093. .ip rset
  2094. The wait for a reply from a RSET command
  2095. [5m, unspecified].
  2096. .ip quit
  2097. The wait for a reply from a QUIT command
  2098. [2m, unspecified].
  2099. .ip misc
  2100. The wait for a reply from miscellaneous (but short) commands
  2101. such as NOOP (no-operation) and VERB (go into verbose mode).
  2102. [2m, unspecified].
  2103. .ip command(dg(dd
  2104. In server SMTP,
  2105. the time to wait for another command.
  2106. [1h, 5m].
  2107. .ip ident(dd
  2108. The timeout waiting for a reply to an IDENT query
  2109. [30s**, unspecified].
  2110. .(f
  2111. **On some systems the default is zero to turn the protocol off entirely.
  2112. .)f
  2113. .ip fileopen(dd
  2114. The timeout for opening .forward and :include: files [60s, none].
  2115. .ip control(dd
  2116. The timeout for a complete control socket transaction to complete [2m, none].
  2117. .ip hoststatus(dd
  2118. How long status information about a host
  2119. (e.g., host down)
  2120. will be cached before it is considered stale
  2121. [30m, unspecified].
  2122. .ip resolver.retrans
  2123. The resolver's
  2124. retransmission time interval
  2125. (in seconds)
  2126. [varies].
  2127. Sets both
  2128. .i Timeout.resolver.retrans.first
  2129. and
  2130. .i Timeout.resolver.retrans.normal .
  2131. .ip resolver.retrans.first
  2132. The resolver's
  2133. retransmission time interval
  2134. (in seconds)
  2135. for the first attempt to
  2136. deliver a message
  2137. [varies].
  2138. .ip resolver.retrans.normal
  2139. The resolver's
  2140. retransmission time interval
  2141. (in seconds)
  2142. for all resolver lookups
  2143. except the first delivery attempt
  2144. [varies].
  2145. .ip resolver.retry
  2146. The number of times
  2147. to retransmit a resolver query.
  2148. Sets both
  2149. .i Timeout.resolver.retry.first
  2150. and
  2151. .i Timeout.resolver.retry.normal
  2152. [varies].
  2153. .ip resolver.retry.first
  2154. The number of times
  2155. to retransmit a resolver query
  2156. for the first attempt
  2157. to deliver a message
  2158. [varies].
  2159. .ip resolver.retry.normal
  2160. The number of times
  2161. to retransmit a resolver query
  2162. for all resolver lookups
  2163.  except the first delivery attempt
  2164. [varies].
  2165. .lp
  2166. For compatibility with old configuration files,
  2167. if no
  2168. .i suboption
  2169. is specified,
  2170. all the timeouts marked with a dagger ((dg) are set to the indicated value.
  2171. All but those marked with a double dagger ((dd) apply to client SMTP.
  2172. .pp
  2173. Many of the RFC 1123 minimum values
  2174. may well be too short.
  2175. .i Sendmail
  2176. was designed to the RFC 822 protocols,
  2177. which did not specify read timeouts;
  2178. hence, versions of
  2179. .i sendmail
  2180. prior to version 8.1 did not guarantee to reply to messages promptly.
  2181. In particular, a
  2182. .q RCPT
  2183. command specifying a mailing list
  2184. will expand and verify the entire list;
  2185. a large list on a slow system
  2186. may easily take more than five minutes**.
  2187. .(f
  2188. **This verification includes looking up every address
  2189. with the name server;
  2190. this involves network delays,
  2191. and can in some cases can be considerable.
  2192. .)f
  2193. I recommend a one hour timeout *-
  2194. since a communications failure during the RCPT phase is rare,
  2195. a long timeout is not onerous
  2196. and may ultimately help reduce network load
  2197. and duplicated messages.
  2198. .pp
  2199. For example, the lines:
  2200. .(b
  2201. O Timeout.command=25m
  2202. O Timeout.datablock=3h
  2203. .)b
  2204. sets the server SMTP command timeout to 25 minutes
  2205. and the input data block timeout to three hours.
  2206. .sh 3 "Message timeouts"
  2207. .pp
  2208. After sitting in the queue for a few days,
  2209. a message will time out.
  2210. This is to insure that at least the sender is aware
  2211. of the inability to send a message.
  2212. The timeout is typically set to five days.
  2213. It is sometimes considered convenient to also send a warning message
  2214. if the message is in the queue longer than a few hours
  2215. (assuming you normally have good connectivity;
  2216. if your messages normally took several hours to send
  2217. you wouldn't want to do this because it wouldn't be an unusual event).
  2218. These timeouts are set using the
  2219. .b Timeout.queuereturn
  2220. and
  2221. .b Timeout.queuewarn
  2222. options in the configuration file
  2223. (previously both were set using the
  2224. .b T
  2225. option).
  2226. .pp
  2227. If the message is submitted using the
  2228. .sm NOTIFY
  2229. .sm SMTP
  2230. extension,
  2231. warning messages will only be sent if
  2232. .sm NOTIFY=DELAY
  2233. is specified.
  2234. The queuereturn and queuewarn timeouts
  2235. can be further qualified with a tag based on the Precedence: field
  2236. in the message;
  2237. they must be one of
  2238. .q urgent
  2239. (indicating a positive non-zero precedence)
  2240. .q normal
  2241. (indicating a zero precedence), or
  2242. .q non-urgent
  2243. (indicating negative precedences).
  2244. For example, setting
  2245. .q Timeout.queuewarn.urgent=1h
  2246. sets the warning timeout for urgent messages only
  2247. to one hour.
  2248. The default if no precedence is indicated
  2249. is to set the timeout for all precedences.
  2250. The value "now" can be used for
  2251. -O Timeout.queuereturn
  2252. to return entries immediately during a queue run,
  2253. e.g., to bounce messages independent of their time in the queue.
  2254. .pp
  2255. Since these options are global,
  2256. and since you can not know
  2257. .i "a priori"
  2258. how long another host outside your domain will be down,
  2259. a five day timeout is recommended.
  2260. This allows a recipient to fix the problem even if it occurs
  2261. at the beginning of a long weekend.
  2262. RFC 1123 section 5.3.1.1 says that this parameter
  2263. should be ``at least 4-5 days''.
  2264. .pp
  2265. The
  2266. .b Timeout.queuewarn
  2267. value can be piggybacked on the
  2268. .b T
  2269. option by indicating a time after which
  2270. a warning message should be sent;
  2271. the two timeouts are separated by a slash.
  2272. For example, the line
  2273. .(b
  2274. OT5d/4h
  2275. .)b
  2276. causes email to fail after five days,
  2277. but a warning message will be sent after four hours.
  2278. This should be large enough that the message will have been tried
  2279. several times.
  2280. .sh 2 "Forking During Queue Runs"
  2281. .pp
  2282. By setting the
  2283. .b ForkEachJob
  2284. (c
  2285. .b Y )
  2286. option,
  2287. .i sendmail
  2288. will fork before each individual message
  2289. while running the queue.
  2290. This will prevent
  2291. .i sendmail
  2292. from consuming large amounts of memory,
  2293. so it may be useful in memory-poor environments.
  2294. However, if the
  2295. .b ForkEachJob
  2296. option is not set,
  2297. .i sendmail
  2298. will keep track of hosts that are down during a queue run,
  2299. which can improve performance dramatically.
  2300. .pp
  2301. If the
  2302. .b ForkEachJob
  2303. option is set,
  2304. .i sendmail
  2305. can not use connection caching.
  2306. .sh 2 "Queue Priorities"
  2307. .pp
  2308. Every message is assigned a priority when it is first instantiated,
  2309. consisting of the message size (in bytes)
  2310. offset by the message class
  2311. (which is determined from the Precedence: header)
  2312. times the
  2313. .q "work class factor"
  2314. and the number of recipients times the
  2315. .q "work recipient factor."
  2316. The priority is used to order the queue.
  2317. Higher numbers for the priority mean that the message will be processed later
  2318. when running the queue.
  2319. .pp
  2320. The message size is included so that large messages are penalized
  2321. relative to small messages.
  2322. The message class allows users to send
  2323. .q "high priority"
  2324. messages by including a
  2325. .q Precedence:
  2326. field in their message;
  2327. the value of this field is looked up in the
  2328. .b P
  2329. lines of the configuration file.
  2330. Since the number of recipients affects the amount of load a message presents
  2331. to the system,
  2332. this is also included into the priority.
  2333. .pp
  2334. The recipient and class factors
  2335. can be set in the configuration file using the
  2336. .b RecipientFactor
  2337. (c
  2338. .b y )
  2339. and
  2340. .b ClassFactor
  2341. (c
  2342. .b z )
  2343. options respectively.
  2344. They default to 30000 (for the recipient factor)
  2345. and 1800
  2346. (for the class factor).
  2347. The initial priority is:
  2348. .EQ
  2349. pri = msgsize - (class times bold ClassFactor) + (nrcpt times bold RecipientFactor)
  2350. .EN
  2351. (Remember, higher values for this parameter actually mean
  2352. that the job will be treated with lower priority.)
  2353. .pp
  2354. The priority of a job can also be adjusted each time it is processed
  2355. (that is, each time an attempt is made to deliver it)
  2356. using the
  2357. .q "work time factor,"
  2358. set by the
  2359. .b RetryFactor
  2360. (c
  2361. .b Z )
  2362. option.
  2363. This is added to the priority,
  2364. so it normally decreases the precedence of the job,
  2365. on the grounds that jobs that have failed many times
  2366. will tend to fail again in the future.
  2367. The
  2368. .b RetryFactor
  2369. option defaults to 90000.
  2370. .sh 2 "Load Limiting"
  2371. .pp
  2372. .i Sendmail
  2373. can be asked to queue (but not deliver)
  2374. mail if the system load average gets too high
  2375. using the
  2376. .b QueueLA
  2377. (c
  2378. .b x )
  2379. option.
  2380. When the load average exceeds the value of the
  2381. .b QueueLA
  2382. option,
  2383. the delivery mode is set to
  2384. .b q
  2385. (queue only)
  2386. if the
  2387. .b QueueFactor
  2388. (c
  2389. .b q )
  2390. option divided by the difference in the current load average and the
  2391. .b QueueLA
  2392. option
  2393. plus one
  2394. exceeds the priority of the message (em
  2395. that is, the message is queued iff:
  2396. .EQ
  2397. pri > { bold QueueFactor } over { LA - { bold QueueLA } + 1 }
  2398. .EN
  2399. The
  2400. .b QueueFactor
  2401. option defaults to 600000,
  2402. so each point of load average is worth 600000
  2403. priority points
  2404. (as described above).
  2405. .pp
  2406. For drastic cases,
  2407. the
  2408. .b RefuseLA
  2409. (c
  2410. .b X )
  2411. option defines a load average at which
  2412. .i sendmail
  2413. will refuse
  2414. to accept network connections.
  2415. Locally generated mail
  2416. (including incoming UUCP mail)
  2417. is still accepted.
  2418. .sh 2 "Delivery Mode"
  2419. .pp
  2420. There are a number of delivery modes that
  2421. .i sendmail
  2422. can operate in,
  2423. set by the
  2424. .b DeliveryMode
  2425. (c
  2426. .b d )
  2427. configuration option.
  2428. These modes
  2429. specify how quickly mail will be delivered.
  2430. Legal modes are:
  2431. .(b
  2432. .ta 4n
  2433. i deliver interactively (synchronously)
  2434. b deliver in background (asynchronously)
  2435. q queue only (don't deliver)
  2436. d defer delvery attempts (don't deliver)
  2437. .)b
  2438. There are tradeoffs.
  2439. Mode
  2440. .q i
  2441. gives the sender the quickest feedback,
  2442. but may slow down some mailers and
  2443. is hardly ever necessary.
  2444. Mode
  2445. .q b
  2446. delivers promptly but
  2447. can cause large numbers of processes
  2448. if you have a mailer that takes a long time to deliver a message.
  2449. Mode
  2450. .q q
  2451. minimizes the load on your machine,
  2452. but means that delivery may be delayed for up to the queue interval.
  2453. Mode
  2454. .q d
  2455. is identical to mode
  2456. .q q
  2457. except that it also prevents all the early map lookups from working;
  2458. it is intended for ``dial on demand'' sites where DNS lookups
  2459. might cost real money.
  2460. Some simple error messages
  2461. (e.g., host unknown during the SMTP protocol)
  2462. will be delayed using this mode.
  2463. Mode
  2464. .q b
  2465. is the usual default.
  2466. .pp
  2467. If you run in mode
  2468. .q q
  2469. (queue only),
  2470. .q d
  2471. (defer),
  2472. or
  2473. .q b
  2474. (deliver in background)
  2475. .i sendmail
  2476. will not expand aliases and follow .forward files
  2477. upon initial receipt of the mail.
  2478. This speeds up the response to RCPT commands.
  2479. Mode
  2480. .q i
  2481. cannot be used by the SMTP server.
  2482. .sh 2 "Log Level"
  2483. .pp
  2484. The level of logging can be set for
  2485. .i sendmail .
  2486. The default using a standard configuration table is level 9.
  2487. The levels are as follows:
  2488. .nr ii 0.5i
  2489. .ip 0
  2490. Minimal logging.
  2491. .ip 1
  2492. Serious system failures and potential security problems.
  2493. .ip 2
  2494. Lost communications (network problems) and protocol failures.
  2495. .ip 3
  2496. Other serious failures, malformed addresses, transient forward/include
  2497. errors, connection timeouts.
  2498. .ip 4
  2499. Minor failures, out of date alias databases, connection rejections
  2500. via check_ rulesets.
  2501. .ip 5
  2502. Message collection statistics.
  2503. .ip 6
  2504. Creation of error messages,
  2505. VRFY and EXPN commands.
  2506. .ip 7
  2507. Delivery failures (host or user unknown, etc.).
  2508. .ip 8
  2509. Successful deliveries and alias database rebuilds.
  2510. .ip 9
  2511. Messages being deferred
  2512. (due to a host being down, etc.).
  2513. .ip 10
  2514. Database expansion (alias, forward, and userdb lookups).
  2515. .ip 11
  2516. NIS errors and end of job processing.
  2517. .ip 12
  2518. Logs all SMTP connections.
  2519. .ip 13
  2520. Log bad user shells, files with improper permissions, and other
  2521. questionable situations.
  2522. .ip 14
  2523. Logs refused connections.
  2524. .ip 15
  2525. Log all incoming and outgoing SMTP commands.
  2526. .ip 20
  2527. Logs attempts to run locked queue files.
  2528. These are not errors,
  2529. but can be useful to note if your queue appears to be clogged.
  2530. .ip 30
  2531. Lost locks (only if using lockf instead of flock).
  2532. .lp
  2533. Additionally,
  2534. values above 64 are reserved for extremely verbose debugging output.
  2535. No normal site would ever set these.
  2536. .sh 2 "File Modes"
  2537. .pp
  2538. The modes used for files depend on what functionality you want
  2539. and the level of security you require.
  2540. In many cases
  2541. .i sendmail
  2542. does careful checking of the modes
  2543. of files and directories
  2544. to avoid accidental compromise;
  2545. if you want to make it possible to have group-writable support files
  2546. you may need to use the
  2547. .b DontBlameSendmail
  2548. option to turn off some of these checks.
  2549. .sh 3 "To suid or not to suid?"
  2550. .pp
  2551. .i Sendmail
  2552. is normally installed
  2553. setuid to root.
  2554. At the point where it is about to
  2555. .i exec |(2)
  2556. a mailer,
  2557. it checks to see if the userid is zero (root);
  2558. if so,
  2559. it resets the userid and groupid to a default
  2560. (set by the
  2561. .b U=
  2562. equate in the mailer line;
  2563. if that is not set, the
  2564. .b DefaultUser
  2565. option is used).
  2566. This can be overridden
  2567. by setting the
  2568. .b S
  2569. flag to the mailer
  2570. for mailers that are trusted
  2571. and must be called as root.
  2572. However,
  2573. this will cause mail processing
  2574. to be accounted
  2575. (using
  2576. .i sa |(8))
  2577. to root
  2578. rather than to the user sending the mail.
  2579. .pp
  2580. If you don't make
  2581. .i sendmail
  2582. setuid to root, it will still run but you lose a lot of functionality
  2583. and a lot of privacy, since you'll have to make the queue directory
  2584. world readable.
  2585. You could also make
  2586. .i sendmail
  2587. setuid to some pseudo-user
  2588. (e.g., create a user called
  2589. .q sendmail
  2590. and make
  2591. .i sendmail
  2592. setuid to that)
  2593. which will fix the privacy problems
  2594. but not the functionality issues.
  2595. Also, this isn't a guarantee of security:
  2596. for example,
  2597. root occasionally sends mail,
  2598. and the daemon often runs as root.
  2599. Note however that
  2600. .i sendmail
  2601. must run as root or the trusted user in order to create the SMTP listener
  2602. socket.
  2603. .pp
  2604. A middle ground is to make
  2605. .i sendmail
  2606. setuid to root,
  2607. but set the
  2608. .b RunAsUser
  2609. option.
  2610. This causes
  2611. .i sendmail
  2612. to become the indicated user as soon as it has done the startup
  2613. that requires root privileges
  2614. (primarily, opening the
  2615. .sm SMTP
  2616. socket).
  2617. If you use
  2618. .b RunAsUser ,
  2619. the queue directory
  2620. (normally
  2621. .i /var/spool/mqueue )
  2622. should be owned by that user,
  2623. and all files and databases
  2624. (including user
  2625. .i &.forward
  2626. files,
  2627. alias files,
  2628. :include: files,
  2629. and external databases)
  2630. must be readable by that user.
  2631. Also, since sendmail will not be able to change it's uid,
  2632. delivery to programs or files will be marked as unsafe, 
  2633. e.g., undeliverable,
  2634. in
  2635. .i &.forward ,
  2636. aliases,
  2637. and :include: files.
  2638. Administrators can override this by setting the
  2639. .b DontBlameSendmail
  2640. option to the setting
  2641. .b NonRootSafeAddr .
  2642. .b RunAsUser
  2643. is probably best suited for firewall configurations
  2644. that don't have regular user logins.
  2645. .sh 3 "Turning off security checks"
  2646. .pp
  2647. .i Sendmail
  2648. is very particular about the modes of files that it reads or writes.
  2649. For example, by default it will refuse to read most files
  2650. that are group writable
  2651. on the grounds that they might have been tampered with
  2652. by someone other than the owner;
  2653. it will even refuse to read files in group writable directories.
  2654. .pp
  2655. If you are
  2656. .i quite
  2657. sure that your configuration is safe and you want
  2658. .i sendmail
  2659. to avoid these security checks,
  2660. you can turn off certain checks using the
  2661. .b DontBlameSendmail
  2662. option.
  2663. This option takes one or more names that disable checks.
  2664. In the descriptions that follow,
  2665. .q "unsafe directory"
  2666. means a directory that is writable by anyone other than the owner.
  2667. The values are:
  2668. .nr ii 0.5i
  2669. .ip Safe
  2670. No special handling.
  2671. .ip AssumeSafeChown
  2672. Assume that the
  2673. .i chown
  2674. system call is restricted to root.
  2675. Since some versions of Unix permit regular users
  2676. to give away their files to other users on some filesystems,
  2677. .i sendmail
  2678. often cannot assume that a given file was created by the owner,
  2679. particularly when it is in a writable directory.
  2680. You can set this flag if you know that file giveaway is restricted
  2681. on your system.
  2682. .ip ClassFileInUnsafeDirPath
  2683. When reading class files (using the
  2684. .b F
  2685. line in the configuration file),
  2686. allow files that are in unsafe directories.
  2687. .ip DontWarnForwardFileInUnsafeDirPath
  2688. Prevent logging of
  2689. unsafe directory path warnings
  2690. for non-existent forward files.
  2691. .ip ErrorHeaderInUnsafeDirPath
  2692. Allow the file named in the
  2693. .b ErrorHeader
  2694. option to be in an unsafe directory.
  2695. .ip GroupWritableDirPathSafe
  2696. Change the definition of
  2697. .q "unsafe directory"
  2698. to consider group-writable directories to be safe.
  2699. World-writable directories are always unsafe.
  2700. .ip GroupWritableForwardFileSafe
  2701. Accept group-writable
  2702. .i &.forward
  2703. files.
  2704. .ip GroupWritableIncludeFileSafe
  2705. Accept group-writable
  2706. .i :include:
  2707. files.
  2708. .ip GroupWritableAliasFile
  2709. Allow group-writable alias files.
  2710. .ip HelpFileInUnsafeDirPath
  2711. Allow the file named in the
  2712. .b HelpFile
  2713. option to be in an unsafe directory.
  2714. .ip WorldWritableAliasFile
  2715. Accept world-writable alias files.
  2716. .ip ForwardFileInGroupWritableDirPath
  2717. Allow
  2718. .i &.forward
  2719. files in group writable directories.
  2720. .ip IncludeFileInGroupWritableDirPath
  2721. Allow
  2722. .i :include:
  2723. files in group writable directories.
  2724. .ip ForwardFileInUnsafeDirPath
  2725. Allow
  2726. .i &.forward
  2727. files in unsafe directories.
  2728. .ip IncludeFileInUnsafeDirPath
  2729. Allow
  2730. .i :include:
  2731. files in unsafe directories.
  2732. .ip ForwardFileInUnsafeDirPathSafe
  2733. Allow a
  2734. .i &.forward
  2735. file that is in an unsafe directory to include references
  2736. to program and files.
  2737. .ip IncludeFileInUnsafeDirPathSafe
  2738. Allow a
  2739. .i :include:
  2740. file that is in an unsafe directory to include references
  2741. to program and files.
  2742. .ip MapInUnsafeDirPath
  2743. Allow maps (e.g.,
  2744. .i hash ,
  2745. .i btree ,
  2746. and
  2747. .i dbm
  2748. files)
  2749. in unsafe directories.
  2750. .ip LinkedAliasFileInWritableDir
  2751. Allow an alias file that is a link in a writable directory.
  2752. .ip LinkedClassFileInWritableDir
  2753. Allow class files that are links in writable directories.
  2754. .ip LinkedForwardFileInWritableDir
  2755. Allow
  2756. .i &.forward
  2757. files that are links in writable directories.
  2758. .ip LinkedIncludeFileInWritableDir
  2759. Allow
  2760. .i :include:
  2761. files that are links in writable directories.
  2762. .ip LinkedMapInWritableDir
  2763. Allow map files that are links in writable directories.
  2764. .ip LinkedServiceSwitchFileInWritableDir
  2765. Allow the service switch file to be a link
  2766. even if the directory is writable.
  2767. .ip FileDeliveryToHardLink
  2768. Allow delivery to files that are hard links.
  2769. .ip FileDeliveryToSymLink
  2770. Allow delivery to files that are symbolic links.
  2771. .ip RunProgramInUnsafeDirPath
  2772. Go ahead and run programs that are in writable directories.
  2773. .ip RunWritableProgram
  2774. Go ahead and run programs that are group- or world-writable.
  2775. .ip WriteMapToHardLink
  2776. Allow writes to maps that are hard links.
  2777. .ip WriteMapToSymLink
  2778. Allow writes to maps that are symbolic links.
  2779. .ip WriteStatsToHardLink
  2780. Allow the status file to be a hard link.
  2781. .ip WriteStatsToSymLink
  2782. Allow the status file to be a symbolic link.
  2783. .ip TrustStickyBit
  2784. Allow group or world writable directories
  2785. if the sticky bit is set on the directory.
  2786. Do not set this on systems which do not honor
  2787. the sticky bit on directories.
  2788. .ip NonRootSafeAddr
  2789. Do not mark file and program deliveries as unsafe
  2790. if sendmail is not running with root privileges.
  2791. .sh 2 "Connection Caching"
  2792. .pp
  2793. When processing the queue,
  2794. .i sendmail
  2795. will try to keep the last few open connections open
  2796. to avoid startup and shutdown costs.
  2797. This only applies to IPC connections.
  2798. .pp
  2799. When trying to open a connection
  2800. the cache is first searched.
  2801. If an open connection is found, it is probed to see if it is still active
  2802. by sending a
  2803. .sm RSET
  2804. command.
  2805. It is not an error if this fails;
  2806. instead, the connection is closed and reopened.
  2807. .pp
  2808. Two parameters control the connection cache.
  2809. The
  2810. .b ConnectionCacheSize
  2811. (c
  2812. .b k )
  2813. option defines the number of simultaneous open connections
  2814. that will be permitted.
  2815. If it is set to zero,
  2816. connections will be closed as quickly as possible.
  2817. The default is one.
  2818. This should be set as appropriate for your system size;
  2819. it will limit the amount of system resources that
  2820. .i sendmail
  2821. will use during queue runs.
  2822. Never set this higher than 4.
  2823. .pp
  2824. The
  2825. .b ConnectionCacheTimeout
  2826. (c
  2827. .b K )
  2828. option specifies the maximum time that any cached connection
  2829. will be permitted to idle.
  2830. When the idle time exceeds this value
  2831. the connection is closed.
  2832. This number should be small
  2833. (under ten minutes)
  2834. to prevent you from grabbing too many resources
  2835. from other hosts.
  2836. The default is five minutes.
  2837. .sh 2 "Name Server Access"
  2838. .pp
  2839. Control of host address lookups is set by the
  2840. .b hosts
  2841. service entry in your service switch file.
  2842. If you are on a system that has built-in service switch support
  2843. (e.g., Ultrix, Solaris, or DEC OSF/1)
  2844. then your system is probably configured properly already.
  2845. Otherwise,
  2846. .i sendmail
  2847. will consult the file
  2848. .b /etc/mail/service.switch ,
  2849. which should be created.
  2850. .i Sendmail
  2851. only uses two entries:
  2852. .b hosts
  2853. and
  2854. .b aliases ,
  2855. although system routines may use other services
  2856. (notably the
  2857. .b passwd
  2858. service for user name lookups by
  2859. .i getpwname ).
  2860. .pp
  2861. However, some systems (such as SunOS 4.X)
  2862. will do DNS lookups
  2863. regardless of the setting of the service switch entry.
  2864. In particular, the system routine
  2865. .i gethostbyname (3)
  2866. is used to look up host names,
  2867. and many vendor versions try some combination of DNS, NIS,
  2868. and file lookup in /etc/hosts
  2869. without consulting a service switch.
  2870. .i Sendmail
  2871. makes no attempt to work around this problem,
  2872. and the DNS lookup will be done anyway.
  2873. If you do not have a nameserver configured at all,
  2874. such as at a UUCP-only site,
  2875. .i sendmail
  2876. will get a
  2877. .q "connection refused"
  2878. message when it tries to connect to the name server.
  2879. If the
  2880. .b hosts
  2881. switch entry has the service
  2882. .q dns
  2883. listed somewhere in the list,
  2884. .i sendmail
  2885. will interpret this to mean a temporary failure
  2886. and will queue the mail for later processing;
  2887. otherwise, it ignores the name server data.
  2888. .pp
  2889. The same technique is used to decide whether to do MX lookups.
  2890. If you want MX support, you
  2891. .i must
  2892. have
  2893. .q dns
  2894. listed as a service in the
  2895. .b hosts
  2896. switch entry.
  2897. .pp
  2898. The
  2899. .b ResolverOptions
  2900. (c
  2901. .b I )
  2902. option allows you to tweak name server options.
  2903. The command line takes a series of flags as documented in
  2904. .i resolver (3)
  2905. (with the leading
  2906. .q RES_
  2907. deleted).
  2908. Each can be preceded by an optional `+' or `(mi'.
  2909. For example, the line
  2910. .(b
  2911. O ResolverOptions=+AAONLY (miDNSRCH
  2912. .)b
  2913. turns on the AAONLY (accept authoritative answers only)
  2914. and turns off the DNSRCH (search the domain path) options.
  2915. Most resolver libraries default DNSRCH, DEFNAMES, and RECURSE
  2916. flags on and all others off.
  2917. You can also include
  2918. .q HasWildcardMX
  2919. to specify that there is a wildcard MX record matching your domain;
  2920. this turns off MX matching when canonifying names,
  2921. which can lead to inappropriate canonifications.
  2922. .pp
  2923. Version level 1 configurations
  2924. turn DNSRCH and DEFNAMES off when doing delivery lookups,
  2925. but leave them on everywhere else.
  2926. Version 8 of
  2927. .i sendmail
  2928. ignores them when doing canonification lookups
  2929. (that is, when using $[ ... $]),
  2930. and always does the search.
  2931. If you don't want to do automatic name extension,
  2932. don't call $[ ... $].
  2933. .pp
  2934. The search rules for $[ ... $] are somewhat different than usual.
  2935. If the name being looked up
  2936. has at least one dot, it always tries the unmodified name first.
  2937. If that fails, it tries the reduced search path,
  2938. and lastly tries the unmodified name
  2939. (but only for names without a dot,
  2940. since names with a dot have already been tried).
  2941. This allows names such as
  2942. ``utc.CS''
  2943. to match the site in Czechoslovakia
  2944. rather than the site in your local Computer Science department.
  2945. It also prefers A and CNAME records over MX records *-
  2946. that is, if it finds an MX record it makes note of it,
  2947. but keeps looking.
  2948. This way, if you have a wildcard MX record matching your domain,
  2949. it will not assume that all names match.
  2950. .pp
  2951. To completely turn off all name server access
  2952. on systems without service switch support
  2953. (such as SunOS 4.X)
  2954. you will have to recompile with
  2955. -DNAMED_BIND=0
  2956. and remove -lresolv from the list of libraries to be searched
  2957. when linking.
  2958. .sh 2 "Moving the Per-User Forward Files"
  2959. .pp
  2960. Some sites mount each user's home directory
  2961. from a local disk on their workstation,
  2962. so that local access is fast.
  2963. However, the result is that .forward file lookups are slow.
  2964. In some cases,
  2965. mail can even be delivered on machines inappropriately
  2966. because of a file server being down.
  2967. The performance can be especially bad if you run the automounter.
  2968. .pp
  2969. The
  2970. .b ForwardPath
  2971. (c
  2972. .b J )
  2973. option allows you to set a path of forward files.
  2974. For example, the config file line
  2975. .(b
  2976. O ForwardPath=/var/forward/$u:$z/.forward.$w
  2977. .)b
  2978. would first look for a file with the same name as the user's login
  2979. in /var/forward;
  2980. if that is not found (or is inaccessible)
  2981. the file
  2982. ``.forward.c
  2983. .i machinename ''
  2984. in the user's home directory is searched.
  2985. A truly perverse site could also search by sender
  2986. by using $r, $s, or $f.
  2987. .pp
  2988. If you create a directory such as /var/forward,
  2989. it should be mode 1777
  2990. (that is, the sticky bit should be set).
  2991. Users should create the files mode 644.
  2992. Note that you must use the
  2993. forwardfileinunsafedirpath and
  2994. forwardfileinunsafedirpathsafe
  2995. flags with the DontBlameSendmail option
  2996. to allow forward files in a world
  2997. writable directory.
  2998. This might also be used as a
  2999. denial of service
  3000. attack (users could create forward files for other users);
  3001. a better approach might be to create
  3002. /var/forward
  3003. mode 755
  3004. and create empty files for each user,
  3005. owned by that user,
  3006. mode 644.
  3007. If you do this, you don't have to set the DontBlameSendmail options
  3008. indicated above.
  3009. .sh 2 "Free Space"
  3010. .pp
  3011. On systems that have one of the system calls in the
  3012. .i statfs (2)
  3013. family
  3014. (including
  3015. .i statvfs
  3016. and
  3017. .i ustat ),
  3018. you can specify a minimum number of free blocks on the queue filesystem
  3019. using the
  3020. .b MinFreeBlocks
  3021. (c
  3022. .b b )
  3023. option.
  3024. If there are fewer than the indicated number of blocks free
  3025. on the filesystem on which the queue is mounted
  3026. the SMTP server will reject mail
  3027. with the
  3028. 452 error code.
  3029. This invites the SMTP client to try again later.
  3030. .pp
  3031. Beware of setting this option too high;
  3032. it can cause rejection of email
  3033. when that mail would be processed without difficulty.
  3034. .sh 2 "Maximum Message Size"
  3035. .pp
  3036. To avoid overflowing your system with a large message,
  3037. the
  3038. .b MaxMessageSize
  3039. option can be set to set an absolute limit
  3040. on the size of any one message.
  3041. This will be advertised in the ESMTP dialogue
  3042. and checked during message collection.
  3043. .sh 2 "Privacy Flags"
  3044. .pp
  3045. The
  3046. .b PrivacyOptions
  3047. (c
  3048. .b p )
  3049. option allows you to set certain
  3050. ``privacy''
  3051. flags.
  3052. Actually, many of them don't give you any extra privacy,
  3053. rather just insisting that client SMTP servers
  3054. use the HELO command
  3055. before using certain commands
  3056. or adding extra headers to indicate possible spoof attempts.
  3057. .pp
  3058. The option takes a series of flag names;
  3059. the final privacy is the inclusive or of those flags.
  3060. For example:
  3061. .(b
  3062. O PrivacyOptions=needmailhelo, noexpn
  3063. .)b
  3064. insists that the HELO or EHLO command be used before a MAIL command is accepted
  3065. and disables the EXPN command.
  3066. .pp
  3067. The flags are detailed in section
  3068. ."XREF
  3069. 5.6.
  3070. .sh 2 "Send to Me Too"
  3071. .pp
  3072. Beginning with version 8.10,
  3073. .i sendmail
  3074. includes by default the (envelope) sender in any list expansions.
  3075. For example, if
  3076. .q matt
  3077. sends to a list that contains
  3078. .q matt
  3079. as one of the members he will get a copy of the message.
  3080. If the
  3081. .b MeToo
  3082. option is set to
  3083. .sm FALSE
  3084. (in the configuration file or via the command line),
  3085. this behavior is changed, i.e.,
  3086. the (envelope) sender is excluded in list expansions.
  3087. .sh 1 "THE WHOLE SCOOP ON THE CONFIGURATION FILE"
  3088. .pp
  3089. This section describes the configuration file
  3090. in detail.
  3091. .pp
  3092. There is one point that should be made clear immediately:
  3093. the syntax of the configuration file
  3094. is designed to be reasonably easy to parse,
  3095. since this is done every time
  3096. .i sendmail
  3097. starts up,
  3098. rather than easy for a human to read or write.
  3099. On the
  3100. .q "future project"
  3101. list is a
  3102. configuration-file compiler.
  3103. .pp
  3104. The configuration file is organized as a series of lines,
  3105. each of which begins with a single character
  3106. defining the semantics for the rest of the line.
  3107. Lines beginning with a space or a tab
  3108. are continuation lines
  3109. (although the semantics are not well defined in many places).
  3110. Blank lines and lines beginning with a sharp symbol
  3111. (`#')
  3112. are comments.
  3113. .sh 2 "R and S *- Rewriting Rules"
  3114. .pp
  3115. The core of address parsing
  3116. are the rewriting rules.
  3117. These are an ordered production system.
  3118. .i Sendmail
  3119. scans through the set of rewriting rules
  3120. looking for a match on the left hand side
  3121. (LHS)
  3122. of the rule.
  3123. When a rule matches,
  3124. the address is replaced by the right hand side
  3125. (RHS)
  3126. of the rule.
  3127. .pp
  3128. There are several sets of rewriting rules.
  3129. Some of the rewriting sets are used internally
  3130. and must have specific semantics.
  3131. Other rewriting sets
  3132. do not have specifically assigned semantics,
  3133. and may be referenced by the mailer definitions
  3134. or by other rewriting sets.
  3135. .pp
  3136. The syntax of these two commands are:
  3137. .(b F
  3138. .b S c
  3139. .i n
  3140. .)b
  3141. Sets the current ruleset being collected to
  3142. .i n .
  3143. If you begin a ruleset more than once
  3144. it appends to the old definition.
  3145. .(b F
  3146. .b R c
  3147. .i lhs
  3148. .i rhs
  3149. .i comments
  3150. .)b
  3151. The
  3152. fields must be separated
  3153. by at least one tab character;
  3154. there may be embedded spaces
  3155. in the fields.
  3156. The
  3157. .i lhs
  3158. is a pattern that is applied to the input.
  3159. If it matches,
  3160. the input is rewritten to the
  3161. .i rhs .
  3162. The
  3163. .i comments
  3164. are ignored.
  3165. .pp
  3166. Macro expansions of the form
  3167. .b $ c
  3168. .i x
  3169. are performed when the configuration file is read.
  3170. Expansions of the form
  3171. .b $& c
  3172. .i x
  3173. are performed at run time using a somewhat less general algorithm.
  3174. This is intended only for referencing internally defined macros
  3175. such as
  3176. .b $h
  3177. that are changed at runtime.
  3178. .sh 3 "The left hand side"
  3179. .pp
  3180. The left hand side of rewriting rules contains a pattern.
  3181. Normal words are simply matched directly.
  3182. Metasyntax is introduced using a dollar sign.
  3183. The metasymbols are:
  3184. .(b
  3185. .ta w'fB$=fPfIxfP  'u
  3186. fB$*fP Match zero or more tokens
  3187. fB$+fP Match one or more tokens
  3188. fB$-fP Match exactly one token
  3189. fB$=fPfIxfP Match any phrase in class fIxfP
  3190. fB$~fPfIxfP Match any word not in class fIxfP
  3191. .)b
  3192. If any of these match,
  3193. they are assigned to the symbol
  3194. .b $ c
  3195. .i n
  3196. for replacement on the right hand side,
  3197. where
  3198. .i n
  3199. is the index in the LHS.
  3200. For example,
  3201. if the LHS:
  3202. .(b
  3203. $-:$+
  3204. .)b
  3205. is applied to the input:
  3206. .(b
  3207. UCBARPA:eric
  3208. .)b
  3209. the rule will match, and the values passed to the RHS will be:
  3210. .(b
  3211. .ta 4n
  3212. $1 UCBARPA
  3213. $2 eric
  3214. .)b
  3215. .pp
  3216. Additionally, the LHS can include
  3217. .b $@
  3218. to match zero tokens.
  3219. This is
  3220. .i not
  3221. bound to a
  3222. .b $ c
  3223. .i n
  3224. on the RHS, and is normally only used when it stands alone
  3225. in order to match the null input.
  3226. .sh 3 "The right hand side"
  3227. .pp
  3228. When the left hand side of a rewriting rule matches,
  3229. the input is deleted and replaced by the right hand side.
  3230. Tokens are copied directly from the RHS
  3231. unless they begin with a dollar sign.
  3232. Metasymbols are:
  3233. .(b
  3234. .ta w'$#mailer'u
  3235. fB$fPfInfP Substitute indefinite token fInfP from LHS
  3236. fB$[fPfInamefPfB$]fP Canonicalize fInamefP
  3237. fB$(fPfImap keyfP fB$@fPfIargumentsfP fB$:fPfIdefaultfP fB$)fP
  3238. Generalized keyed mapping function
  3239. fB$>fPfInfP *(lqCall*(rq ruleset fInfP
  3240. fB$#fPfImailerfP Resolve to fImailerfP
  3241. fB$@fPfIhostfP Specify fIhostfP
  3242. fB$:fPfIuserfP Specify fIuserfP
  3243. .)b
  3244. .pp
  3245. The
  3246. .b $ c
  3247. .i n
  3248. syntax substitutes the corresponding value from a
  3249. .b $+ ,
  3250. .b $- ,
  3251. .b $* ,
  3252. .b $= ,
  3253. or
  3254. .b $~
  3255. match on the LHS.
  3256. It may be used anywhere.
  3257. .pp
  3258. A host name enclosed between
  3259. .b $[
  3260. and
  3261. .b $]
  3262. is looked up in the host database(s)
  3263. and replaced by the canonical name**.
  3264. .(f
  3265. **This is actually
  3266. completely equivalent
  3267. to $(host fIhostnamefP$).
  3268. In particular, a
  3269. .b $:
  3270. default can be used.
  3271. .)f
  3272. For example,
  3273. .q $[ftp$]
  3274. might become
  3275. .q ftp.CS.Berkeley.EDU
  3276. and
  3277. .q $[[128.32.130.2]$]
  3278. would become
  3279. .q vangogh.CS.Berkeley.EDU.
  3280. .i Sendmail
  3281. recognizes its numeric IP address
  3282. without calling the name server
  3283. and replaces it with its canonical name.
  3284. .pp
  3285. The
  3286. .b $(
  3287. &...
  3288. .b $)
  3289. syntax is a more general form of lookup;
  3290. it uses a named map instead of an implicit map.
  3291. If no lookup is found, the indicated
  3292. .i default
  3293. is inserted;
  3294. if no default is specified and no lookup matches,
  3295. the value is left unchanged.
  3296. The
  3297. .i arguments
  3298. are passed to the map for possible use.
  3299. .pp
  3300. The
  3301. .b $> c
  3302. .i n
  3303. syntax
  3304. causes the remainder of the line to be substituted as usual
  3305. and then passed as the argument to ruleset
  3306. .i n .
  3307. The final value of ruleset
  3308. .i n
  3309. then becomes
  3310. the substitution for this rule.
  3311. The
  3312. .b $>
  3313. syntax expands everything after the ruleset name
  3314. to the end of the replacement string
  3315. and then passes that as the initial input to the ruleset.
  3316. Recursive calls are allowed.
  3317. For example,
  3318. .(b
  3319. $>0 $>3 $1
  3320. .)b
  3321. expands $1, passes that to ruleset 3, and then passes the result
  3322. of ruleset 3 to ruleset 0.
  3323. .pp
  3324. The
  3325. .b $#
  3326. syntax should
  3327. .i only
  3328. be used in ruleset zero
  3329. or a subroutine of ruleset zero.
  3330. It causes evaluation of the ruleset to terminate immediately,
  3331. and signals to
  3332. .i sendmail
  3333. that the address has completely resolved.
  3334. The complete syntax is:
  3335. .(b
  3336. fB$#fPfImailerfP fB$@fPfIhostfP fB$:fPfIuserfP
  3337. .)b
  3338. This specifies the
  3339. {mailer, host, user}
  3340. 3-tuple necessary to direct the mailer.
  3341. If the mailer is local
  3342. the host part may be omitted**.
  3343. .(f
  3344. **You may want to use it for special
  3345. .q "per user"
  3346. extensions.
  3347. For example, in the address
  3348. .q jgm+foo@CMU.EDU ;
  3349. the
  3350. .q +foo
  3351. part is not part of the user name,
  3352. and is passed to the local mailer for local use.
  3353. .)f
  3354. The
  3355. .i mailer
  3356. must be a single word,
  3357. but the
  3358. .i host
  3359. and
  3360. .i user
  3361. may be multi-part.
  3362. If the
  3363. .i mailer
  3364. is the builtin IPC mailer,
  3365. the
  3366. .i host
  3367. may be a colon-separated list of hosts
  3368. that are searched in order for the first working address
  3369. (exactly like MX records).
  3370. The
  3371. .i user
  3372. is later rewritten by the mailer-specific envelope rewriting set
  3373. and assigned to the
  3374. .b $u
  3375. macro.
  3376. As a special case, if the mailer specified has the
  3377. .b F=@
  3378. flag specified
  3379. and the first character of the
  3380. .b $:
  3381. value is
  3382. .q @ ,
  3383. the
  3384. .q @
  3385. is stripped off, and a flag is set in the address descriptor
  3386. that causes sendmail to not do ruleset 5 processing.
  3387. .pp
  3388. Normally, a rule that matches is retried,
  3389. that is,
  3390. the rule loops until it fails.
  3391. A RHS may also be preceded by a
  3392. .b $@
  3393. or a
  3394. .b $:
  3395. to change this behavior.
  3396. A
  3397. .b $@
  3398. prefix causes the ruleset to return with the remainder of the RHS
  3399. as the value.
  3400. A
  3401. .b $:
  3402. prefix causes the rule to terminate immediately,
  3403. but the ruleset to continue;
  3404. this can be used to avoid continued application of a rule.
  3405. The prefix is stripped before continuing.
  3406. .pp
  3407. The
  3408. .b $@
  3409. and
  3410. .b $:
  3411. prefixes may precede a
  3412. .b $>
  3413. spec;
  3414. for example:
  3415. .(b
  3416. .ta 8n
  3417. R$+ $: $>7 $1
  3418. .)b
  3419. matches anything,
  3420. passes that to ruleset seven,
  3421. and continues;
  3422. the
  3423. .b $:
  3424. is necessary to avoid an infinite loop.
  3425. .pp
  3426. Substitution occurs in the order described,
  3427. that is,
  3428. parameters from the LHS are substituted,
  3429. hostnames are canonicalized,
  3430. .q subroutines
  3431. are called,
  3432. and finally
  3433. .b $# ,
  3434. .b $@ ,
  3435. and
  3436. .b $:
  3437. are processed.
  3438. .sh 3 "Semantics of rewriting rule sets"
  3439. .pp
  3440. There are six rewriting sets
  3441. that have specific semantics.
  3442. Five of these are related as depicted by figure 1.
  3443. .(z
  3444. .hl
  3445. .ie n {
  3446. .(c
  3447.                     +---+
  3448.                  -->| 0 |-->resolved address
  3449.                 /   +---+
  3450.                /            +---+   +---+
  3451.               /        ---->| 1 |-->| S |--
  3452.        +---+ / +---+  /     +---+   +---+  e    +---+
  3453. addr-->| 3 |-->| D |--                      --->| 4 |-->msg
  3454.        +---+   +---+  e     +---+   +---+  /    +---+
  3455.                         --->| 2 |-->| R |--
  3456.                             +---+   +---+
  3457. .)c
  3458. .}
  3459. .el .ie !"*(.T"" 
  3460. {
  3461. .PS
  3462. boxwid = 0.3i
  3463. boxht = 0.3i
  3464. movewid = 0.3i
  3465. moveht = 0.3i
  3466. linewid = 0.3i
  3467. lineht = 0.3i
  3468. box invis "addr"; arrow
  3469. Box3: box "3"
  3470. A1: arrow
  3471. BoxD: box "D"; line; L1: Here
  3472. C: [
  3473. C1: arrow; box "1"; arrow; box "S"; line; E1: Here
  3474. move to C1 down 0.5; right
  3475. C2: arrow; box "2"; arrow; box "R"; line; E2: Here
  3476. ] with .w at L1 + (0.5, 0)
  3477. move to C.e right 0.5
  3478. L4: arrow; box "4"; arrow; box invis "msg"
  3479. line from L1 to C.C1
  3480. line from L1 to C.C2
  3481. line from C.E1 to L4
  3482. line from C.E2 to L4
  3483. move to BoxD.n up 0.6; right
  3484. Box0: arrow; box "0"
  3485. arrow; box invis "resolved address" width 1.3
  3486. line from 1/3 of the way between A1 and BoxD.w to Box0
  3487. .PE
  3488. .}
  3489. .el .sp 2i
  3490. .ce
  3491. Figure 1 *- Rewriting set semantics
  3492. .(c
  3493. D *- sender domain addition
  3494. S *- mailer-specific sender rewriting
  3495. R *- mailer-specific recipient rewriting
  3496. .)c
  3497. .hl
  3498. .)z
  3499. .pp
  3500. Ruleset three
  3501. should turn the address into
  3502. .q "canonical form."
  3503. This form should have the basic syntax:
  3504. .(b
  3505. local-part@host-domain-spec
  3506. .)b
  3507. Ruleset three
  3508. is applied by
  3509. .i sendmail
  3510. before doing anything with any address.
  3511. .pp
  3512. If no
  3513. .q @
  3514. sign is specified,
  3515. then the
  3516. host-domain-spec
  3517. .i may
  3518. be appended (box
  3519. .q D
  3520. in Figure 1)
  3521. from the
  3522. sender address
  3523. (if the
  3524. .b C
  3525. flag is set in the mailer definition
  3526. corresponding to the
  3527. .i sending
  3528. mailer).
  3529. .pp
  3530. Ruleset zero
  3531. is applied after ruleset three
  3532. to addresses that are going to actually specify recipients.
  3533. It must resolve to a
  3534. .i "{mailer, host, address}"
  3535. triple.
  3536. The
  3537. .i mailer
  3538. must be defined in the mailer definitions
  3539. from the configuration file.
  3540. The
  3541. .i host
  3542. is defined into the
  3543. .b $h
  3544. macro
  3545. for use in the argv expansion of the specified mailer.
  3546. .pp
  3547. Rulesets one and two
  3548. are applied to all sender and recipient addresses respectively.
  3549. They are applied before any specification
  3550. in the mailer definition.
  3551. They must never resolve.
  3552. .pp
  3553. Ruleset four is applied to all addresses
  3554. in the message.
  3555. It is typically used
  3556. to translate internal to external form.
  3557. .pp
  3558. In addition,
  3559. ruleset 5 is applied to all local addresses
  3560. (specifically, those that resolve to a mailer with the `F=5'
  3561. flag set)
  3562. that do not have aliases.
  3563. This allows a last minute hook for local names.
  3564. .sh 3 "Ruleset hooks"
  3565. .pp
  3566. A few extra rulesets are defined as
  3567. .q hooks
  3568. that can be defined to get special features.
  3569. They are all named rulesets.
  3570. The
  3571. .q check_*
  3572. forms all give accept/reject status;
  3573. falling off the end or returning normally is an accept,
  3574. and resolving to
  3575. .b $#error
  3576. is a reject.
  3577. Many of these can also resolve to the special mailer
  3578. .b $#discard ;
  3579. this accepts the message as though it were successful
  3580. but then discards it without delivery.
  3581. .sh 4 "check_relay"
  3582. .pp
  3583. The
  3584. .i check_relay
  3585. ruleset is called after a connection is accepted.
  3586. It is passed
  3587. .(b
  3588. client.host.name $| client.host.address
  3589. .)b
  3590. where
  3591. .b $|
  3592. is a metacharacter separating the two parts.
  3593. This ruleset can reject connections from various locations.
  3594. .sh 4 "check_mail"
  3595. .pp
  3596. The
  3597. .i check_mail
  3598. ruleset is passed the user name parameter of the
  3599. .sm "SMTP MAIL"
  3600. command.
  3601. It can accept or reject the address.
  3602. .sh 4 "check_rcpt"
  3603. .pp
  3604. The
  3605. .i check_rcpt
  3606. ruleset is passed the user name parameter of the
  3607. .sm "SMTP RCPT"
  3608. command.
  3609. It can accept or reject the address.
  3610. .sh 4 "check_compat"
  3611. .pp
  3612. The
  3613. .i check_compat
  3614. ruleset is passed
  3615. .(b
  3616. sender-address $| recipient-address
  3617. .)b
  3618. where
  3619. .b $|
  3620. is a metacharacter separating the addresses.
  3621. It can accept or reject mail transfer between these two addresses
  3622. much like the
  3623. .i checkcompat()
  3624. function.
  3625. .sh 4 "check_eoh"
  3626. .pp
  3627. The
  3628. .i check_eoh
  3629. ruleset is passed
  3630. .(b
  3631. number-of-headers $| size-of-headers
  3632. .)b
  3633. where
  3634. .b $|
  3635. is a metacharacter separating the numbers.
  3636. These numbers can be used for size comparisons with the
  3637. .b arith
  3638. map.
  3639. The ruleset is triggered after
  3640. all of the headers have been read.
  3641. It can be used to correlate information gathered
  3642. from those headers using the
  3643. .b macro
  3644. storage map.
  3645. One possible use is to check for a missing header.
  3646. For example:
  3647. .(b
  3648. .ta 1.5i
  3649. Kstorage macro
  3650. HMessage-Id: $>CheckMessageId
  3651. SCheckMessageId
  3652. # Record the presence of the header
  3653. R$* $: $(storage {MessageIdCheck} $@ OK $) $1
  3654. R< $+ @ $+ > $@ OK
  3655. R$* $#error $: 553 Header Error
  3656. Scheck_eoh
  3657. # Check the macro
  3658. R$* $: < $&{MessageIdCheck} >
  3659. # Clear the macro for the next message
  3660. R$* $: $(storage {MessageIdCheck} $) $1
  3661. # Has a Message-Id: header
  3662. R< $+ > $@ OK
  3663. # Allow missing Message-Id: from local mail
  3664. R$* $: < $&{client_name} >
  3665. R< > $@ OK
  3666. R< $=w > $@ OK
  3667. # Otherwise, reject the mail
  3668. R$* $#error $: 553 Header Error
  3669. .)b
  3670. Keep in mind the Message-Id: header is not a required header and
  3671. is not a guaranteed spam indicator.
  3672. This ruleset is an example and
  3673. should probably not be used in production.
  3674. .sh 4 "check_etrn"
  3675. .pp
  3676. The
  3677. .i check_etrn
  3678. ruleset is passed the parameter of the
  3679. .sm "SMTP ETRN"
  3680. command.
  3681. It can accept or reject the command.
  3682. .sh 4 "check_expn"
  3683. .pp
  3684. The
  3685. .i check_expn
  3686. ruleset is passed the user name parameter of the
  3687. .sm "SMTP EXPN"
  3688. command.
  3689. It can accept or reject the address.
  3690. .sh 4 "check_vrfy"
  3691. .pp
  3692. The
  3693. .i check_vrfy
  3694. ruleset is passed the user name parameter of the
  3695. .sm "SMTP VRFY"
  3696. command.
  3697. It can accept or reject the command.
  3698. .sh 4 "trust_auth"
  3699. .pp
  3700. The
  3701. .i trust_auth
  3702. ruleset is passed the AUTH= parameter of the
  3703. .sm "SMTP MAIL"
  3704. command.
  3705. It is used to determine whether this value should be
  3706. trusted. In order to make this decision, the ruleset
  3707. may make use of the various
  3708. .b ${auth_*}
  3709. macros.
  3710. If the ruleset does resolve to the
  3711. .q error
  3712. mailer the AUTH= parameter is not trusted and hence
  3713. not passed on to the next relay.
  3714. .sh 3 "IPC mailers"
  3715. .pp
  3716. Some special processing occurs
  3717. if the ruleset zero resolves to an IPC mailer
  3718. (that is, a mailer that has
  3719. .q [IPC]
  3720. listed as the Path in the
  3721. .b M
  3722. configuration line.
  3723. The host name passed after
  3724. .q $@
  3725. has MX expansion performed;
  3726. this looks the name up in DNS to find alternate delivery sites.
  3727. .pp
  3728. The host name can also be provided as a dotted quad in square brackets;
  3729. for example:
  3730. .(b
  3731. [128.32.149.78]
  3732. .)b
  3733. This causes direct conversion of the numeric value
  3734. to an IP host address.
  3735. .pp
  3736. The host name passed in after the
  3737. .q $@
  3738. may also be a colon-separated list of hosts.
  3739. Each is separately MX expanded and the results are concatenated
  3740. to make (essentially) one long MX list.
  3741. The intent here is to create
  3742. .q fake
  3743. MX records that are not published in DNS
  3744. for private internal networks.
  3745. .pp
  3746. As a final special case, the host name can be passed in
  3747. as a text string
  3748. in square brackets:
  3749. .(b
  3750. [ucbvax.berkeley.edu]
  3751. .)b
  3752. This form avoids the MX mapping.
  3753. .b N.B.:
  3754. .i
  3755. This is intended only for situations where you have a network firewall
  3756. or other host that will do special processing for all your mail,
  3757. so that your MX record points to a gateway machine;
  3758. this machine could then do direct delivery to machines
  3759. within your local domain.
  3760. Use of this feature directly violates RFC 1123 section 5.3.5:
  3761. it should not be used lightly.
  3762. .r
  3763. .sh 2 "D *- Define Macro"
  3764. .pp
  3765. Macros are named with a single character
  3766. or with a word in {braces}.
  3767. Single character names may be selected from the entire ASCII set,
  3768. but user-defined macros
  3769. should be selected from the set of upper case letters only.
  3770. Lower case letters
  3771. and special symbols
  3772. are used internally.
  3773. Long names beginning with a lower case letter or a punctuation character
  3774. are reserved for use by sendmail,
  3775. so user-defined long macro names should begin with an upper case letter.
  3776. .pp
  3777. The syntax for macro definitions is:
  3778. .(b F
  3779. .b D c
  3780. .i x|val
  3781. .)b
  3782. where
  3783. .i x
  3784. is the name of the macro
  3785. (which may be a single character
  3786. or a word in braces)
  3787. and
  3788. .i val
  3789. is the value it should have.
  3790. There should be no spaces given
  3791. that do not actually belong in the macro value.
  3792. .pp
  3793. Macros are interpolated
  3794. using the construct
  3795. .b $ c
  3796. .i x ,
  3797. where
  3798. .i x
  3799. is the name of the macro to be interpolated.
  3800. This interpolation is done when the configuration file is read,
  3801. except in
  3802. .b M
  3803. lines.
  3804. The special construct
  3805. .b $& c
  3806. .i x
  3807. can be used in
  3808. .b R
  3809. lines to get deferred interpolation.
  3810. .pp
  3811. Conditionals can be specified using the syntax:
  3812. .(b
  3813. $?x text1 $| text2 $.
  3814. .)b
  3815. This interpolates
  3816. .i text1
  3817. if the macro
  3818. .b $x
  3819. is set and non-null,
  3820. and
  3821. .i text2
  3822. otherwise.
  3823. The
  3824. .q else
  3825. (c
  3826. .b $| )
  3827. clause may be omitted.
  3828. .pp
  3829. Lower case macro names are reserved to have
  3830. special semantics,
  3831. used to pass information in or out of
  3832. .i sendmail ,
  3833. and special characters are reserved to
  3834. provide conditionals, etc.
  3835. Upper case names
  3836. (that is,
  3837. .b $A
  3838. through
  3839. .b $Z )
  3840. are specifically reserved for configuration file authors.
  3841. .pp
  3842. The following macros are defined and/or used internally by
  3843. .i sendmail
  3844. for interpolation into argv's for mailers
  3845. or for other contexts.
  3846. The ones marked (dg are information passed into sendmail**,
  3847. .(f
  3848. **As of version 8.6,
  3849. all of these macros have reasonable defaults.
  3850. Previous versions required that they be defined.
  3851. .)f
  3852. the ones marked (dd are information passed both in and out of sendmail,
  3853. and the unmarked macros are passed out of sendmail
  3854. but are not otherwise used internally.
  3855. These macros are:
  3856. .nr ii 5n
  3857. .ip $a
  3858. The origination date in RFC 822 format.
  3859. This is extracted from the Date: line.
  3860. .ip $b
  3861. The current date in RFC 822 format.
  3862. .ip $c
  3863. The hop count.
  3864. This is a count of the number of Received: lines
  3865. plus the value of the
  3866. .b -h
  3867. command line flag.
  3868. .ip $d
  3869. The current date in UNIX (ctime) format.
  3870. .ip $e(dg
  3871. (Obsolete; use SmtpGreetingMessage option instead.)
  3872. The SMTP entry message.
  3873. This is printed out when SMTP starts up.
  3874. The first word must be the
  3875. .b $j
  3876. macro as specified by RFC821.
  3877. Defaults to
  3878. .q "$j Sendmail $v ready at $b" .
  3879. Commonly redefined to include the configuration version number, e.g.,
  3880. .q "$j Sendmail $v/$Z ready at $b"
  3881. .ip $f
  3882. The envelope sender (from) address.
  3883. .ip $g
  3884. The sender address relative to the recipient.
  3885. For example, if
  3886. .b $f
  3887. is
  3888. .q foo ,
  3889. .b $g
  3890. will be
  3891. .q host!foo ,
  3892. .q foo@host.domain ,
  3893. or whatever is appropriate for the receiving mailer.
  3894. .ip $h
  3895. The recipient host.
  3896. This is set in ruleset 0 from the $@ field of a parsed address.
  3897. .ip $i
  3898. The queue id,
  3899. e.g.,
  3900. .q HAA12345 .
  3901. .ip $j(dd
  3902. The *(lqofficial*(rq domain name for this site.
  3903. This is fully qualified if the full qualification can be found.
  3904. It
  3905. .i must
  3906. be redefined to be the fully qualified domain name
  3907. if your system is not configured so that information can find
  3908. it automatically.
  3909. .ip $k
  3910. The UUCP node name (from the uname system call).
  3911. .ip $l(dg
  3912. (Obsolete; use UnixFromLine option instead.)
  3913. The format of the UNIX from line.
  3914. Unless you have changed the UNIX mailbox format,
  3915. you should not change the default,
  3916. which is
  3917. .q "From $g  $d" .
  3918. .ip $m
  3919. The domain part of the fIgethostnamefP return value.
  3920. Under normal circumstances,
  3921. .b $j
  3922. is equivalent to
  3923. .b $w.$m .
  3924. .ip $n(dg
  3925. The name of the daemon (for error messages).
  3926. Defaults to
  3927. .q MAILER-DAEMON .
  3928. .ip $o(dg
  3929. (Obsolete: use OperatorChars option instead.)
  3930. The set of *(lqoperators*(rq in addresses.
  3931. A list of characters
  3932. which will be considered tokens
  3933. and which will separate tokens
  3934. when doing parsing.
  3935. For example, if
  3936. .q @
  3937. were in the
  3938. .b $o
  3939. macro, then the input
  3940. .q a@b
  3941. would be scanned as three tokens:
  3942. .q a,
  3943. .q @,
  3944. and
  3945. .q b.
  3946. Defaults to
  3947. .q ".:@[]" ,
  3948. which is the minimum set necessary to do RFC 822 parsing;
  3949. a richer set of operators is
  3950. .q ".:%@!/[]" ,
  3951. which adds support for UUCP, the %-hack, and X.400 addresses.
  3952. .ip $p
  3953. Sendmail's process id.
  3954. .ip $q(dg
  3955. Default format of sender address.
  3956. The
  3957. .b $q
  3958. macro specifies how an address should appear in a message
  3959. when it is defaulted.
  3960. Defaults to
  3961. .q "<$g>" .
  3962. It is commonly redefined to be
  3963. .q "$?x$x <$g>$|$g$."
  3964. or
  3965. .q "$g$?x ($x)$." ,
  3966. corresponding to the following two formats:
  3967. .(b
  3968. Eric Allman <eric@CS.Berkeley.EDU>
  3969. eric@CS.Berkeley.EDU (Eric Allman)
  3970. .)b
  3971. .i Sendmail
  3972. properly quotes names that have special characters
  3973. if the first form is used.
  3974. .ip $r
  3975. Protocol used to receive the message.
  3976. Set from the
  3977. .b -p
  3978. command line flag or by the SMTP server code.
  3979. .ip $s
  3980. Sender's host name.
  3981. Set from the
  3982. .b -p
  3983. command line flag or by the SMTP server code.
  3984. .ip $t
  3985. A numeric representation of the current time.
  3986. .ip $u
  3987. The recipient user.
  3988. .ip $v
  3989. The version number of the
  3990. .i sendmail
  3991. binary.
  3992. .ip $w(dd
  3993. The hostname of this site.
  3994. This is the root name of this host (but see below for caveats).
  3995. .ip $x
  3996. The full name of the sender.
  3997. .ip $z
  3998. The home directory of the recipient.
  3999. .ip $_
  4000. The validated sender address.
  4001. .ip ${auth_authen}
  4002. The client's authentication credentials as determined by authentication
  4003. (only set if successful).
  4004. .ip ${auth_author}
  4005. The authorization identity, i.e. the AUTH= parameter of the
  4006. .sm "SMTP MAIL"
  4007. command if supplied.
  4008. .ip ${auth_type}
  4009. The mechanism used for authentication
  4010. (only set if successful).
  4011. .ip ${bodytype}
  4012. The message body type
  4013. (7BIT or 8BITMIME),
  4014. as determined from the envelope.
  4015. .ip ${client_addr}
  4016. The IP address of the SMTP client.
  4017. Defined in the SMTP server only.
  4018. .ip ${client_name}
  4019. The host name of the SMTP client.
  4020. This may be the client's bracketed IP address
  4021. in the form [ nnn.nnn.nnn.nnn ] if the client's
  4022. IP address is not resolvable, or if the resolved
  4023. name doesn't match ${client_name}.
  4024. Defined in the SMTP server only.
  4025. .ip ${client_port}
  4026. The port number of the SMTP client.
  4027. Defined in the SMTP server only.
  4028. .ip ${client_resolve}
  4029. Holds the result of the resolve call for
  4030. .b ${client_name}
  4031. : OK, FAIL, FORGED, TEMP.
  4032. Defined in the SMTP server only.
  4033. .ip ${currHeader}
  4034. Header value as quoted string
  4035. (possibly truncated to
  4036. .b MAXNAME ).
  4037. .ip ${daemon_addr}
  4038. The IP address the daemon is listening on for connections.
  4039. Unless
  4040. .b DaemonPortOptions
  4041. is set, this will be
  4042. .q 0.0.0.0 .
  4043. .ip ${daemon_family}
  4044. The network family
  4045. if the daemon is accepting network connections.
  4046. Possible values include
  4047. .q inet ,
  4048. .q inet6 ,
  4049. .q iso ,
  4050. .q ns ,
  4051. .q x.25
  4052. .ip ${daemon_flags}
  4053. The flags for the daemon as specified by the
  4054. Modifier= part of
  4055. .b DaemonPortOptions
  4056. whereby the flags are separated from each other by spaces,
  4057. and upper case flags are doubled.
  4058. That is,
  4059. Modifier=Ea
  4060. will be represented as
  4061. "EE a" in
  4062. .b ${daemon_flags} ,
  4063. which is required for testing the flags in rulesets.
  4064. .ip ${daemon_info}
  4065. Some information about a daemon as a text string.
  4066. For example,
  4067. .q SMTP+queueing@00:30:00 .
  4068. .ip ${daemon_name}
  4069. The name of the daemon from
  4070. .b DaemonPortOptions
  4071. Name= suboption.
  4072. If this suboption is not set,
  4073. "Daemon#",
  4074. where # is the daemon number,
  4075. is used.
  4076. .ip ${daemon_port}
  4077. The port the daemon is accepting connection on.
  4078. Unless
  4079. .b DaemonPortOptions
  4080. is set, this will most likely be
  4081. .q 25 .
  4082. .ip ${deliveryMode}
  4083. The current delivery mode sendmail is using.
  4084. It is initially set to the value of the
  4085. .b DeliveryMode
  4086. option.
  4087. .ip ${envid}
  4088. The envelope id passed to sendmail as part of the envelope.
  4089. .ip ${hdrlen}
  4090. The length of the header value which is stored in
  4091. ${currHeader} (before possible truncation).
  4092. If this value is greater than or equal
  4093. .b MAXNAME
  4094. the header has been truncated.
  4095. .ip ${hdr_name}
  4096. The name of the header field for which the current header
  4097. check ruleset has been called.
  4098. This is useful for a default header check ruleset to get
  4099. the name of the header.
  4100. .ip ${if_addr}
  4101. The IP address of the interface of an incoming connection
  4102. unless it is in the loopback net.
  4103. .ip ${if_name}
  4104. The name of the interface of an incoming connection.
  4105. This macro can be used for
  4106. SmtpGreetingMessage and HReceived for virtual hosting.
  4107. For example:
  4108. O SmtpGreetingMessage=$?{if_name}${if_name}$|$j$. Sendmail $v/$Z; $b
  4109. .ip ${mail_addr}
  4110. The address part of the resolved triple of the address given for the
  4111. .sm "SMTP MAIL"
  4112. command.
  4113. Defined in the SMTP server only.
  4114. .ip ${mail_host}
  4115. The host from the resolved triple of the address given for the
  4116. .sm "SMTP MAIL"
  4117. command.
  4118. Defined in the SMTP server only.
  4119. .ip ${mail_mailer}
  4120. The mailer from the resolved triple of the address given for the
  4121. .sm "SMTP MAIL"
  4122. command.
  4123. Defined in the SMTP server only.
  4124. .ip ${ntries}
  4125. The number of delivery attempts.
  4126. .ip ${opMode}
  4127. The current operation mode (from the
  4128. .b -b
  4129. flag).
  4130. .ip ${queue_interval}
  4131. The queue run interval given by the
  4132. .b -q
  4133. flag.
  4134. For example,
  4135. .b -q30m
  4136. would set
  4137. .b ${queue_interval}
  4138. to
  4139. .q 00:30:00 .
  4140. .ip ${rcpt_addr}
  4141. The address part of the resolved triple of the address given for the
  4142. .sm "SMTP RCPT"
  4143. command.
  4144. Defined in the SMTP server only.
  4145. .ip ${rcpt_host}
  4146. The host from the resolved triple of the address given for the
  4147. .sm "SMTP RCPT"
  4148. command.
  4149. Defined in the SMTP server only.
  4150. .ip ${rcpt_mailer}
  4151. The mailer from the resolved triple of the address given for the
  4152. .sm "SMTP RCPT"
  4153. command.
  4154. Defined in the SMTP server only.
  4155. .pp
  4156. There are three types of dates that can be used.
  4157. The
  4158. .b $a
  4159. and
  4160. .b $b
  4161. macros are in RFC 822 format;
  4162. .b $a
  4163. is the time as extracted from the
  4164. .q Date:
  4165. line of the message
  4166. (if there was one),
  4167. and
  4168. .b $b
  4169. is the current date and time
  4170. (used for postmarks).
  4171. If no
  4172. .q Date:
  4173. line is found in the incoming message,
  4174. .b $a
  4175. is set to the current time also.
  4176. The
  4177. .b $d
  4178. macro is equivalent to the
  4179. .b $b
  4180. macro in UNIX
  4181. (ctime)
  4182. format.
  4183. .pp
  4184. The macros
  4185. .b $w ,
  4186. .b $j ,
  4187. and
  4188. .b $m
  4189. are set to the identity of this host.
  4190. .i Sendmail
  4191. tries to find the fully qualified name of the host
  4192. if at all possible;
  4193. it does this by calling
  4194. .i gethostname (2)
  4195. to get the current hostname
  4196. and then passing that to
  4197. .i gethostbyname (3)
  4198. which is supposed to return the canonical version of that host name.**
  4199. .(f
  4200. **For example, on some systems
  4201. .i gethostname
  4202. might return
  4203. .q foo
  4204. which would be mapped to
  4205. .q foo.bar.com
  4206. by
  4207. .i gethostbyname .
  4208. .)f
  4209. Assuming this is successful,
  4210. .b $j
  4211. is set to the fully qualified name
  4212. and
  4213. .b $m
  4214. is set to the domain part of the name
  4215. (everything after the first dot).
  4216. The
  4217. .b $w
  4218. macro is set to the first word
  4219. (everything before the first dot)
  4220. if you have a level 5 or higher configuration file;
  4221. otherwise, it is set to the same value as
  4222. .b $j .
  4223. If the canonification is not successful,
  4224. it is imperative that the config file set
  4225. .b $j
  4226. to the fully qualified domain name**.
  4227. .(f
  4228. **Older versions of sendmail didn't pre-define
  4229. .b $j
  4230. at all, so up until 8.6,
  4231. config files
  4232. .i always
  4233. had to define
  4234. .b $j .
  4235. .)f
  4236. .pp
  4237. The
  4238. .b $f
  4239. macro is the id of the sender
  4240. as originally determined;
  4241. when mailing to a specific host
  4242. the
  4243. .b $g
  4244. macro is set to the address of the sender
  4245. .ul
  4246. relative to the recipient.
  4247. For example,
  4248. if I send to
  4249. .q bollard@matisse.CS.Berkeley.EDU
  4250. from the machine
  4251. .q vangogh.CS.Berkeley.EDU
  4252. the
  4253. .b $f
  4254. macro will be
  4255. .q eric
  4256. and the
  4257. .b $g
  4258. macro will be
  4259. .q eric@vangogh.CS.Berkeley.EDU.
  4260. .pp
  4261. The
  4262. .b $x
  4263. macro is set to the full name of the sender.
  4264. This can be determined in several ways.
  4265. It can be passed as flag to
  4266. .i sendmail .
  4267. It can be defined in the
  4268. .sm NAME
  4269. environment variable.
  4270. The third choice is the value of the
  4271. .q Full-Name:
  4272. line in the header if it exists,
  4273. and the fourth choice is the comment field
  4274. of a
  4275. .q From:
  4276. line.
  4277. If all of these fail,
  4278. and if the message is being originated locally,
  4279. the full name is looked up in the
  4280. .i /etc/passwd
  4281. file.
  4282. .pp
  4283. When sending,
  4284. the
  4285. .b $h ,
  4286. .b $u ,
  4287. and
  4288. .b $z
  4289. macros get set to the host, user, and home directory
  4290. (if local)
  4291. of the recipient.
  4292. The first two are set from the
  4293. .b $@
  4294. and
  4295. .b $:
  4296. part of the rewriting rules, respectively.
  4297. .pp
  4298. The
  4299. .b $p
  4300. and
  4301. .b $t
  4302. macros are used to create unique strings
  4303. (e.g., for the
  4304. .q Message-Id:
  4305. field).
  4306. The
  4307. .b $i
  4308. macro is set to the queue id on this host;
  4309. if put into the timestamp line
  4310. it can be extremely useful for tracking messages.
  4311. The
  4312. .b $v
  4313. macro is set to be the version number of
  4314. .i sendmail ;
  4315. this is normally put in timestamps
  4316. and has been proven extremely useful for debugging.
  4317. .pp
  4318. The
  4319. .b $c
  4320. field is set to the
  4321. .q "hop count,"
  4322. i.e., the number of times this message has been processed.
  4323. This can be determined
  4324. by the
  4325. .b -h
  4326. flag on the command line
  4327. or by counting the timestamps in the message.
  4328. .pp
  4329. The
  4330. .b $r
  4331. and
  4332. .b $s
  4333. fields are set to the protocol used to communicate with
  4334. .i sendmail
  4335. and the sending hostname.
  4336. They can be set together using the
  4337. .b -p
  4338. command line flag or separately using the
  4339. .b -M
  4340. or
  4341. .b -oM
  4342. flags.
  4343. .pp
  4344. The
  4345. .b $_
  4346. is set to a validated sender host name.
  4347. If the sender is running an RFC 1413 compliant IDENT server
  4348. and the receiver has the IDENT protocol turned on,
  4349. it will include the user name on that host.
  4350. .pp
  4351. The
  4352. .b ${client_name} ,
  4353. .b ${client_addr} ,
  4354. and
  4355. .b ${client_port}
  4356. macros
  4357. are set to the name, address, and port number of the SMTP client
  4358. who is invoking
  4359. .i sendmail
  4360. as a server.
  4361. These can be used in the
  4362. .i check_*
  4363. rulesets (using the
  4364. .b $&
  4365. deferred evaluation form, of course!).
  4366. .sh 2 "C and F *- Define Classes"
  4367. .pp
  4368. Classes of phrases may be defined
  4369. to match on the left hand side of rewriting rules,
  4370. where a
  4371. .q phrase
  4372. is a sequence of characters that does not contain space characters.
  4373. For example
  4374. a class of all local names for this site
  4375. might be created
  4376. so that attempts to send to oneself
  4377. can be eliminated.
  4378. These can either be defined directly in the configuration file
  4379. or read in from another file.
  4380. Classes are named as a single letter or a word in {braces}.
  4381. Class names beginning with lower case letters
  4382. and special characters are reserved for system use.
  4383. Classes defined in config files may be given names
  4384. from the set of upper case letters for short names
  4385. or beginning with an upper case letter for long names.
  4386. .pp
  4387. The syntax is:
  4388. .(b F
  4389. .b C c
  4390. .i c|phrase1
  4391. .i phrase2...
  4392. .br
  4393. .b F c
  4394. .i c|file
  4395. .)b
  4396. The first form defines the class
  4397. .i c
  4398. to match any of the named words.
  4399. If
  4400. .i phrase1
  4401. or
  4402. .i phrase2
  4403. is another class,
  4404. e.g.,
  4405. .i $=S ,
  4406. the contents of class
  4407. .i S
  4408. are added to class
  4409. .i c .
  4410. It is permissible to split them among multiple lines;
  4411. for example, the two forms:
  4412. .(b
  4413. CHmonet ucbmonet
  4414. .)b
  4415. and
  4416. .(b
  4417. CHmonet
  4418. CHucbmonet
  4419. .)b
  4420. are equivalent.
  4421. The ``F'' form
  4422. reads the elements of the class
  4423. .i c
  4424. from the named
  4425. .i file .
  4426. .pp
  4427. Elements of classes can be accessed in rules using
  4428. .b $=
  4429. or
  4430. .b $~ .
  4431. The
  4432. .b $~
  4433. (match entries not in class)
  4434. only matches a single word;
  4435. multi-word entries in the class are ignored in this context.
  4436. .pp
  4437. Some classes have internal meaning to
  4438. .i sendmail :
  4439. .nr ii 0.5i
  4440. .".ip $=b
  4441. ."A set of Content-Types that will not have the newline character
  4442. ."translated to CR-LF before encoding into base64 MIME.
  4443. ."The class can have major times
  4444. ."(e.g.,
  4445. .".q image )
  4446. ."or full types
  4447. ."(such as
  4448. .".q application/octet-stream ).
  4449. ."The class is initialized with
  4450. .".q application/octet-stream ,
  4451. .".q image ,
  4452. .".q audio ,
  4453. ."and
  4454. .".q video .
  4455. .ip $=e
  4456. contains the Content-Transfer-Encodings that can be 8(->7 bit encoded.
  4457. It is predefined to contain
  4458. .q 7bit ,
  4459. .q 8bit ,
  4460. and
  4461. .q binary .
  4462. .ip $=k
  4463. set to be the same as
  4464. .b $k ,
  4465. that is, the UUCP node name.
  4466. .ip $=m
  4467. set to the set of domains by which this host is known,
  4468. initially just
  4469. .b $m .
  4470. .ip $=n
  4471. can be set to the set of MIME body types
  4472. that can never be eight to seven bit encoded.
  4473. It defaults to
  4474. .q multipart/signed .
  4475. Message types
  4476. .q message/*
  4477. and
  4478. .q multipart/*
  4479. are never encoded directly.
  4480. Multipart messages are always handled recursively.
  4481. The handling of message/* messages
  4482. are controlled by class
  4483. .b $=s .
  4484. .ip $=q
  4485. A set of Content-Types that will never be encoded as base64
  4486. (if they have to be encoded, they will be encoded as quoted-printable).
  4487. It can have primary types
  4488. (e.g.,
  4489. .q text )
  4490. or full types
  4491. (such as
  4492. .q text/plain ).
  4493. The class is initialized to have
  4494. .q text/plain
  4495. only.
  4496. .ip $=s
  4497. contains the set of subtypes of message that can be treated recursively.
  4498. By default it contains only
  4499. .q rfc822 .
  4500. Other
  4501. .q message/*
  4502. types cannot be 8(->7 bit encoded.
  4503. If a message containing eight bit data is sent to a seven bit host,
  4504. and that message cannot be encoded into seven bits,
  4505. it will be stripped to 7 bits.
  4506. .ip $=t
  4507. set to the set of trusted users by the
  4508. .b T
  4509. configuration line.
  4510. If you want to read trusted users from a file, use
  4511. .b Ft c
  4512. .i /file/name .
  4513. .ip $=w
  4514. set to be the set of all names
  4515. this host is known by.
  4516. This can be used to match local hostnames.
  4517. .ip $={persistentMacros}
  4518. set to the macros would should be saved across queue runs.
  4519. Care should be taken when adding macro names to this class.
  4520. .pp
  4521. .i Sendmail
  4522. can be compiled to allow a
  4523. .i scanf (3)
  4524. string on the
  4525. .b F
  4526. line.
  4527. This lets you do simplistic parsing of text files.
  4528. For example, to read all the user names in your system
  4529. .i /etc/passwd
  4530. file into a class, use
  4531. .(b
  4532. FL/etc/passwd %[^:]
  4533. .)b
  4534. which reads every line up to the first colon.
  4535. .sh 2 "M *- Define Mailer"
  4536. .pp
  4537. Programs and interfaces to mailers
  4538. are defined in this line.
  4539. The format is:
  4540. .(b F
  4541. .b M c
  4542. .i name ,
  4543. {c
  4544. .i field =c
  4545. .i value |}*
  4546. .)b
  4547. where
  4548. .i name
  4549. is the name of the mailer
  4550. (used internally only)
  4551. and the
  4552. .q field=name
  4553. pairs define attributes of the mailer.
  4554. Fields are:
  4555. .(b
  4556. .ta 1i