816.)b
817This file does not grow.
818It is printed with the program
819.q mailstats/mailstats.c.
820The actual path of this file
821is defined in the
822.b S
823option of the
824.i sendmail.cf
825file.
826.sh 3 "/usr/\*(SB/mailq"
827.pp
828If
829.i sendmail
830is invoked as
831.q mailq,
832it will simulate the
833.b \-bp
834flag
835(i.e.,
836.i sendmail
837will print the contents of the mail queue;
838see below).
839This should be a link to /usr/\*(SD/sendmail.
840.sh 1 "NORMAL OPERATIONS"
841.sh 2 "The System Log"
842.pp
843The system log is supported by the
844.i syslogd \|(8)
845program.
846All messages from
847.i sendmail
848are logged under the
849.sm LOG_MAIL
850facility\**.
851.(f
852\**Except on Ultrix,
853which does not support facilities in the syslog.
854.)f
855.sh 3 "Format"
856.pp
857Each line in the system log
858consists of a timestamp,
859the name of the machine that generated it
860(for logging from several machines
861over the local area network),
862the word
863.q sendmail: ,
864and a message\**.
865.(f
866\**This format may vary slightly if your vendor has changed
867the syntax.
868.)f
869Most messages are a sequence of
870.i name \c
871=\c
872.i value
873pairs.
874.pp
875The two most common lines are logged when a message is processed.
876The first logs the receipt of a message;
877there will be exactly one of these per message.
878Some fields may be omitted if they do not contain interesting information.
879Fields are:
880.ip from
881The envelope sender address.
882.ip size
883The size of the message in bytes.
884.ip class
885The class (i.e., numeric precedence) of the message.
886.ip pri
887The initial message priority (used for queue sorting).
888.ip nrcpts
889The number of envelope recipients for this message
890(after aliasing and forwarding).
891.ip msgid
892The message id of the message (from the header).
893.ip proto
894The protocol used to receive this message (e.g., ESMTP or UUCP)
895.ip relay
896The machine from which it was received.
897.lp
898There is also one line logged per delivery attempt
899(so there can be several per message if delivery is deferred
900or there are multiple recipients).
901Fields are:
902.ip to
903A comma-separated list of the recipients to this mailer.
904.ip ctladdr
905The ``controlling user'', that is, the name of the user
906whose credentials we use for delivery.
907.ip delay
908The total delay between the time this message was received
909and the time it was delivered.
910.ip xdelay
911The amount of time needed in this delivery attempt
912(normally indicative of the speed of the connection).
913.ip mailer
914The name of the mailer used to deliver to this recipient.
915.ip relay
916The name of the host that actually accepted (or rejected) this recipient.
917.ip stat
918The delivery status.
919.lp
920Not all fields are present in all messages;
921for example, the relay is not listed for local deliveries.
922.sh 3 "Levels"
923.pp
924If you have
925.i syslogd \|(8)
926or an equivalent installed,
927you will be able to do logging.
928There is a large amount of information that can be logged.
929The log is arranged as a succession of levels.
930At the lowest level
931only extremely strange situations are logged.
932At the highest level,
933even the most mundane and uninteresting events
934are recorded for posterity.
935As a convention,
936log levels under ten
937are considered generally
938.q useful;
939log levels above 64
940are reserved for debugging purposes.
941Levels from 11\-64 are reserved for verbose information
942that some sites might want.
943.pp
944A complete description of the log levels
945is given in section
946.\" XREF
9474.6.
948.sh 2 "Dumping State"
949.pp
950You can ask
951.i sendmail
952to log a dump of the open files
953and the connection cache
954by sending it a
955.sm SIGUSR1
956signal.
957The results are logged at
958.sm LOG_DEBUG
959priority.
960.sh 2 "The Mail Queue"
961.pp
962Sometimes a host cannot handle a message immediately.
963For example, it may be down or overloaded, causing it to refuse connections.
964The sending host is then expected to save this message in
965its mail queue
966and attempt to deliver it later.
967.pp
968Under normal conditions the mail queue will be processed transparently.
969However, you may find that manual intervention is sometimes necessary.
970For example,
971if a major host is down for a period of time
972the queue may become clogged.
973Although
974.i sendmail
975ought to recover gracefully when the host comes up,
976you may find performance unacceptably bad in the meantime.
977.sh 3 "Printing the queue"
978.pp
979The contents of the queue can be printed
980using the
981.i mailq
982command
983(or by specifying the
984.b \-bp
985flag to
986.i sendmail ):
987.(b
988mailq
989.)b
990This will produce a listing of the queue id's,
991the size of the message,
992the date the message entered the queue,
993and the sender and recipients.
994.sh 3 "Forcing the queue"
995.pp
996.i Sendmail
997should run the queue automatically
998at intervals.
999The algorithm is to read and sort the queue,
1000and then to attempt to process all jobs in order.
1001When it attempts to run the job,
1002.i sendmail
1003first checks to see if the job is locked.
1004If so, it ignores the job.
1005.pp
1006There is no attempt to insure that only one queue processor
1007exists at any time,
1008since there is no guarantee that a job cannot take forever
1009to process
1010(however,
1011.i sendmail
1012does include heuristics to try to abort jobs
1013that are taking absurd amounts of time;
1014technically, this violates RFC 821, but is blessed by RFC 1123).
1015Due to the locking algorithm,
1016it is impossible for one job to freeze the entire queue.
1017However,
1018an uncooperative recipient host
1019or a program recipient
1020that never returns
1021can accumulate many processes in your system.
1022Unfortunately,
1023there is no completely general way to solve this.
1024.pp
1025In some cases,
1026you may find that a major host going down
1027for a couple of days
1028may create a prohibitively large queue.
1029This will result in
1030.i sendmail
1031spending an inordinate amount of time
1032sorting the queue.
1033This situation can be fixed by moving the queue to a temporary place
1034and creating a new queue.
1035The old queue can be run later when the offending host returns to service.
1036.pp
1037To do this,
1038it is acceptable to move the entire queue directory:
1039.(b
1040cd /var/spool
1041mv mqueue omqueue; mkdir mqueue; chmod 700 mqueue
1042.)b
1043You should then kill the existing daemon
1044(since it will still be processing in the old queue directory)
1045and create a new daemon.
1046.pp
1047To run the old mail queue,
1048run the following command:
1049.(b
1050/usr/\*(SD/sendmail \-oQ/var/spool/omqueue \-q
1051.)b
1052The
1053.b \-oQ
1054flag specifies an alternate queue directory
1055and the
1056.b \-q
1057flag says to just run every job in the queue.
1058If you have a tendency toward voyeurism,
1059you can use the
1060.b \-v
1061flag to watch what is going on.
1062.pp
1063When the queue is finally emptied,
1064you can remove the directory:
1065.(b
1066rmdir /var/spool/omqueue
1067.)b
1068.sh 2 "Disk Based Connection Information"
1069.pp
1070.i Sendmail
1071stores a large amount of information about each remote system it
1072has connected to in memory. It is now possible to preserve some
1073of this information on disk as well, by using the
1074.b HostStatusDirectory
1075option, so that it may be shared between several invocations of
1076.i sendmail .
1077This allows mail to be queued immediately or skipped during a queue run if
1078there has been a recent failure in connecting to a remote machine.
1079.pp
1080Additionally enabling
1081.b SingleThreadDelivery
1082has the added effect of single-threading mail delivery to a destination.
1083This can be quite helpful
1084if the remote machine is running an SMTP server that is easily overloaded
1085or cannot accept more than a single connection at a time,
1086but can cause some messages to be punted to a future queue run.
1087It also applies to
1088.i all
1089hosts, so setting this because you have one machine on site
1090that runs some software that is easily overrun
1091can cause mail to other hosts to be slowed down.
1092If this option is set,
1093you probably want to set the
1094.b MinQueueAge
1095option as well and run the queue fairly frequently;
1096this way jobs that are skipped because another
1097.i sendmail
1098is talking to the same host will be tried again quickly
1099rather than being delayed for a long time.
1100.pp
1101The disk based host information is stored in a subdirectory of the
1102.b mqueue
1103directory called
1104.b \&.hoststat \**.
1105.(f
1106\**This is the usual value of the
1107.b HostStatusDirectory
1108option;
1109it can, of course, go anywhere you like in your filesystem.
1110.)f
1111Removing this directory and its subdirectories has an effect similar to
1112the
1113.i purgestat
1114command and is completely safe.
1115The information in these directories can
1116be perused with the
1117.i hoststat
1118command, which will indicate the host name, the last access, and the
1119status of that access.
1120An asterisk in the left most column indicates that a
1121.i sendmail
1122process currently has the host locked for mail delivery.
1123.pp
1124The disk based connection information is treated the same way as memory based
1125connection information for the purpose of timeouts.
1126By default, information about host failures is valid for 30 minutes.
1127This can be adjusted with
1128the
1129.b Timeout.hoststatus
1130option.
1131.pp
1132The connection information stored on disk may be purged at any time
1133with the
1134.i purgestat
1135command or by invoking sendmail with the
1136.b \-bH
1137switch.
1138The connection information may be viewed with the
1139.i hoststat
1140command or by invoking sendmail with the
1141.b \-bh
1142switch.
1143.sh 2 "The Service Switch"
1144.pp
1145The implementation of certain system services
1146such as host and user name lookup
1147is controlled by the service switch.
1148If the host operating system supports such a switch
1149.i sendmail
1150will use the native version.
1151Ultrix, Solaris, and DEC OSF/1 are examples of such systems\**.
1152.(f
1153\**HP-UX 10 has service switch support,
1154but since the APIs are apparently not available in the libraries
1155.i sendmail
1156does not use the native service switch in this release.
1157.)f
1158.pp
1159If the underlying operating system does not support a service switch
1160(e.g., SunOS 4.X, HP-UX, BSD)
1161then
1162.i sendmail
1163will provide a stub implementation.
1164The
1165.b ServiceSwitchFile
1166option points to the name of a file that has the service definitions.
1167Each line has the name of a service
1168and the possible implementations of that service.
1169For example, the file:
1170.(b
1171hosts dns files nis
1172aliases files nis
1173.)b
1174will ask
1175.i sendmail
1176to look for hosts in the Domain Name System first.
1177If the requested host name is not found,
1178it tries local files,
1179and if that fails it tries NIS.
1180Similarly,
1181when looking for aliases
1182it will try the local files first
1183followed by NIS.
1184.pp
1185Service switches are not completely integrated.
1186For example, despite the fact that the host entry listed in the above example
1187specifies to look in NIS,
1188on SunOS this won't happen because the system implementation of
1189.i gethostbyname \|(3)
1190doesn't understand this.
1191If there is enough demand
1192.i sendmail
1193may reimplement
1194.i gethostbyname \|(3),
1195.i gethostbyaddr \|(3),
1196.i getpwent \|(3),
1197and the other system routines that would be necessary
1198to make this work seamlessly.
1199.sh 2 "The Alias Database"
1200.pp
1201After recipient addresses are read from the SMTP connection
1202or command line
1203they are parsed by ruleset 0,
1204which must resolve to a
1205{\c
1206.i mailer ,
1207.i host ,
1208.i user }
1209triple.
1210If the flags selected by the
1211.i mailer
1212include the
1213.b A
1214(aliasable) flag,
1215the
1216.i user
1217part of the triple is looked up as the key
1218(i.e., the left hand side)
1219into the alias database.
1220If there is a match, the address is deleted from the send queue
1221and all addresses on the right hand side of the alias
1222are added in place of the alias that was found.
1223This is a recursive operation,
1224so aliases found in the right hand side of the alias
1225are similarly expanded.
1226.pp
1227The alias database exists in two forms.
1228One is a text form,
1229maintained in the file
1230.i /etc/aliases.
1231The aliases are of the form
1232.(b
1233name: name1, name2, ...
1234.)b
1235Only local names may be aliased;
1236e.g.,
1237.(b
1238eric@prep.ai.MIT.EDU: eric@CS.Berkeley.EDU
1239.)b
1240will not have the desired effect
1241(except on prep.ai.MIT.EDU,
1242and they probably don't want me)\**.
1243.(f
1244\**Actually, any mailer that has the `A' mailer flag set
1245will permit aliasing;
1246this is normally limited to the local mailer.
1247.)f
1248Aliases may be continued by starting any continuation lines
1249with a space or a tab.
1250Blank lines and lines beginning with a sharp sign
1251(\c
1252.q # )
1253are comments.
1254.pp
1255The second form is processed by the
1256.i ndbm \|(3)\**
1257.(f
1258\**The
1259.i gdbm
1260package does not work.
1261.)f
1262or the Berkeley DB library.
1263This form is in the file
1264.i /etc/aliases.db
1265(if using NEWDB)
1266or
1267.i /etc/aliases.dir
1268and
1269.i /etc/aliases.pag
1270(if using NDBM).
1271This is the form that
1272.i sendmail
1273actually uses to resolve aliases.
1274This technique is used to improve performance.
1275.pp
1276The control of search order is actually set by the service switch.
1277Essentially, the entry
1278.(b
1279O AliasFile=switch:aliases
1280.)b
1281is always added as the first alias entry;
1282also, the first alias file name without a class
1283(e.g., without
1284.q nis:
1285on the front)
1286will be used as the name of the file for a ``files'' entry
1287in the aliases switch.
1288For example, if the configuration file contains
1289.(b
1290O AliasFile=/etc/aliases
1291.)b
1292and the service switch contains
1293.(b
1294aliases nis files nisplus
1295.)b
1296then aliases will first be searched in the NIS database,
1297then in /etc/aliases,
1298then in the NIS+ database.
1299.pp
1300You can also use
1301.sm NIS -based
1302alias files.
1303For example, the specification:
1304.(b
1305O AliasFile=/etc/aliases
1306O AliasFile=nis:mail.aliases@my.nis.domain
1307.)b
1308will first search the /etc/aliases file
1309and then the map named
1310.q mail.aliases
1311in
1312.q my.nis.domain .
1313Warning: if you build your own
1314.sm NIS -based
1315alias files,
1316be sure to provide the
1317.b \-l
1318flag to
1319.i makedbm (8)
1320to map upper case letters in the keys to lower case;
1321otherwise, aliases with upper case letters in their names
1322won't match incoming addresses.
1323.pp
1324Additional flags can be added after the colon
1325exactly like a
1326.b K
1327line \(em for example:
1328.(b
1329O AliasFile=nis:\-N mail.aliases@my.nis.domain
1330.)b
1331will search the appropriate NIS map and always include null bytes in the key.
1332Also:
1333.(b
1334O AliasFile=nis:\-f mail.aliases@my.nis.domain
1335.)b
1336will prevent sendmail from downcasing the key before the alias lookup.
1337.sh 3 "Rebuilding the alias database"
1338.pp
1339The
1340.i hash
1341or
1342.i dbm
1343version of the database
1344may be rebuilt explicitly by executing the command
1345.(b
1346newaliases
1347.)b
1348This is equivalent to giving
1349.i sendmail
1350the
1351.b \-bi
1352flag:
1353.(b
1354/usr/\*(SD/sendmail \-bi
1355.)b
1356.pp
1357If the
1358.b RebuildAliases
1359(old
1360.b D )
1361option is specified in the configuration,
1362.i sendmail
1363will rebuild the alias database automatically
1364if possible
1365when it is out of date.
1366Auto-rebuild can be dangerous
1367on heavily loaded machines
1368with large alias files;
1369if it might take more than the rebuild timeout
1370(option
1371.b AliasWait ,
1372old
1373.b a ,
1374which is normally five minutes)
1375to rebuild the database,
1376there is a chance that several processes will start the rebuild process
1377simultaneously.
1378.pp
1379If you have multiple aliases databases specified,
1380the
1381.b \-bi
1382flag rebuilds all the database types it understands
1383(for example, it can rebuild NDBM databases but not NIS databases).
1384.sh 3 "Potential problems"
1385.pp
1386There are a number of problems that can occur
1387with the alias database.
1388They all result from a
1389.i sendmail
1390process accessing the DBM version
1391while it is only partially built.
1392This can happen under two circumstances:
1393One process accesses the database
1394while another process is rebuilding it,
1395or the process rebuilding the database dies
1396(due to being killed or a system crash)
1397before completing the rebuild.
1398.pp
1399Sendmail has three techniques to try to relieve these problems.
1400First, it ignores interrupts while rebuilding the database;
1401this avoids the problem of someone aborting the process
1402leaving a partially rebuilt database.
1403Second,
1404it locks the database source file during the rebuild \(em
1405but that may not work over NFS or if the file is unwritable.
1406Third,
1407at the end of the rebuild
1408it adds an alias of the form
1409.(b
1410@: @
1411.)b
1412(which is not normally legal).
1413Before
1414.i sendmail
1415will access the database,
1416it checks to insure that this entry exists\**.
1417.(f
1418\**The
1419.b AliasWait
1420option is required in the configuration
1421for this action to occur.
1422This should normally be specified.
1423.)f
1424.sh 3 "List owners"
1425.pp
1426If an error occurs on sending to a certain address,
1427say
1428.q \fIx\fP ,
1429.i sendmail
1430will look for an alias
1431of the form
1432.q owner-\fIx\fP
1433to receive the errors.
1434This is typically useful
1435for a mailing list
1436where the submitter of the list
1437has no control over the maintenance of the list itself;
1438in this case the list maintainer would be the owner of the list.
1439For example:
1440.(b
1441unix-wizards: eric@ucbarpa, wnj@monet, nosuchuser,
1442 sam@matisse
1443owner-unix-wizards: unix-wizards-request
1444unix-wizards-request: eric@ucbarpa
1445.)b
1446would cause
1447.q eric@ucbarpa
1448to get the error that will occur
1449when someone sends to
1450unix-wizards
1451due to the inclusion of
1452.q nosuchuser
1453on the list.
1454.pp
1455List owners also cause the envelope sender address to be modified.
1456The contents of the owner alias are used if they point to a single user,
1457otherwise the name of the alias itself is used.
1458For this reason, and to obey Internet conventions,
1459the
1460.q owner-
1461address normally points at the
1462.q -request
1463address; this causes messages to go out with the typical Internet convention
1464of using ``\c
1465.i list -request''
1466as the return address.
1467.sh 2 "User Information Database"
1468.pp
1469If you have a version of
1470.i sendmail
1471with the user information database
1472compiled in,
1473and you have specified one or more databases using the
1474.b U
1475option,
1476the databases will be searched for a
1477.i user :maildrop
1478entry.
1479If found, the mail will be sent to the specified address.
1480.sh 2 "Per-User Forwarding (.forward Files)"
1481.pp
1482As an alternative to the alias database,
1483any user may put a file with the name
1484.q .forward
1485in his or her home directory.
1486If this file exists,
1487.i sendmail
1488redirects mail for that user
1489to the list of addresses listed in the .forward file.
1490For example, if the home directory for user
1491.q mckusick
1492has a .forward file with contents:
1493.(b
1494mckusick@ernie
1495kirk@calder
1496.)b
1497then any mail arriving for
1498.q mckusick
1499will be redirected to the specified accounts.
1500.pp
1501Actually, the configuration file defines a sequence of filenames to check.
1502By default, this is the user's .forward file,
1503but can be defined to be more generally using the
1504.b ForwardPath
1505option.
1506If you change this,
1507you will have to inform your user base of the change;
1508\&.forward is pretty well incorporated into the collective subconscious.
1509.sh 2 "Special Header Lines"
1510.pp
1511Several header lines have special interpretations
1512defined by the configuration file.
1513Others have interpretations built into
1514.i sendmail
1515that cannot be changed without changing the code.
1516These builtins are described here.
1517.sh 3 "Errors-To:"
1518.pp
1519If errors occur anywhere during processing,
1520this header will cause error messages to go to
1521the listed addresses.
1522This is intended for mailing lists.
1523.pp
1524The Errors-To: header was created in the bad old days
1525when UUCP didn't understand the distinction between an envelope and a header;
1526this was a hack to provide what should now be passed
1527as the envelope sender address.
1528It should go away.
1529It is only used if the
1530.b UseErrorsTo
1531option is set.
1532.pp
1533The Errors-To: header is officially deprecated
1534and will go away in a future release.
1535.sh 3 "Apparently-To:"
1536.pp
1537RFC 822 requires at least one recipient field
1538(To:, Cc:, or Bcc: line)
1539in every message.
1540If a message comes in with no recipients listed in the message
1541then
1542.i sendmail
1543will adjust the header based on the
1544.q NoRecipientAction
1545option.
1546One of the possible actions is to add an
1547.q "Apparently-To:"
1548header line for any recipients it is aware of.
1549.pp
1550The Apparently-To: header is non-standard
1551and is deprecated.
1552.sh 3 "Precedence"
1553.pp
1554The Precedence: header can be used as a crude control of message priority.
1555It tweaks the sort order in the queue
1556and can be configured to change the message timeout values.
1557.sh 2 "IDENT Protocol Support"
1558.pp
1559.i Sendmail
1560supports the IDENT protocol as defined in RFC 1413.
1561Although this enhances identification
1562of the author of an email message
1563by doing a ``call back'' to the originating system to include
1564the owner of a particular TCP connection
1565in the audit trail
1566it is in no sense perfect;
1567a determined forger can easily spoof the IDENT protocol.
1568The following description is excerpted from RFC 1413:
1569.ba +5
1570.lp
15716. Security Considerations
1572.lp
1573The information returned by this protocol is at most as trustworthy
1574as the host providing it OR the organization operating the host. For
1575example, a PC in an open lab has few if any controls on it to prevent
1576a user from having this protocol return any identifier the user
1577wants. Likewise, if the host has been compromised the information
1578returned may be completely erroneous and misleading.
1579.lp
1580The Identification Protocol is not intended as an authorization or
1581access control protocol. At best, it provides some additional
1582auditing information with respect to TCP connections. At worst, it
1583can provide misleading, incorrect, or maliciously incorrect
1584information.
1585.lp
1586The use of the information returned by this protocol for other than
1587auditing is strongly discouraged. Specifically, using Identification
1588Protocol information to make access control decisions - either as the
1589primary method (i.e., no other checks) or as an adjunct to other
1590methods may result in a weakening of normal host security.
1591.lp
1592An Identification server may reveal information about users,
1593entities, objects or processes which might normally be considered
1594private. An Identification server provides service which is a rough
1595analog of the CallerID services provided by some phone companies and
1596many of the same privacy considerations and arguments that apply to
1597the CallerID service apply to Identification. If you wouldn't run a
1598"finger" server due to privacy considerations you may not want to run
1599this protocol.
1600.ba
1601.lp
1602In some cases your system may not work properly with IDENT support
1603due to a bug in the TCP/IP implementation.
1604The symptoms will be that for some hosts
1605the SMTP connection will be closed
1606almost immediately.
1607If this is true or if you do not want to use IDENT,
1608you should set the IDENT timeout to zero;
1609this will disable the IDENT protocol.
1610.sh 1 "ARGUMENTS"
1611.pp
1612The complete list of arguments to
1613.i sendmail
1614is described in detail in Appendix A.
1615Some important arguments are described here.
1616.sh 2 "Queue Interval"
1617.pp
1618The amount of time between forking a process
1619to run through the queue
1620is defined by the
1621.b \-q
1622flag.
1623If you run with delivery mode set to
1624.b i
1625or
1626.b b
1627this can be relatively large,
1628since it will only be relevant
1629when a host that was down comes back up.
1630If you run in
1631.b q
1632mode
1633it should be relatively short,
1634since it defines the maximum amount of time that a message
1635may sit in the queue.
1636(See also the MinQueueAge option.)
1637.pp
1638RFC 1123 section 5.3.1.1 says that this value should be at least 30 minutes
1639(although that probably doesn't make sense if you use ``queue-only'' mode).
1640.sh 2 "Daemon Mode"
1641.pp
1642If you allow incoming mail over an IPC connection,
1643you should have a daemon running.
1644This should be set by your
1645.i /etc/rc
1646file using the
1647.b \-bd
1648flag.
1649The
1650.b \-bd
1651flag and the
1652.b \-q
1653flag may be combined in one call:
1654.(b
1655/usr/\*(SD/sendmail \-bd \-q30m
1656.)b
1657.pp
1658An alternative approach is to invoke sendmail from
1659.i inetd (8)
1660(use the
1661.b \-bs
1662flag to ask sendmail to speak SMTP on its standard input and output).
1663This works and allows you to wrap
1664.i sendmail
1665in a TCP wrapper program,
1666but may be a bit slower since the configuration file
1667has to be re-read on every message that comes in.
1668If you do this, you still need to have a
1669.i sendmail
1670running to flush the queue:
1671.(b
1672/usr/\*(SD/sendmail \-q30m
1673.)b
1674.sh 2 "Forcing the Queue"
1675.pp
1676In some cases you may find that the queue has gotten clogged for some reason.
1677You can force a queue run
1678using the
1679.b \-q
1680flag (with no value).
1681It is entertaining to use the
1682.b \-v
1683flag (verbose)
1684when this is done to watch what happens:
1685.(b
1686/usr/\*(SD/sendmail \-q \-v
1687.)b
1688.pp
1689You can also limit the jobs to those with a particular queue identifier,
1690sender, or recipient
1691using one of the queue modifiers.
1692For example,
1693.q \-qRberkeley
1694restricts the queue run to jobs that have the string
1695.q berkeley
1696somewhere in one of the recipient addresses.
1697Similarly,
1698.q \-qSstring
1699limits the run to particular senders and
1700.q \-qIstring
1701limits it to particular queue identifiers.
1702.sh 2 "Debugging"
1703.pp
1704There are a fairly large number of debug flags
1705built into
1706.i sendmail .
1707Each debug flag has a number and a level,
1708where higher levels means to print out more information.
1709The convention is that levels greater than nine are
1710.q absurd,
1711i.e.,
1712they print out so much information that you wouldn't normally
1713want to see them except for debugging that particular piece of code.
1714Debug flags are set using the
1715.b \-d
1716option;
1717the syntax is:
1718.(b
1719.ta \w'debug-option 'u
1720debug-flag: \fB\-d\fP debug-list
1721debug-list: debug-option [ , debug-option ]*
1722debug-option: debug-range [ . debug-level ]
1723debug-range: integer | integer \- integer
1724debug-level: integer
1725.)b
1726where spaces are for reading ease only.
1727For example,
1728.(b
1729\-d12 Set flag 12 to level 1
1730\-d12.3 Set flag 12 to level 3
1731\-d3\-17 Set flags 3 through 17 to level 1
1732\-d3\-17.4 Set flags 3 through 17 to level 4
1733.)b
1734For a complete list of the available debug flags
1735you will have to look at the code
1736(they are too dynamic to keep this documentation up to date).
1737.sh 2 "Changing the Values of Options"
1738.pp
1739Options can be overridden using the
1740.b \-o
1741or
1742.b \-O
1743command line flags.
1744For example,
1745.(b
1746/usr/\*(SD/sendmail \-oT2m
1747.)b
1748sets the
1749.b T
1750(timeout) option to two minutes
1751for this run only;
1752the equivalent line using the long option name is
1753.(b
1754/usr/\*(SD/sendmail -OTimeout.queuereturn=2m
1755.)b
1756.pp
1757Some options have security implications.
1758Sendmail allows you to set these,
1759but relinquishes its setuid root permissions thereafter\**.
1760.(f
1761\**That is, it sets its effective uid to the real uid;
1762thus, if you are executing as root,
1763as from root's crontab file or during system startup
1764the root permissions will still be honored.
1765.)f
1766.sh 2 "Trying a Different Configuration File"
1767.pp
1768An alternative configuration file
1769can be specified using the
1770.b \-C
1771flag; for example,
1772.(b
1773/usr/\*(SD/sendmail \-Ctest.cf \-oQ/tmp/mqueue
1774.)b
1775uses the configuration file
1776.i test.cf
1777instead of the default
1778.i /etc/sendmail.cf.
1779If the
1780.b \-C
1781flag has no value
1782it defaults to
1783.i sendmail.cf
1784in the current directory.
1785.pp
1786.i Sendmail
1787gives up its setuid root permissions
1788when you use this flag, so it is common to use a publicly writable directory
1789(such as /tmp)
1790as the spool directory (QueueDirectory or Q option) while testing.
1791.sh 2 "Logging Traffic"
1792.pp
1793Many SMTP implementations do not fully implement the protocol.
1794For example, some personal computer based SMTPs
1795do not understand continuation lines in reply codes.
1796These can be very hard to trace.
1797If you suspect such a problem, you can set traffic logging using the
1798.b \-X
1799flag.
1800For example,
1801.(b
1802/usr/\*(SD/sendmail \-X /tmp/traffic \-bd
1803.)b
1804will log all traffic in the file
1805.i /tmp/traffic .
1806.pp
1807This logs a lot of data very quickly and should
1808.b NEVER
1809be used
1810during normal operations.
1811After starting up such a daemon,
1812force the errant implementation to send a message to your host.
1813All message traffic in and out of
1814.i sendmail ,
1815including the incoming SMTP traffic,
1816will be logged in this file.
1817.sh 2 "Testing Configuration Files"
1818.pp
1819When you build a configuration table,
1820you can do a certain amount of testing
1821using the
1822.q "test mode"
1823of
1824.i sendmail .
1825For example,
1826you could invoke
1827.i sendmail
1828as:
1829.(b
1830sendmail \-bt \-Ctest.cf
1831.)b
1832which would read the configuration file
1833.q test.cf
1834and enter test mode.
1835In this mode,
1836you enter lines of the form:
1837.(b
1838rwset address
1839.)b
1840where
1841.i rwset
1842is the rewriting set you want to use
1843and
1844.i address
1845is an address to apply the set to.
1846Test mode shows you the steps it takes
1847as it proceeds,
1848finally showing you the address it ends up with.
1849You may use a comma separated list of rwsets
1850for sequential application of rules to an input.
1851For example:
1852.(b
18533,1,21,4 monet:bollard
1854.)b
1855first applies ruleset three to the input
1856.q monet:bollard.
1857Ruleset one is then applied to the output of ruleset three,
1858followed similarly by rulesets twenty-one and four.
1859.pp
1860If you need more detail,
1861you can also use the
1862.q \-d21
1863flag to turn on more debugging.
1864For example,
1865.(b
1866sendmail \-bt \-d21.99
1867.)b
1868turns on an incredible amount of information;
1869a single word address
1870is probably going to print out several pages worth of information.
1871.pp
1872You should be warned that internally,
1873.i sendmail
1874applies ruleset 3 to all addresses.
1875In test mode
1876you will have to do that manually.
1877For example, older versions allowed you to use
1878.(b
18790 bruce@broadcast.sony.com
1880.)b
1881This version requires that you use:
1882.(b
18833,0 bruce@broadcast.sony.com
1884.)b
1885.pp
1886As of version 8.7,
1887some other syntaxes are available in test mode:
1888.bu
1889\&.D\|x\|value
1890defines macro
1891.i x
1892to have the indicated
1893.i value .
1894This is useful when debugging rules that use the
1895.b $& \c
1896.i x
1897syntax.
1898.bu
1899\&.C\|c\|value
1900adds the indicated
1901.i value
1902to class
1903.i c .
1904.bu
1905\&.S\|ruleset
1906dumps the contents of the indicated ruleset.
1907.bu
1908\-d\|debug-spec
1909is equivalent to the command-line flag.
1910.sh 2 "Persistent Host Status Information"
1911.pp
1912When
1913.b HostStatusDirectory
1914is enabled,
1915information about the status of hosts is maintained on disk
1916and can thus be shared between different instantiations of
1917.i sendmail .
1918The status of the last connection with each remote host
1919may be viewed with the command:
1920.(b
1921sendmail \-bh
1922.)b
1923This information may be flushed with the command:
1924.(b
1925sendmail \-bH
1926.)b
1927Flushing the information prevents new
1928.i sendmail
1929processes from loading it,
1930but does not prevent existing processes from using the status information
1931that they already have.
1932.sh 1 "TUNING"
1933.pp
1934There are a number of configuration parameters
1935you may want to change,
1936depending on the requirements of your site.
1937Most of these are set
1938using an option in the configuration file.
1939For example,
1940the line
1941.q "O Timeout.queuereturn=5d"
1942sets option
1943.q Timeout.queuereturn
1944to the value
1945.q 5d
1946(five days).
1947.pp
1948Most of these options have appropriate defaults for most sites.
1949However,
1950sites having very high mail loads may find they need to tune them
1951as appropriate for their mail load.
1952In particular,
1953sites experiencing a large number of small messages,
1954many of which are delivered to many recipients,
1955may find that they need to adjust the parameters
1956dealing with queue priorities.
1957.pp
1958All versions of
1959.i sendmail
1960prior to 8.7
1961had single character option names.
1962As of 8.7,
1963options have long (multi-character names).
1964Although old short names are still accepted,
1965most new options do not have short equivalents.
1966.pp
1967This section only describes the options you are most likely
1968to want to tweak;
1969read section
1970.\"XREF
19715
1972for more details.
1973.sh 2 "Timeouts"
1974.pp
1975All time intervals are set
1976using a scaled syntax.
1977For example,
1978.q 10m
1979represents ten minutes, whereas
1980.q 2h30m
1981represents two and a half hours.
1982The full set of scales is:
1983.(b
1984.ta 4n
1985s seconds
1986m minutes
1987h hours
1988d days
1989w weeks
1990.)b
1991.sh 3 "Queue interval"
1992.pp
1993The argument to the
1994.b \-q
1995flag
1996specifies how often a sub-daemon will run the queue.
1997This is typically set to between fifteen minutes
1998and one hour.
1999RFC 1123 section 5.3.1.1 recommends that this be at least 30 minutes.
2000.sh 3 "Read timeouts"
2001.pp
2002Timeouts all have option names
2003.q Timeout.\fIsuboption\fP .
2004The recognized
2005.i suboption s,
2006their default values, and the minimum values
2007allowed by RFC 1123 section 5.3.2 are:
2008.nr ii 1i
2009.ip connect
2010The time to wait for an SMTP connection to open
2011(the
2012.i connect (2)
2013system call)
2014[0, unspecified].
2015If zero, uses the kernel default.
2016In no case can this option extend the timeout
2017longer than the kernel provides, but it can shorten it.
2018This is to get around kernels that provide an absurdly long connection timeout
2019(90 minutes in one case).
2020.ip iconnect
2021The same as
2022.i connect,
2023except it applies only to the initial attempt to connect to a host
2024for a given message
2025[0, unspecified].
2026The concept is that this should be very short (a few seconds);
2027hosts that are well connected and responsive will thus be serviced immediately.
2028Hosts that are slow will not hold up other deliveries in the initial
2029delivery attempt.
2030.ip initial
2031The wait for the initial 220 greeting message
2032[5m, 5m].
2033.ip helo
2034The wait for a reply from a HELO or EHLO command
2035[5m, unspecified].
2036This may require a host name lookup, so
2037five minutes is probably a reasonable minimum.
2038.ip mail\(dg
2039The wait for a reply from a MAIL command
2040[10m, 5m].
2041.ip rcpt\(dg
2042The wait for a reply from a RCPT command
2043[1h, 5m].
2044This should be long
2045because it could be pointing at a list
2046that takes a long time to expand
2047(see below).
2048.ip datainit\(dg
2049The wait for a reply from a DATA command
2050[5m, 2m].
2051.ip datablock\(dg
2052The wait for reading a data block
2053(that is, the body of the message).
2054[1h, 3m].
2055This should be long because it also applies to programs
2056piping input to
2057.i sendmail
2058which have no guarantee of promptness.
2059.ip datafinal\(dg
2060The wait for a reply from the dot terminating a message.
2061[1h, 10m].
2062If this is shorter than the time actually needed
2063for the receiver to deliver the message,
2064duplicates will be generated.
2065This is discussed in RFC 1047.
2066.ip rset
2067The wait for a reply from a RSET command
2068[5m, unspecified].
2069.ip quit
2070The wait for a reply from a QUIT command
2071[2m, unspecified].
2072.ip misc
2073The wait for a reply from miscellaneous (but short) commands
2074such as NOOP (no-operation) and VERB (go into verbose mode).
2075[2m, unspecified].
2076.ip command\(dg
2077In server SMTP,
2078the time to wait for another command.
2079[1h, 5m].
2080.ip ident
2081The timeout waiting for a reply to an IDENT query
2082[30s\**, unspecified].
2083.(f
2084\**On some systems the default is zero to turn the protocol off entirely.
2085.)f
2086.ip fileopen
2087The timeout for opening .forward and :include: files [60s, none].
2088.ip hoststatus
2089How long status information about a host
2090(e.g., host down)
2091will be cached before it is considered stale
2092[30m, unspecified].
2093.lp
2094For compatibility with old configuration files,
2095if no
2096.i suboption
2097is specified,
2098all the timeouts marked with \(dg are set to the indicated value.
2099.pp
2100Many of the RFC 1123 minimum values
2101may well be too short.
2102.i Sendmail
2103was designed to the RFC 822 protocols,
2104which did not specify read timeouts;
2105hence, versions of
2106.i sendmail
2107prior to version 8.1 did not guarantee to reply to messages promptly.
2108In particular, a
2109.q RCPT
2110command specifying a mailing list
2111will expand and verify the entire list;
2112a large list on a slow system
2113may easily take more than five minutes\**.
2114.(f
2115\**This verification includes looking up every address
2116with the name server;
2117this involves network delays,
2118and can in some cases can be considerable.
2119.)f
2120I recommend a one hour timeout \*-
2121since a communications failure during the RCPT phase is rare,
2122a long timeout is not onerous
2123and may ultimately help reduce network load
2124and duplicated messages.
2125.pp
2126For example, the lines:
2127.(b
2128O Timeout.command=25m
2129O Timeout.datablock=3h
2130.)b
2131sets the server SMTP command timeout to 25 minutes
2132and the input data block timeout to three hours.
2133.sh 3 "Message timeouts"
2134.pp
2135After sitting in the queue for a few days,
2136a message will time out.
2137This is to insure that at least the sender is aware
2138of the inability to send a message.
2139The timeout is typically set to five days.
2140It is sometimes considered convenient to also send a warning message
2141if the message is in the queue longer than a few hours
2142(assuming you normally have good connectivity;
2143if your messages normally took several hours to send
2144you wouldn't want to do this because it wouldn't be an unusual event).
2145These timeouts are set using the
2146.b Timeout.queuereturn
2147and
2148.b Timeout.queuewarn
2149options in the configuration file
2150(previously both were set using the
2151.b T
2152option).
2153.pp
2154Since these options are global,
2155and since you can not know
2156.i "a priori"
2157how long another host outside your domain will be down,
2158a five day timeout is recommended.
2159This allows a recipient to fix the problem even if it occurs
2160at the beginning of a long weekend.
2161RFC 1123 section 5.3.1.1 says that this parameter
2162should be ``at least 4\-5 days''.
2163.pp
2164The
2165.b Timeout.queuewarn
2166value can be piggybacked on the
2167.b T
2168option by indicating a time after which
2169a warning message should be sent;
2170the two timeouts are separated by a slash.
2171For example, the line
2172.(b
2173OT5d/4h
2174.)b
2175causes email to fail after five days,
2176but a warning message will be sent after four hours.
2177This should be large enough that the message will have been tried
2178several times.
2179.sh 2 "Forking During Queue Runs"
2180.pp
2181By setting the
2182.b ForkEachJob
2183(\c
2184.b Y )
2185option,
2186.i sendmail
2187will fork before each individual message
2188while running the queue.
2189This will prevent
2190.i sendmail
2191from consuming large amounts of memory,
2192so it may be useful in memory-poor environments.
2193However, if the
2194.b ForkEachJob
2195option is not set,
2196.i sendmail
2197will keep track of hosts that are down during a queue run,
2198which can improve performance dramatically.
2199.pp
2200If the
2201.b ForkEachJob
2202option is set,
2203.i sendmail
2204can not use connection caching.
2205.sh 2 "Queue Priorities"
2206.pp
2207Every message is assigned a priority when it is first instantiated,
2208consisting of the message size (in bytes)
2209offset by the message class
2210(which is determined from the Precedence: header)
2211times the
2212.q "work class factor"
2213and the number of recipients times the
2214.q "work recipient factor."
2215The priority is used to order the queue.
2216Higher numbers for the priority mean that the message will be processed later
2217when running the queue.
2218.pp
2219The message size is included so that large messages are penalized
2220relative to small messages.
2221The message class allows users to send
2222.q "high priority"
2223messages by including a
2224.q Precedence:
2225field in their message;
2226the value of this field is looked up in the
2227.b P
2228lines of the configuration file.
2229Since the number of recipients affects the amount of load a message presents
2230to the system,
2231this is also included into the priority.
2232.pp
2233The recipient and class factors
2234can be set in the configuration file using the
2235.b RecipientFactor
2236(\c
2237.b y )
2238and
2239.b ClassFactor
2240(\c
2241.b z )
2242options respectively.
2243They default to 30000 (for the recipient factor)
2244and 1800
2245(for the class factor).
2246The initial priority is:
2247.EQ
2248pri = msgsize - (class times bold ClassFactor) + (nrcpt times bold RecipientFactor)
2249.EN
2250(Remember, higher values for this parameter actually mean
2251that the job will be treated with lower priority.)
2252.pp
2253The priority of a job can also be adjusted each time it is processed
2254(that is, each time an attempt is made to deliver it)
2255using the
2256.q "work time factor,"
2257set by the
2258.b RetryFactor
2259(\c
2260.b Z )
2261option.
2262This is added to the priority,
2263so it normally decreases the precedence of the job,
2264on the grounds that jobs that have failed many times
2265will tend to fail again in the future.
2266The
2267.b RetryFactor
2268option defaults to 90000.
2269.sh 2 "Load Limiting"
2270.pp
2271.i Sendmail
2272can be asked to queue (but not deliver)
2273mail if the system load average gets too high
2274using the
2275.b QueueLA
2276(\c
2277.b x )
2278option.
2279When the load average exceeds the value of the
2280.b QueueLA
2281option,
2282the delivery mode is set to
2283.b q
2284(queue only)
2285if the
2286.b QueueFactor
2287(\c
2288.b q )
2289option divided by the difference in the current load average and the
2290.b QueueLA
2291option
2292plus one
2293exceeds the priority of the message \(em
2294that is, the message is queued iff:
2295.EQ
2296pri > { bold QueueFactor } over { LA - { bold QueueLA } + 1 }
2297.EN
2298The
2299.b QueueFactor
2300option defaults to 600000,
2301so each point of load average is worth 600000
2302priority points
2303(as described above).
2304.pp
2305For drastic cases,
2306the
2307.b RefuseLA
2308(\c
2309.b X )
2310option defines a load average at which
2311.i sendmail
2312will refuse
2313to accept network connections.
2314Locally generated mail
2315(including incoming UUCP mail)
2316is still accepted.
2317.sh 2 "Delivery Mode"
2318.pp
2319There are a number of delivery modes that
2320.i sendmail
2321can operate in,
2322set by the
2323.b DeliveryMode
2324(\c
2325.b d )
2326configuration option.
2327These modes
2328specify how quickly mail will be delivered.
2329Legal modes are:
2330.(b
2331.ta 4n
2332i deliver interactively (synchronously)
2333b deliver in background (asynchronously)
2334q queue only (don't deliver)
2335d defer delvery attempts (don't deliver)
2336.)b
2337There are tradeoffs.
2338Mode
2339.q i
2340gives the sender the quickest feedback,
2341but may slow down some mailers and
2342is hardly ever necessary.
2343Mode
2344.q b
2345delivers promptly but
2346can cause large numbers of processes
2347if you have a mailer that takes a long time to deliver a message.
2348Mode
2349.q q
2350minimizes the load on your machine,
2351but means that delivery may be delayed for up to the queue interval.
2352Mode
2353.q d
2354is identical to mode
2355.q q
2356except that it also prevents all the early map lookups from working;
2357it is intended for ``dial on demand'' sites where DNS lookups
2358might cost real money.
2359Some simple error messages
2360(e.g., host unknown during the SMTP protocol)
2361will be delayed using this mode.
2362Mode
2363.q b
2364is the usual default.
2365.pp
2366If you run in mode
2367.q q
2368(queue only),
2369.q d
2370(defer),
2371or
2372.q b
2373(deliver in background)
2374.i sendmail
2375will not expand aliases and follow .forward files
2376upon initial receipt of the mail.
2377This speeds up the response to RCPT commands.
2378Mode
2379.q i
2380cannot be used by the SMTP server.
2381.sh 2 "Log Level"
2382.pp
2383The level of logging can be set for
2384.i sendmail .
2385The default using a standard configuration table is level 9.
2386The levels are as follows:
2387.nr ii 0.5i
2388.ip 0
2389Minimal logging.
2390.ip 1
2391Serious system failures and potential security problems.
2392.ip 2
2393Lost communications (network problems) and protocol failures.
2394.ip 3
2395Other serious failures, malformed addresses, transient forward/include
2396errors, connection timeouts.
2397.ip 4
2398Minor failures, out of date alias databases, connection rejections
2399via check_ rulesets.
2400.ip 5
2401Message collection statistics.
2402.ip 6
2403Creation of error messages,
2404VRFY and EXPN commands.
2405.ip 7
2406Delivery failures (host or user unknown, etc.).
2407.ip 8
2408Successful deliveries and alias database rebuilds.
2409.ip 9
2410Messages being deferred
2411(due to a host being down, etc.).
2412.ip 10
2413Database expansion (alias, forward, and userdb lookups).
2414.ip 11
2415NIS errors and end of job processing.
2416.ip 12
2417Logs all SMTP connections.
2418.ip 13
2419Log bad user shells, files with improper permissions, and other
2420questionable situations.
2421.ip 14
2422Logs refused connections.
2423.ip 15
2424Log all incoming and outgoing SMTP commands.
2425.ip 20
2426Logs attempts to run locked queue files.
2427These are not errors,
2428but can be useful to note if your queue appears to be clogged.
2429.ip 30
2430Lost locks (only if using lockf instead of flock).
2431.lp
2432Additionally,
2433values above 64 are reserved for extremely verbose debugging output.
2434No normal site would ever set these.
2435.sh 2 "File Modes"
2436.pp
2437The modes used for files depend on what functionality you want
2438and the level of security you require.
2439In many cases
2440.i sendmail
2441does careful checking of the modes
2442of files and directories
2443to avoid accidental compromise;
2444if you want to make it possible to have group-writable support files
2445you may need to use the
2446.b DontBlameSendmail
2447option to turn off some of these checks.
2448.sh 3 "To suid or not to suid?"
2449.pp
2450.i Sendmail
2451is normally installed
2452setuid to root.
2453At the point where it is about to
2454.i exec \|(2)
2455a mailer,
2456it checks to see if the userid is zero (root);
2457if so,
2458it resets the userid and groupid to a default
2459(set by the
2460.b U=
2461equate in the mailer line;
2462if that is not set, the
2463.b DefaultUser
2464option is used).
2465This can be overridden
2466by setting the
2467.b S
2468flag to the mailer
2469for mailers that are trusted
2470and must be called as root.
2471However,
2472this will cause mail processing
2473to be accounted
2474(using
2475.i sa \|(8))
2476to root
2477rather than to the user sending the mail.
2478.pp
2479If you don't make
2480.i sendmail
2481setuid to root, it will still run but you lose a lot of functionality
2482and a lot of privacy, since you'll have to make the queue directory
2483world readable.
2484You could also make
2485.i sendmail
2486setuid to some pseudo-user
2487(e.g., create a user called
2488.q sendmail
2489and make
2490.i sendmail
2491setuid to that)
2492which will fix the privacy problems
2493but not the functionality issues.
2494Also, this isn't a guarantee of security:
2495for example,
2496root occasionally sends mail,
2497and the daemon often runs as root.
2498Note however that
2499.i sendmail
2500must run as root in order to create the SMTP listener socket.
2501.pp
2502A middle ground is to make
2503.i sendmail
2504setuid to root,
2505but set the
2506.b RunAsUser
2507option.
2508This causes
2509.i sendmail
2510to become the indicated user as soon as it has done the startup
2511that requires root privileges
2512(primarily, opening the
2513.sm SMTP
2514socket).
2515If you use
2516.b RunAsUser ,
2517the queue directory
2518(normally
2519.i /var/spool/mqueue )
2520should be owned by that user,
2521and all files and databases
2522(including user
2523.i \&.forward
2524files,
2525alias files,
2526:include: files,
2527and external databases)
2528must be readable by that user.
2529.b RunAsUser
2530is probably best suited for firewall configurations
2531that don't have regular user logins.
2532.sh 3 "Turning off security checks"
2533.pp
2534.i Sendmail
2535is very particular about the modes of files that it reads or writes.
2536For example, by default it will refuse to read most files
2537that are group writable
2538on the grounds that they might have been tampered with
2539by someone other than the owner;
2540it will even refuse to read files in group writable directories.
2541.pp
2542If you are
2543.i quite
2544sure that your configuration is safe and you want
2545.i sendmail
2546to avoid these security checks,
2547you can turn off certain checks using the
2548.b DontBlameSendmail
2549option.
2550This option takes one or more names that disable checks.
2551In the descriptions that follow,
2552.q "unsafe directory"
2553means a directory that is writable by anyone other than the owner.
2554The values are:
2555.nr ii 0.5i
2556.ip Safe
2557No special handling.
2558.ip AssumeSafeChown
2559Assume that the
2560.i chown
2561system call is restricted to root.
2562Since some versions of Unix permit regular users
2563to give away their files to other users on some filesystems,
2564.i sendmail
2565often cannot assume that a given file was created by the owner,
2566particularly when it is in a writable directory.
2567You can set this flag if you know that file giveaway is restricted
2568on your system.
2569.ip ClassFileInUnsafeDirPath
2570When reading class files (using the
2571.b F
2572line in the configuration file),
2573allow files that are in unsafe directories.
2574.ip ErrorHeaderInUnsafeDirPath
2575Allow the file named in the
2576.b ErrorHeader
2577option to be in an unsafe directory.
2578.ip GroupWritableDirPathSafe
2579Change the definition of
2580.q "unsafe directory"
2581to consider group-writable directories to be safe.
2582World-writable directories are always unsafe.
2583.ip GroupWritableForwardFileSafe
2584Accept group-writable
2585.i \&.forward
2586files.
2587.ip GroupWritableIncludeFileSafe
2588Accept group-writable
2589.i :include:
2590files.
2591.ip GroupWritableAliasFile
2592Allow group-writable alias files.
2593.ip HelpFileInUnsafeDirPath
2594Allow the file named in the
2595.b HelpFile
2596option to be in an unsafe directory.
2597.ip WorldWritableAliasFile
2598Accept world-writable alias files.
2599.ip ForwardFileInGroupWritableDirPath
2600Allow
2601.i \&.forward
2602files in group writable directories.
2603.ip IncludeFileInGroupWritableDirPath
2604Allow
2605.i :include:
2606files in group writable directories.
2607.ip ForwardFileInUnsafeDirPath
2608Allow
2609.i \&.forward
2610files in unsafe directories.
2611.ip IncludeFileInUnsafeDirPath
2612Allow
2613.i :include:
2614files in unsafe directories.
2615.ip ForwardFileInUnsafeDirPathSafe
2616Allow a
2617.i \&.forward
2618file that is in an unsafe directory to include references
2619to program and files.
2620.ip IncludeFileInUnsafeDirPathSafe
2621Allow a
2622.i :include:
2623file that is in an unsafe directory to include references
2624to program and files.
2625.ip MapInUnsafeDirPath
2626Allow maps (e.g.,
2627.i hash ,
2628.i btree ,
2629and
2630.i dbm
2631files)
2632in unsafe directories.
2633.ip LinkedAliasFileInWritableDir
2634Allow an alias file that is a link in a writable directory.
2635.ip LinkedClassFileInWritableDir
2636Allow class files that are links in writable directories.
2637.ip LinkedForwardFileInWritableDir
2638Allow
2639.i \&.forward
2640files that are links in writable directories.
2641.ip LinkedIncludeFileInWritableDir
2642Allow
2643.i :include:
2644files that are links in writable directories.
2645.ip LinkedMapInWritableDir
2646Allow map files that are links in writable directories.
2647.ip LinkedServiceSwitchFileInWritableDir
2648Allow the service switch file to be a link
2649even if the directory is writable.
2650.ip FileDeliveryToHardLink
2651Allow delivery to files that are hard links.
2652.ip FileDeliveryToSymLink
2653Allow delivery to files that are symbolic links.
2654.ip RunProgramInUnsafeDirPath
2655Go ahead and run programs that are in writable directories.
2656.ip RunWritableProgram
2657Go ahead and run programs that are group- or world-writable.
2658.ip WriteMapToHardLink
2659Allow writes to maps that are hard links.
2660.ip WriteMapToSymLink
2661Allow writes to maps that are symbolic links.
2662.ip WriteStatsToHardLink
2663Allow the status file to be a hard link.
2664.ip WriteStatsToSymLink
2665Allow the status file to be a symbolic link.
2666.sh 2 "Connection Caching"
2667.pp
2668When processing the queue,
2669.i sendmail
2670will try to keep the last few open connections open
2671to avoid startup and shutdown costs.
2672This only applies to IPC connections.
2673.pp
2674When trying to open a connection
2675the cache is first searched.
2676If an open connection is found, it is probed to see if it is still active
2677by sending a
2678.sm RSET
2679command.
2680It is not an error if this fails;
2681instead, the connection is closed and reopened.
2682.pp
2683Two parameters control the connection cache.
2684The
2685.b ConnectionCacheSize
2686(\c
2687.b k )
2688option defines the number of simultaneous open connections
2689that will be permitted.
2690If it is set to zero,
2691connections will be closed as quickly as possible.
2692The default is one.
2693This should be set as appropriate for your system size;
2694it will limit the amount of system resources that
2695.i sendmail
2696will use during queue runs.
2697Never set this higher than 4.
2698.pp
2699The
2700.b ConnectionCacheTimeout
2701(\c
2702.b K )
2703option specifies the maximum time that any cached connection
2704will be permitted to idle.
2705When the idle time exceeds this value
2706the connection is closed.
2707This number should be small
2708(under ten minutes)
2709to prevent you from grabbing too many resources
2710from other hosts.
2711The default is five minutes.
2712.sh 2 "Name Server Access"
2713.pp
2714Control of host address lookups is set by the
2715.b hosts
2716service entry in your service switch file.
2717If you are on a system that has built-in service switch support
2718(e.g., Ultrix, Solaris, or DEC OSF/1)
2719then your system is probably configured properly already.
2720Otherwise,
2721.i sendmail
2722will consult the file
2723.b /etc/service.switch ,
2724which should be created.
2725.i Sendmail
2726only uses two entries:
2727.b hosts
2728and
2729.b aliases ,
2730although system routines may use other services
2731(notably the
2732.b passwd
2733service for user name lookups by
2734.i getpwname ).
2735.pp
2736However, some systems (such as SunOS 4.X)
2737will do DNS lookups
2738regardless of the setting of the service switch entry.
2739In particular, the system routine
2740.i gethostbyname (3)
2741is used to look up host names,
2742and many vendor versions try some combination of DNS, NIS,
2743and file lookup in /etc/hosts
2744without consulting a service switch.
2745.i Sendmail
2746makes no attempt to work around this problem,
2747and the DNS lookup will be done anyway.
2748If you do not have a nameserver configured at all,
2749such as at a UUCP-only site,
2750.i sendmail
2751will get a
2752.q "connection refused"
2753message when it tries to connect to the name server.
2754If the
2755.b hosts
2756switch entry has the service
2757.q dns
2758listed somewhere in the list,
2759.i sendmail
2760will interpret this to mean a temporary failure
2761and will queue the mail for later processing;
2762otherwise, it ignores the name server data.
2763.pp
2764The same technique is used to decide whether to do MX lookups.
2765If you want MX support, you
2766.i must
2767have
2768.q dns
2769listed as a service in the
2770.b hosts
2771switch entry.
2772.pp
2773The
2774.b ResolverOptions
2775(\c
2776.b I )
2777option allows you to tweak name server options.
2778The command line takes a series of flags as documented in
2779.i resolver (3)
2780(with the leading
2781.q RES_
2782deleted).
2783Each can be preceded by an optional `+' or `\(mi'.
2784For example, the line
2785.(b
2786O ResolverOptions=+AAONLY \(miDNSRCH
2787.)b
2788turns on the AAONLY (accept authoritative answers only)
2789and turns off the DNSRCH (search the domain path) options.
2790Most resolver libraries default DNSRCH, DEFNAMES, and RECURSE
2791flags on and all others off.
2792You can also include
2793.q HasWildcardMX
2794to specify that there is a wildcard MX record matching your domain;
2795this turns off MX matching when canonifying names,
2796which can lead to inappropriate canonifications.
2797.pp
2798Version level 1 configurations
2799turn DNSRCH and DEFNAMES off when doing delivery lookups,
2800but leave them on everywhere else.
2801Version 8 of
2802.i sendmail
2803ignores them when doing canonification lookups
2804(that is, when using $[ ... $]),
2805and always does the search.
2806If you don't want to do automatic name extension,
2807don't call $[ ... $].
2808.pp
2809The search rules for $[ ... $] are somewhat different than usual.
2810If the name being looked up
2811has at least one dot, it always tries the unmodified name first.
2812If that fails, it tries the reduced search path,
2813and lastly tries the unmodified name
2814(but only for names without a dot,
2815since names with a dot have already been tried).
2816This allows names such as
2817``utc.CS''
2818to match the site in Czechoslovakia
2819rather than the site in your local Computer Science department.
2820It also prefers A and CNAME records over MX records \*-
2821that is, if it finds an MX record it makes note of it,
2822but keeps looking.
2823This way, if you have a wildcard MX record matching your domain,
2824it will not assume that all names match.
2825.pp
2826To completely turn off all name server access
2827on systems without service switch support
2828(such as SunOS 4.X)
2829you will have to recompile with
2830\-DNAMED_BIND=0
2831and remove \-lresolv from the list of libraries to be searched
2832when linking.
2833.sh 2 "Moving the Per-User Forward Files"
2834.pp
2835Some sites mount each user's home directory
2836from a local disk on their workstation,
2837so that local access is fast.
2838However, the result is that .forward file lookups are slow.
2839In some cases,
2840mail can even be delivered on machines inappropriately
2841because of a file server being down.
2842The performance can be especially bad if you run the automounter.
2843.pp
2844The
2845.b ForwardPath
2846(\c
2847.b J )
2848option allows you to set a path of forward files.
2849For example, the config file line
2850.(b
2851O ForwardPath=/var/forward/$u:$z/.forward.$w
2852.)b
2853would first look for a file with the same name as the user's login
2854in /var/forward;
2855if that is not found (or is inaccessible)
2856the file
2857``.forward.\c
2858.i machinename ''
2859in the user's home directory is searched.
2860A truly perverse site could also search by sender
2861by using $r, $s, or $f.
2862.pp
2863If you create a directory such as /var/forward,
2864it should be mode 1777
2865(that is, the sticky bit should be set).
2866Users should create the files mode 644.
2867Note that you must use the
2868forwardfileinunsafedirpath and
2869forwardfileinunsafedirpathsafe
2870flags with the DontBlameSendmail option
2871to allow forward files in a world
2872writable directory.
| 816.)b
817This file does not grow.
818It is printed with the program
819.q mailstats/mailstats.c.
820The actual path of this file
821is defined in the
822.b S
823option of the
824.i sendmail.cf
825file.
826.sh 3 "/usr/\*(SB/mailq"
827.pp
828If
829.i sendmail
830is invoked as
831.q mailq,
832it will simulate the
833.b \-bp
834flag
835(i.e.,
836.i sendmail
837will print the contents of the mail queue;
838see below).
839This should be a link to /usr/\*(SD/sendmail.
840.sh 1 "NORMAL OPERATIONS"
841.sh 2 "The System Log"
842.pp
843The system log is supported by the
844.i syslogd \|(8)
845program.
846All messages from
847.i sendmail
848are logged under the
849.sm LOG_MAIL
850facility\**.
851.(f
852\**Except on Ultrix,
853which does not support facilities in the syslog.
854.)f
855.sh 3 "Format"
856.pp
857Each line in the system log
858consists of a timestamp,
859the name of the machine that generated it
860(for logging from several machines
861over the local area network),
862the word
863.q sendmail: ,
864and a message\**.
865.(f
866\**This format may vary slightly if your vendor has changed
867the syntax.
868.)f
869Most messages are a sequence of
870.i name \c
871=\c
872.i value
873pairs.
874.pp
875The two most common lines are logged when a message is processed.
876The first logs the receipt of a message;
877there will be exactly one of these per message.
878Some fields may be omitted if they do not contain interesting information.
879Fields are:
880.ip from
881The envelope sender address.
882.ip size
883The size of the message in bytes.
884.ip class
885The class (i.e., numeric precedence) of the message.
886.ip pri
887The initial message priority (used for queue sorting).
888.ip nrcpts
889The number of envelope recipients for this message
890(after aliasing and forwarding).
891.ip msgid
892The message id of the message (from the header).
893.ip proto
894The protocol used to receive this message (e.g., ESMTP or UUCP)
895.ip relay
896The machine from which it was received.
897.lp
898There is also one line logged per delivery attempt
899(so there can be several per message if delivery is deferred
900or there are multiple recipients).
901Fields are:
902.ip to
903A comma-separated list of the recipients to this mailer.
904.ip ctladdr
905The ``controlling user'', that is, the name of the user
906whose credentials we use for delivery.
907.ip delay
908The total delay between the time this message was received
909and the time it was delivered.
910.ip xdelay
911The amount of time needed in this delivery attempt
912(normally indicative of the speed of the connection).
913.ip mailer
914The name of the mailer used to deliver to this recipient.
915.ip relay
916The name of the host that actually accepted (or rejected) this recipient.
917.ip stat
918The delivery status.
919.lp
920Not all fields are present in all messages;
921for example, the relay is not listed for local deliveries.
922.sh 3 "Levels"
923.pp
924If you have
925.i syslogd \|(8)
926or an equivalent installed,
927you will be able to do logging.
928There is a large amount of information that can be logged.
929The log is arranged as a succession of levels.
930At the lowest level
931only extremely strange situations are logged.
932At the highest level,
933even the most mundane and uninteresting events
934are recorded for posterity.
935As a convention,
936log levels under ten
937are considered generally
938.q useful;
939log levels above 64
940are reserved for debugging purposes.
941Levels from 11\-64 are reserved for verbose information
942that some sites might want.
943.pp
944A complete description of the log levels
945is given in section
946.\" XREF
9474.6.
948.sh 2 "Dumping State"
949.pp
950You can ask
951.i sendmail
952to log a dump of the open files
953and the connection cache
954by sending it a
955.sm SIGUSR1
956signal.
957The results are logged at
958.sm LOG_DEBUG
959priority.
960.sh 2 "The Mail Queue"
961.pp
962Sometimes a host cannot handle a message immediately.
963For example, it may be down or overloaded, causing it to refuse connections.
964The sending host is then expected to save this message in
965its mail queue
966and attempt to deliver it later.
967.pp
968Under normal conditions the mail queue will be processed transparently.
969However, you may find that manual intervention is sometimes necessary.
970For example,
971if a major host is down for a period of time
972the queue may become clogged.
973Although
974.i sendmail
975ought to recover gracefully when the host comes up,
976you may find performance unacceptably bad in the meantime.
977.sh 3 "Printing the queue"
978.pp
979The contents of the queue can be printed
980using the
981.i mailq
982command
983(or by specifying the
984.b \-bp
985flag to
986.i sendmail ):
987.(b
988mailq
989.)b
990This will produce a listing of the queue id's,
991the size of the message,
992the date the message entered the queue,
993and the sender and recipients.
994.sh 3 "Forcing the queue"
995.pp
996.i Sendmail
997should run the queue automatically
998at intervals.
999The algorithm is to read and sort the queue,
1000and then to attempt to process all jobs in order.
1001When it attempts to run the job,
1002.i sendmail
1003first checks to see if the job is locked.
1004If so, it ignores the job.
1005.pp
1006There is no attempt to insure that only one queue processor
1007exists at any time,
1008since there is no guarantee that a job cannot take forever
1009to process
1010(however,
1011.i sendmail
1012does include heuristics to try to abort jobs
1013that are taking absurd amounts of time;
1014technically, this violates RFC 821, but is blessed by RFC 1123).
1015Due to the locking algorithm,
1016it is impossible for one job to freeze the entire queue.
1017However,
1018an uncooperative recipient host
1019or a program recipient
1020that never returns
1021can accumulate many processes in your system.
1022Unfortunately,
1023there is no completely general way to solve this.
1024.pp
1025In some cases,
1026you may find that a major host going down
1027for a couple of days
1028may create a prohibitively large queue.
1029This will result in
1030.i sendmail
1031spending an inordinate amount of time
1032sorting the queue.
1033This situation can be fixed by moving the queue to a temporary place
1034and creating a new queue.
1035The old queue can be run later when the offending host returns to service.
1036.pp
1037To do this,
1038it is acceptable to move the entire queue directory:
1039.(b
1040cd /var/spool
1041mv mqueue omqueue; mkdir mqueue; chmod 700 mqueue
1042.)b
1043You should then kill the existing daemon
1044(since it will still be processing in the old queue directory)
1045and create a new daemon.
1046.pp
1047To run the old mail queue,
1048run the following command:
1049.(b
1050/usr/\*(SD/sendmail \-oQ/var/spool/omqueue \-q
1051.)b
1052The
1053.b \-oQ
1054flag specifies an alternate queue directory
1055and the
1056.b \-q
1057flag says to just run every job in the queue.
1058If you have a tendency toward voyeurism,
1059you can use the
1060.b \-v
1061flag to watch what is going on.
1062.pp
1063When the queue is finally emptied,
1064you can remove the directory:
1065.(b
1066rmdir /var/spool/omqueue
1067.)b
1068.sh 2 "Disk Based Connection Information"
1069.pp
1070.i Sendmail
1071stores a large amount of information about each remote system it
1072has connected to in memory. It is now possible to preserve some
1073of this information on disk as well, by using the
1074.b HostStatusDirectory
1075option, so that it may be shared between several invocations of
1076.i sendmail .
1077This allows mail to be queued immediately or skipped during a queue run if
1078there has been a recent failure in connecting to a remote machine.
1079.pp
1080Additionally enabling
1081.b SingleThreadDelivery
1082has the added effect of single-threading mail delivery to a destination.
1083This can be quite helpful
1084if the remote machine is running an SMTP server that is easily overloaded
1085or cannot accept more than a single connection at a time,
1086but can cause some messages to be punted to a future queue run.
1087It also applies to
1088.i all
1089hosts, so setting this because you have one machine on site
1090that runs some software that is easily overrun
1091can cause mail to other hosts to be slowed down.
1092If this option is set,
1093you probably want to set the
1094.b MinQueueAge
1095option as well and run the queue fairly frequently;
1096this way jobs that are skipped because another
1097.i sendmail
1098is talking to the same host will be tried again quickly
1099rather than being delayed for a long time.
1100.pp
1101The disk based host information is stored in a subdirectory of the
1102.b mqueue
1103directory called
1104.b \&.hoststat \**.
1105.(f
1106\**This is the usual value of the
1107.b HostStatusDirectory
1108option;
1109it can, of course, go anywhere you like in your filesystem.
1110.)f
1111Removing this directory and its subdirectories has an effect similar to
1112the
1113.i purgestat
1114command and is completely safe.
1115The information in these directories can
1116be perused with the
1117.i hoststat
1118command, which will indicate the host name, the last access, and the
1119status of that access.
1120An asterisk in the left most column indicates that a
1121.i sendmail
1122process currently has the host locked for mail delivery.
1123.pp
1124The disk based connection information is treated the same way as memory based
1125connection information for the purpose of timeouts.
1126By default, information about host failures is valid for 30 minutes.
1127This can be adjusted with
1128the
1129.b Timeout.hoststatus
1130option.
1131.pp
1132The connection information stored on disk may be purged at any time
1133with the
1134.i purgestat
1135command or by invoking sendmail with the
1136.b \-bH
1137switch.
1138The connection information may be viewed with the
1139.i hoststat
1140command or by invoking sendmail with the
1141.b \-bh
1142switch.
1143.sh 2 "The Service Switch"
1144.pp
1145The implementation of certain system services
1146such as host and user name lookup
1147is controlled by the service switch.
1148If the host operating system supports such a switch
1149.i sendmail
1150will use the native version.
1151Ultrix, Solaris, and DEC OSF/1 are examples of such systems\**.
1152.(f
1153\**HP-UX 10 has service switch support,
1154but since the APIs are apparently not available in the libraries
1155.i sendmail
1156does not use the native service switch in this release.
1157.)f
1158.pp
1159If the underlying operating system does not support a service switch
1160(e.g., SunOS 4.X, HP-UX, BSD)
1161then
1162.i sendmail
1163will provide a stub implementation.
1164The
1165.b ServiceSwitchFile
1166option points to the name of a file that has the service definitions.
1167Each line has the name of a service
1168and the possible implementations of that service.
1169For example, the file:
1170.(b
1171hosts dns files nis
1172aliases files nis
1173.)b
1174will ask
1175.i sendmail
1176to look for hosts in the Domain Name System first.
1177If the requested host name is not found,
1178it tries local files,
1179and if that fails it tries NIS.
1180Similarly,
1181when looking for aliases
1182it will try the local files first
1183followed by NIS.
1184.pp
1185Service switches are not completely integrated.
1186For example, despite the fact that the host entry listed in the above example
1187specifies to look in NIS,
1188on SunOS this won't happen because the system implementation of
1189.i gethostbyname \|(3)
1190doesn't understand this.
1191If there is enough demand
1192.i sendmail
1193may reimplement
1194.i gethostbyname \|(3),
1195.i gethostbyaddr \|(3),
1196.i getpwent \|(3),
1197and the other system routines that would be necessary
1198to make this work seamlessly.
1199.sh 2 "The Alias Database"
1200.pp
1201After recipient addresses are read from the SMTP connection
1202or command line
1203they are parsed by ruleset 0,
1204which must resolve to a
1205{\c
1206.i mailer ,
1207.i host ,
1208.i user }
1209triple.
1210If the flags selected by the
1211.i mailer
1212include the
1213.b A
1214(aliasable) flag,
1215the
1216.i user
1217part of the triple is looked up as the key
1218(i.e., the left hand side)
1219into the alias database.
1220If there is a match, the address is deleted from the send queue
1221and all addresses on the right hand side of the alias
1222are added in place of the alias that was found.
1223This is a recursive operation,
1224so aliases found in the right hand side of the alias
1225are similarly expanded.
1226.pp
1227The alias database exists in two forms.
1228One is a text form,
1229maintained in the file
1230.i /etc/aliases.
1231The aliases are of the form
1232.(b
1233name: name1, name2, ...
1234.)b
1235Only local names may be aliased;
1236e.g.,
1237.(b
1238eric@prep.ai.MIT.EDU: eric@CS.Berkeley.EDU
1239.)b
1240will not have the desired effect
1241(except on prep.ai.MIT.EDU,
1242and they probably don't want me)\**.
1243.(f
1244\**Actually, any mailer that has the `A' mailer flag set
1245will permit aliasing;
1246this is normally limited to the local mailer.
1247.)f
1248Aliases may be continued by starting any continuation lines
1249with a space or a tab.
1250Blank lines and lines beginning with a sharp sign
1251(\c
1252.q # )
1253are comments.
1254.pp
1255The second form is processed by the
1256.i ndbm \|(3)\**
1257.(f
1258\**The
1259.i gdbm
1260package does not work.
1261.)f
1262or the Berkeley DB library.
1263This form is in the file
1264.i /etc/aliases.db
1265(if using NEWDB)
1266or
1267.i /etc/aliases.dir
1268and
1269.i /etc/aliases.pag
1270(if using NDBM).
1271This is the form that
1272.i sendmail
1273actually uses to resolve aliases.
1274This technique is used to improve performance.
1275.pp
1276The control of search order is actually set by the service switch.
1277Essentially, the entry
1278.(b
1279O AliasFile=switch:aliases
1280.)b
1281is always added as the first alias entry;
1282also, the first alias file name without a class
1283(e.g., without
1284.q nis:
1285on the front)
1286will be used as the name of the file for a ``files'' entry
1287in the aliases switch.
1288For example, if the configuration file contains
1289.(b
1290O AliasFile=/etc/aliases
1291.)b
1292and the service switch contains
1293.(b
1294aliases nis files nisplus
1295.)b
1296then aliases will first be searched in the NIS database,
1297then in /etc/aliases,
1298then in the NIS+ database.
1299.pp
1300You can also use
1301.sm NIS -based
1302alias files.
1303For example, the specification:
1304.(b
1305O AliasFile=/etc/aliases
1306O AliasFile=nis:mail.aliases@my.nis.domain
1307.)b
1308will first search the /etc/aliases file
1309and then the map named
1310.q mail.aliases
1311in
1312.q my.nis.domain .
1313Warning: if you build your own
1314.sm NIS -based
1315alias files,
1316be sure to provide the
1317.b \-l
1318flag to
1319.i makedbm (8)
1320to map upper case letters in the keys to lower case;
1321otherwise, aliases with upper case letters in their names
1322won't match incoming addresses.
1323.pp
1324Additional flags can be added after the colon
1325exactly like a
1326.b K
1327line \(em for example:
1328.(b
1329O AliasFile=nis:\-N mail.aliases@my.nis.domain
1330.)b
1331will search the appropriate NIS map and always include null bytes in the key.
1332Also:
1333.(b
1334O AliasFile=nis:\-f mail.aliases@my.nis.domain
1335.)b
1336will prevent sendmail from downcasing the key before the alias lookup.
1337.sh 3 "Rebuilding the alias database"
1338.pp
1339The
1340.i hash
1341or
1342.i dbm
1343version of the database
1344may be rebuilt explicitly by executing the command
1345.(b
1346newaliases
1347.)b
1348This is equivalent to giving
1349.i sendmail
1350the
1351.b \-bi
1352flag:
1353.(b
1354/usr/\*(SD/sendmail \-bi
1355.)b
1356.pp
1357If the
1358.b RebuildAliases
1359(old
1360.b D )
1361option is specified in the configuration,
1362.i sendmail
1363will rebuild the alias database automatically
1364if possible
1365when it is out of date.
1366Auto-rebuild can be dangerous
1367on heavily loaded machines
1368with large alias files;
1369if it might take more than the rebuild timeout
1370(option
1371.b AliasWait ,
1372old
1373.b a ,
1374which is normally five minutes)
1375to rebuild the database,
1376there is a chance that several processes will start the rebuild process
1377simultaneously.
1378.pp
1379If you have multiple aliases databases specified,
1380the
1381.b \-bi
1382flag rebuilds all the database types it understands
1383(for example, it can rebuild NDBM databases but not NIS databases).
1384.sh 3 "Potential problems"
1385.pp
1386There are a number of problems that can occur
1387with the alias database.
1388They all result from a
1389.i sendmail
1390process accessing the DBM version
1391while it is only partially built.
1392This can happen under two circumstances:
1393One process accesses the database
1394while another process is rebuilding it,
1395or the process rebuilding the database dies
1396(due to being killed or a system crash)
1397before completing the rebuild.
1398.pp
1399Sendmail has three techniques to try to relieve these problems.
1400First, it ignores interrupts while rebuilding the database;
1401this avoids the problem of someone aborting the process
1402leaving a partially rebuilt database.
1403Second,
1404it locks the database source file during the rebuild \(em
1405but that may not work over NFS or if the file is unwritable.
1406Third,
1407at the end of the rebuild
1408it adds an alias of the form
1409.(b
1410@: @
1411.)b
1412(which is not normally legal).
1413Before
1414.i sendmail
1415will access the database,
1416it checks to insure that this entry exists\**.
1417.(f
1418\**The
1419.b AliasWait
1420option is required in the configuration
1421for this action to occur.
1422This should normally be specified.
1423.)f
1424.sh 3 "List owners"
1425.pp
1426If an error occurs on sending to a certain address,
1427say
1428.q \fIx\fP ,
1429.i sendmail
1430will look for an alias
1431of the form
1432.q owner-\fIx\fP
1433to receive the errors.
1434This is typically useful
1435for a mailing list
1436where the submitter of the list
1437has no control over the maintenance of the list itself;
1438in this case the list maintainer would be the owner of the list.
1439For example:
1440.(b
1441unix-wizards: eric@ucbarpa, wnj@monet, nosuchuser,
1442 sam@matisse
1443owner-unix-wizards: unix-wizards-request
1444unix-wizards-request: eric@ucbarpa
1445.)b
1446would cause
1447.q eric@ucbarpa
1448to get the error that will occur
1449when someone sends to
1450unix-wizards
1451due to the inclusion of
1452.q nosuchuser
1453on the list.
1454.pp
1455List owners also cause the envelope sender address to be modified.
1456The contents of the owner alias are used if they point to a single user,
1457otherwise the name of the alias itself is used.
1458For this reason, and to obey Internet conventions,
1459the
1460.q owner-
1461address normally points at the
1462.q -request
1463address; this causes messages to go out with the typical Internet convention
1464of using ``\c
1465.i list -request''
1466as the return address.
1467.sh 2 "User Information Database"
1468.pp
1469If you have a version of
1470.i sendmail
1471with the user information database
1472compiled in,
1473and you have specified one or more databases using the
1474.b U
1475option,
1476the databases will be searched for a
1477.i user :maildrop
1478entry.
1479If found, the mail will be sent to the specified address.
1480.sh 2 "Per-User Forwarding (.forward Files)"
1481.pp
1482As an alternative to the alias database,
1483any user may put a file with the name
1484.q .forward
1485in his or her home directory.
1486If this file exists,
1487.i sendmail
1488redirects mail for that user
1489to the list of addresses listed in the .forward file.
1490For example, if the home directory for user
1491.q mckusick
1492has a .forward file with contents:
1493.(b
1494mckusick@ernie
1495kirk@calder
1496.)b
1497then any mail arriving for
1498.q mckusick
1499will be redirected to the specified accounts.
1500.pp
1501Actually, the configuration file defines a sequence of filenames to check.
1502By default, this is the user's .forward file,
1503but can be defined to be more generally using the
1504.b ForwardPath
1505option.
1506If you change this,
1507you will have to inform your user base of the change;
1508\&.forward is pretty well incorporated into the collective subconscious.
1509.sh 2 "Special Header Lines"
1510.pp
1511Several header lines have special interpretations
1512defined by the configuration file.
1513Others have interpretations built into
1514.i sendmail
1515that cannot be changed without changing the code.
1516These builtins are described here.
1517.sh 3 "Errors-To:"
1518.pp
1519If errors occur anywhere during processing,
1520this header will cause error messages to go to
1521the listed addresses.
1522This is intended for mailing lists.
1523.pp
1524The Errors-To: header was created in the bad old days
1525when UUCP didn't understand the distinction between an envelope and a header;
1526this was a hack to provide what should now be passed
1527as the envelope sender address.
1528It should go away.
1529It is only used if the
1530.b UseErrorsTo
1531option is set.
1532.pp
1533The Errors-To: header is officially deprecated
1534and will go away in a future release.
1535.sh 3 "Apparently-To:"
1536.pp
1537RFC 822 requires at least one recipient field
1538(To:, Cc:, or Bcc: line)
1539in every message.
1540If a message comes in with no recipients listed in the message
1541then
1542.i sendmail
1543will adjust the header based on the
1544.q NoRecipientAction
1545option.
1546One of the possible actions is to add an
1547.q "Apparently-To:"
1548header line for any recipients it is aware of.
1549.pp
1550The Apparently-To: header is non-standard
1551and is deprecated.
1552.sh 3 "Precedence"
1553.pp
1554The Precedence: header can be used as a crude control of message priority.
1555It tweaks the sort order in the queue
1556and can be configured to change the message timeout values.
1557.sh 2 "IDENT Protocol Support"
1558.pp
1559.i Sendmail
1560supports the IDENT protocol as defined in RFC 1413.
1561Although this enhances identification
1562of the author of an email message
1563by doing a ``call back'' to the originating system to include
1564the owner of a particular TCP connection
1565in the audit trail
1566it is in no sense perfect;
1567a determined forger can easily spoof the IDENT protocol.
1568The following description is excerpted from RFC 1413:
1569.ba +5
1570.lp
15716. Security Considerations
1572.lp
1573The information returned by this protocol is at most as trustworthy
1574as the host providing it OR the organization operating the host. For
1575example, a PC in an open lab has few if any controls on it to prevent
1576a user from having this protocol return any identifier the user
1577wants. Likewise, if the host has been compromised the information
1578returned may be completely erroneous and misleading.
1579.lp
1580The Identification Protocol is not intended as an authorization or
1581access control protocol. At best, it provides some additional
1582auditing information with respect to TCP connections. At worst, it
1583can provide misleading, incorrect, or maliciously incorrect
1584information.
1585.lp
1586The use of the information returned by this protocol for other than
1587auditing is strongly discouraged. Specifically, using Identification
1588Protocol information to make access control decisions - either as the
1589primary method (i.e., no other checks) or as an adjunct to other
1590methods may result in a weakening of normal host security.
1591.lp
1592An Identification server may reveal information about users,
1593entities, objects or processes which might normally be considered
1594private. An Identification server provides service which is a rough
1595analog of the CallerID services provided by some phone companies and
1596many of the same privacy considerations and arguments that apply to
1597the CallerID service apply to Identification. If you wouldn't run a
1598"finger" server due to privacy considerations you may not want to run
1599this protocol.
1600.ba
1601.lp
1602In some cases your system may not work properly with IDENT support
1603due to a bug in the TCP/IP implementation.
1604The symptoms will be that for some hosts
1605the SMTP connection will be closed
1606almost immediately.
1607If this is true or if you do not want to use IDENT,
1608you should set the IDENT timeout to zero;
1609this will disable the IDENT protocol.
1610.sh 1 "ARGUMENTS"
1611.pp
1612The complete list of arguments to
1613.i sendmail
1614is described in detail in Appendix A.
1615Some important arguments are described here.
1616.sh 2 "Queue Interval"
1617.pp
1618The amount of time between forking a process
1619to run through the queue
1620is defined by the
1621.b \-q
1622flag.
1623If you run with delivery mode set to
1624.b i
1625or
1626.b b
1627this can be relatively large,
1628since it will only be relevant
1629when a host that was down comes back up.
1630If you run in
1631.b q
1632mode
1633it should be relatively short,
1634since it defines the maximum amount of time that a message
1635may sit in the queue.
1636(See also the MinQueueAge option.)
1637.pp
1638RFC 1123 section 5.3.1.1 says that this value should be at least 30 minutes
1639(although that probably doesn't make sense if you use ``queue-only'' mode).
1640.sh 2 "Daemon Mode"
1641.pp
1642If you allow incoming mail over an IPC connection,
1643you should have a daemon running.
1644This should be set by your
1645.i /etc/rc
1646file using the
1647.b \-bd
1648flag.
1649The
1650.b \-bd
1651flag and the
1652.b \-q
1653flag may be combined in one call:
1654.(b
1655/usr/\*(SD/sendmail \-bd \-q30m
1656.)b
1657.pp
1658An alternative approach is to invoke sendmail from
1659.i inetd (8)
1660(use the
1661.b \-bs
1662flag to ask sendmail to speak SMTP on its standard input and output).
1663This works and allows you to wrap
1664.i sendmail
1665in a TCP wrapper program,
1666but may be a bit slower since the configuration file
1667has to be re-read on every message that comes in.
1668If you do this, you still need to have a
1669.i sendmail
1670running to flush the queue:
1671.(b
1672/usr/\*(SD/sendmail \-q30m
1673.)b
1674.sh 2 "Forcing the Queue"
1675.pp
1676In some cases you may find that the queue has gotten clogged for some reason.
1677You can force a queue run
1678using the
1679.b \-q
1680flag (with no value).
1681It is entertaining to use the
1682.b \-v
1683flag (verbose)
1684when this is done to watch what happens:
1685.(b
1686/usr/\*(SD/sendmail \-q \-v
1687.)b
1688.pp
1689You can also limit the jobs to those with a particular queue identifier,
1690sender, or recipient
1691using one of the queue modifiers.
1692For example,
1693.q \-qRberkeley
1694restricts the queue run to jobs that have the string
1695.q berkeley
1696somewhere in one of the recipient addresses.
1697Similarly,
1698.q \-qSstring
1699limits the run to particular senders and
1700.q \-qIstring
1701limits it to particular queue identifiers.
1702.sh 2 "Debugging"
1703.pp
1704There are a fairly large number of debug flags
1705built into
1706.i sendmail .
1707Each debug flag has a number and a level,
1708where higher levels means to print out more information.
1709The convention is that levels greater than nine are
1710.q absurd,
1711i.e.,
1712they print out so much information that you wouldn't normally
1713want to see them except for debugging that particular piece of code.
1714Debug flags are set using the
1715.b \-d
1716option;
1717the syntax is:
1718.(b
1719.ta \w'debug-option 'u
1720debug-flag: \fB\-d\fP debug-list
1721debug-list: debug-option [ , debug-option ]*
1722debug-option: debug-range [ . debug-level ]
1723debug-range: integer | integer \- integer
1724debug-level: integer
1725.)b
1726where spaces are for reading ease only.
1727For example,
1728.(b
1729\-d12 Set flag 12 to level 1
1730\-d12.3 Set flag 12 to level 3
1731\-d3\-17 Set flags 3 through 17 to level 1
1732\-d3\-17.4 Set flags 3 through 17 to level 4
1733.)b
1734For a complete list of the available debug flags
1735you will have to look at the code
1736(they are too dynamic to keep this documentation up to date).
1737.sh 2 "Changing the Values of Options"
1738.pp
1739Options can be overridden using the
1740.b \-o
1741or
1742.b \-O
1743command line flags.
1744For example,
1745.(b
1746/usr/\*(SD/sendmail \-oT2m
1747.)b
1748sets the
1749.b T
1750(timeout) option to two minutes
1751for this run only;
1752the equivalent line using the long option name is
1753.(b
1754/usr/\*(SD/sendmail -OTimeout.queuereturn=2m
1755.)b
1756.pp
1757Some options have security implications.
1758Sendmail allows you to set these,
1759but relinquishes its setuid root permissions thereafter\**.
1760.(f
1761\**That is, it sets its effective uid to the real uid;
1762thus, if you are executing as root,
1763as from root's crontab file or during system startup
1764the root permissions will still be honored.
1765.)f
1766.sh 2 "Trying a Different Configuration File"
1767.pp
1768An alternative configuration file
1769can be specified using the
1770.b \-C
1771flag; for example,
1772.(b
1773/usr/\*(SD/sendmail \-Ctest.cf \-oQ/tmp/mqueue
1774.)b
1775uses the configuration file
1776.i test.cf
1777instead of the default
1778.i /etc/sendmail.cf.
1779If the
1780.b \-C
1781flag has no value
1782it defaults to
1783.i sendmail.cf
1784in the current directory.
1785.pp
1786.i Sendmail
1787gives up its setuid root permissions
1788when you use this flag, so it is common to use a publicly writable directory
1789(such as /tmp)
1790as the spool directory (QueueDirectory or Q option) while testing.
1791.sh 2 "Logging Traffic"
1792.pp
1793Many SMTP implementations do not fully implement the protocol.
1794For example, some personal computer based SMTPs
1795do not understand continuation lines in reply codes.
1796These can be very hard to trace.
1797If you suspect such a problem, you can set traffic logging using the
1798.b \-X
1799flag.
1800For example,
1801.(b
1802/usr/\*(SD/sendmail \-X /tmp/traffic \-bd
1803.)b
1804will log all traffic in the file
1805.i /tmp/traffic .
1806.pp
1807This logs a lot of data very quickly and should
1808.b NEVER
1809be used
1810during normal operations.
1811After starting up such a daemon,
1812force the errant implementation to send a message to your host.
1813All message traffic in and out of
1814.i sendmail ,
1815including the incoming SMTP traffic,
1816will be logged in this file.
1817.sh 2 "Testing Configuration Files"
1818.pp
1819When you build a configuration table,
1820you can do a certain amount of testing
1821using the
1822.q "test mode"
1823of
1824.i sendmail .
1825For example,
1826you could invoke
1827.i sendmail
1828as:
1829.(b
1830sendmail \-bt \-Ctest.cf
1831.)b
1832which would read the configuration file
1833.q test.cf
1834and enter test mode.
1835In this mode,
1836you enter lines of the form:
1837.(b
1838rwset address
1839.)b
1840where
1841.i rwset
1842is the rewriting set you want to use
1843and
1844.i address
1845is an address to apply the set to.
1846Test mode shows you the steps it takes
1847as it proceeds,
1848finally showing you the address it ends up with.
1849You may use a comma separated list of rwsets
1850for sequential application of rules to an input.
1851For example:
1852.(b
18533,1,21,4 monet:bollard
1854.)b
1855first applies ruleset three to the input
1856.q monet:bollard.
1857Ruleset one is then applied to the output of ruleset three,
1858followed similarly by rulesets twenty-one and four.
1859.pp
1860If you need more detail,
1861you can also use the
1862.q \-d21
1863flag to turn on more debugging.
1864For example,
1865.(b
1866sendmail \-bt \-d21.99
1867.)b
1868turns on an incredible amount of information;
1869a single word address
1870is probably going to print out several pages worth of information.
1871.pp
1872You should be warned that internally,
1873.i sendmail
1874applies ruleset 3 to all addresses.
1875In test mode
1876you will have to do that manually.
1877For example, older versions allowed you to use
1878.(b
18790 bruce@broadcast.sony.com
1880.)b
1881This version requires that you use:
1882.(b
18833,0 bruce@broadcast.sony.com
1884.)b
1885.pp
1886As of version 8.7,
1887some other syntaxes are available in test mode:
1888.bu
1889\&.D\|x\|value
1890defines macro
1891.i x
1892to have the indicated
1893.i value .
1894This is useful when debugging rules that use the
1895.b $& \c
1896.i x
1897syntax.
1898.bu
1899\&.C\|c\|value
1900adds the indicated
1901.i value
1902to class
1903.i c .
1904.bu
1905\&.S\|ruleset
1906dumps the contents of the indicated ruleset.
1907.bu
1908\-d\|debug-spec
1909is equivalent to the command-line flag.
1910.sh 2 "Persistent Host Status Information"
1911.pp
1912When
1913.b HostStatusDirectory
1914is enabled,
1915information about the status of hosts is maintained on disk
1916and can thus be shared between different instantiations of
1917.i sendmail .
1918The status of the last connection with each remote host
1919may be viewed with the command:
1920.(b
1921sendmail \-bh
1922.)b
1923This information may be flushed with the command:
1924.(b
1925sendmail \-bH
1926.)b
1927Flushing the information prevents new
1928.i sendmail
1929processes from loading it,
1930but does not prevent existing processes from using the status information
1931that they already have.
1932.sh 1 "TUNING"
1933.pp
1934There are a number of configuration parameters
1935you may want to change,
1936depending on the requirements of your site.
1937Most of these are set
1938using an option in the configuration file.
1939For example,
1940the line
1941.q "O Timeout.queuereturn=5d"
1942sets option
1943.q Timeout.queuereturn
1944to the value
1945.q 5d
1946(five days).
1947.pp
1948Most of these options have appropriate defaults for most sites.
1949However,
1950sites having very high mail loads may find they need to tune them
1951as appropriate for their mail load.
1952In particular,
1953sites experiencing a large number of small messages,
1954many of which are delivered to many recipients,
1955may find that they need to adjust the parameters
1956dealing with queue priorities.
1957.pp
1958All versions of
1959.i sendmail
1960prior to 8.7
1961had single character option names.
1962As of 8.7,
1963options have long (multi-character names).
1964Although old short names are still accepted,
1965most new options do not have short equivalents.
1966.pp
1967This section only describes the options you are most likely
1968to want to tweak;
1969read section
1970.\"XREF
19715
1972for more details.
1973.sh 2 "Timeouts"
1974.pp
1975All time intervals are set
1976using a scaled syntax.
1977For example,
1978.q 10m
1979represents ten minutes, whereas
1980.q 2h30m
1981represents two and a half hours.
1982The full set of scales is:
1983.(b
1984.ta 4n
1985s seconds
1986m minutes
1987h hours
1988d days
1989w weeks
1990.)b
1991.sh 3 "Queue interval"
1992.pp
1993The argument to the
1994.b \-q
1995flag
1996specifies how often a sub-daemon will run the queue.
1997This is typically set to between fifteen minutes
1998and one hour.
1999RFC 1123 section 5.3.1.1 recommends that this be at least 30 minutes.
2000.sh 3 "Read timeouts"
2001.pp
2002Timeouts all have option names
2003.q Timeout.\fIsuboption\fP .
2004The recognized
2005.i suboption s,
2006their default values, and the minimum values
2007allowed by RFC 1123 section 5.3.2 are:
2008.nr ii 1i
2009.ip connect
2010The time to wait for an SMTP connection to open
2011(the
2012.i connect (2)
2013system call)
2014[0, unspecified].
2015If zero, uses the kernel default.
2016In no case can this option extend the timeout
2017longer than the kernel provides, but it can shorten it.
2018This is to get around kernels that provide an absurdly long connection timeout
2019(90 minutes in one case).
2020.ip iconnect
2021The same as
2022.i connect,
2023except it applies only to the initial attempt to connect to a host
2024for a given message
2025[0, unspecified].
2026The concept is that this should be very short (a few seconds);
2027hosts that are well connected and responsive will thus be serviced immediately.
2028Hosts that are slow will not hold up other deliveries in the initial
2029delivery attempt.
2030.ip initial
2031The wait for the initial 220 greeting message
2032[5m, 5m].
2033.ip helo
2034The wait for a reply from a HELO or EHLO command
2035[5m, unspecified].
2036This may require a host name lookup, so
2037five minutes is probably a reasonable minimum.
2038.ip mail\(dg
2039The wait for a reply from a MAIL command
2040[10m, 5m].
2041.ip rcpt\(dg
2042The wait for a reply from a RCPT command
2043[1h, 5m].
2044This should be long
2045because it could be pointing at a list
2046that takes a long time to expand
2047(see below).
2048.ip datainit\(dg
2049The wait for a reply from a DATA command
2050[5m, 2m].
2051.ip datablock\(dg
2052The wait for reading a data block
2053(that is, the body of the message).
2054[1h, 3m].
2055This should be long because it also applies to programs
2056piping input to
2057.i sendmail
2058which have no guarantee of promptness.
2059.ip datafinal\(dg
2060The wait for a reply from the dot terminating a message.
2061[1h, 10m].
2062If this is shorter than the time actually needed
2063for the receiver to deliver the message,
2064duplicates will be generated.
2065This is discussed in RFC 1047.
2066.ip rset
2067The wait for a reply from a RSET command
2068[5m, unspecified].
2069.ip quit
2070The wait for a reply from a QUIT command
2071[2m, unspecified].
2072.ip misc
2073The wait for a reply from miscellaneous (but short) commands
2074such as NOOP (no-operation) and VERB (go into verbose mode).
2075[2m, unspecified].
2076.ip command\(dg
2077In server SMTP,
2078the time to wait for another command.
2079[1h, 5m].
2080.ip ident
2081The timeout waiting for a reply to an IDENT query
2082[30s\**, unspecified].
2083.(f
2084\**On some systems the default is zero to turn the protocol off entirely.
2085.)f
2086.ip fileopen
2087The timeout for opening .forward and :include: files [60s, none].
2088.ip hoststatus
2089How long status information about a host
2090(e.g., host down)
2091will be cached before it is considered stale
2092[30m, unspecified].
2093.lp
2094For compatibility with old configuration files,
2095if no
2096.i suboption
2097is specified,
2098all the timeouts marked with \(dg are set to the indicated value.
2099.pp
2100Many of the RFC 1123 minimum values
2101may well be too short.
2102.i Sendmail
2103was designed to the RFC 822 protocols,
2104which did not specify read timeouts;
2105hence, versions of
2106.i sendmail
2107prior to version 8.1 did not guarantee to reply to messages promptly.
2108In particular, a
2109.q RCPT
2110command specifying a mailing list
2111will expand and verify the entire list;
2112a large list on a slow system
2113may easily take more than five minutes\**.
2114.(f
2115\**This verification includes looking up every address
2116with the name server;
2117this involves network delays,
2118and can in some cases can be considerable.
2119.)f
2120I recommend a one hour timeout \*-
2121since a communications failure during the RCPT phase is rare,
2122a long timeout is not onerous
2123and may ultimately help reduce network load
2124and duplicated messages.
2125.pp
2126For example, the lines:
2127.(b
2128O Timeout.command=25m
2129O Timeout.datablock=3h
2130.)b
2131sets the server SMTP command timeout to 25 minutes
2132and the input data block timeout to three hours.
2133.sh 3 "Message timeouts"
2134.pp
2135After sitting in the queue for a few days,
2136a message will time out.
2137This is to insure that at least the sender is aware
2138of the inability to send a message.
2139The timeout is typically set to five days.
2140It is sometimes considered convenient to also send a warning message
2141if the message is in the queue longer than a few hours
2142(assuming you normally have good connectivity;
2143if your messages normally took several hours to send
2144you wouldn't want to do this because it wouldn't be an unusual event).
2145These timeouts are set using the
2146.b Timeout.queuereturn
2147and
2148.b Timeout.queuewarn
2149options in the configuration file
2150(previously both were set using the
2151.b T
2152option).
2153.pp
2154Since these options are global,
2155and since you can not know
2156.i "a priori"
2157how long another host outside your domain will be down,
2158a five day timeout is recommended.
2159This allows a recipient to fix the problem even if it occurs
2160at the beginning of a long weekend.
2161RFC 1123 section 5.3.1.1 says that this parameter
2162should be ``at least 4\-5 days''.
2163.pp
2164The
2165.b Timeout.queuewarn
2166value can be piggybacked on the
2167.b T
2168option by indicating a time after which
2169a warning message should be sent;
2170the two timeouts are separated by a slash.
2171For example, the line
2172.(b
2173OT5d/4h
2174.)b
2175causes email to fail after five days,
2176but a warning message will be sent after four hours.
2177This should be large enough that the message will have been tried
2178several times.
2179.sh 2 "Forking During Queue Runs"
2180.pp
2181By setting the
2182.b ForkEachJob
2183(\c
2184.b Y )
2185option,
2186.i sendmail
2187will fork before each individual message
2188while running the queue.
2189This will prevent
2190.i sendmail
2191from consuming large amounts of memory,
2192so it may be useful in memory-poor environments.
2193However, if the
2194.b ForkEachJob
2195option is not set,
2196.i sendmail
2197will keep track of hosts that are down during a queue run,
2198which can improve performance dramatically.
2199.pp
2200If the
2201.b ForkEachJob
2202option is set,
2203.i sendmail
2204can not use connection caching.
2205.sh 2 "Queue Priorities"
2206.pp
2207Every message is assigned a priority when it is first instantiated,
2208consisting of the message size (in bytes)
2209offset by the message class
2210(which is determined from the Precedence: header)
2211times the
2212.q "work class factor"
2213and the number of recipients times the
2214.q "work recipient factor."
2215The priority is used to order the queue.
2216Higher numbers for the priority mean that the message will be processed later
2217when running the queue.
2218.pp
2219The message size is included so that large messages are penalized
2220relative to small messages.
2221The message class allows users to send
2222.q "high priority"
2223messages by including a
2224.q Precedence:
2225field in their message;
2226the value of this field is looked up in the
2227.b P
2228lines of the configuration file.
2229Since the number of recipients affects the amount of load a message presents
2230to the system,
2231this is also included into the priority.
2232.pp
2233The recipient and class factors
2234can be set in the configuration file using the
2235.b RecipientFactor
2236(\c
2237.b y )
2238and
2239.b ClassFactor
2240(\c
2241.b z )
2242options respectively.
2243They default to 30000 (for the recipient factor)
2244and 1800
2245(for the class factor).
2246The initial priority is:
2247.EQ
2248pri = msgsize - (class times bold ClassFactor) + (nrcpt times bold RecipientFactor)
2249.EN
2250(Remember, higher values for this parameter actually mean
2251that the job will be treated with lower priority.)
2252.pp
2253The priority of a job can also be adjusted each time it is processed
2254(that is, each time an attempt is made to deliver it)
2255using the
2256.q "work time factor,"
2257set by the
2258.b RetryFactor
2259(\c
2260.b Z )
2261option.
2262This is added to the priority,
2263so it normally decreases the precedence of the job,
2264on the grounds that jobs that have failed many times
2265will tend to fail again in the future.
2266The
2267.b RetryFactor
2268option defaults to 90000.
2269.sh 2 "Load Limiting"
2270.pp
2271.i Sendmail
2272can be asked to queue (but not deliver)
2273mail if the system load average gets too high
2274using the
2275.b QueueLA
2276(\c
2277.b x )
2278option.
2279When the load average exceeds the value of the
2280.b QueueLA
2281option,
2282the delivery mode is set to
2283.b q
2284(queue only)
2285if the
2286.b QueueFactor
2287(\c
2288.b q )
2289option divided by the difference in the current load average and the
2290.b QueueLA
2291option
2292plus one
2293exceeds the priority of the message \(em
2294that is, the message is queued iff:
2295.EQ
2296pri > { bold QueueFactor } over { LA - { bold QueueLA } + 1 }
2297.EN
2298The
2299.b QueueFactor
2300option defaults to 600000,
2301so each point of load average is worth 600000
2302priority points
2303(as described above).
2304.pp
2305For drastic cases,
2306the
2307.b RefuseLA
2308(\c
2309.b X )
2310option defines a load average at which
2311.i sendmail
2312will refuse
2313to accept network connections.
2314Locally generated mail
2315(including incoming UUCP mail)
2316is still accepted.
2317.sh 2 "Delivery Mode"
2318.pp
2319There are a number of delivery modes that
2320.i sendmail
2321can operate in,
2322set by the
2323.b DeliveryMode
2324(\c
2325.b d )
2326configuration option.
2327These modes
2328specify how quickly mail will be delivered.
2329Legal modes are:
2330.(b
2331.ta 4n
2332i deliver interactively (synchronously)
2333b deliver in background (asynchronously)
2334q queue only (don't deliver)
2335d defer delvery attempts (don't deliver)
2336.)b
2337There are tradeoffs.
2338Mode
2339.q i
2340gives the sender the quickest feedback,
2341but may slow down some mailers and
2342is hardly ever necessary.
2343Mode
2344.q b
2345delivers promptly but
2346can cause large numbers of processes
2347if you have a mailer that takes a long time to deliver a message.
2348Mode
2349.q q
2350minimizes the load on your machine,
2351but means that delivery may be delayed for up to the queue interval.
2352Mode
2353.q d
2354is identical to mode
2355.q q
2356except that it also prevents all the early map lookups from working;
2357it is intended for ``dial on demand'' sites where DNS lookups
2358might cost real money.
2359Some simple error messages
2360(e.g., host unknown during the SMTP protocol)
2361will be delayed using this mode.
2362Mode
2363.q b
2364is the usual default.
2365.pp
2366If you run in mode
2367.q q
2368(queue only),
2369.q d
2370(defer),
2371or
2372.q b
2373(deliver in background)
2374.i sendmail
2375will not expand aliases and follow .forward files
2376upon initial receipt of the mail.
2377This speeds up the response to RCPT commands.
2378Mode
2379.q i
2380cannot be used by the SMTP server.
2381.sh 2 "Log Level"
2382.pp
2383The level of logging can be set for
2384.i sendmail .
2385The default using a standard configuration table is level 9.
2386The levels are as follows:
2387.nr ii 0.5i
2388.ip 0
2389Minimal logging.
2390.ip 1
2391Serious system failures and potential security problems.
2392.ip 2
2393Lost communications (network problems) and protocol failures.
2394.ip 3
2395Other serious failures, malformed addresses, transient forward/include
2396errors, connection timeouts.
2397.ip 4
2398Minor failures, out of date alias databases, connection rejections
2399via check_ rulesets.
2400.ip 5
2401Message collection statistics.
2402.ip 6
2403Creation of error messages,
2404VRFY and EXPN commands.
2405.ip 7
2406Delivery failures (host or user unknown, etc.).
2407.ip 8
2408Successful deliveries and alias database rebuilds.
2409.ip 9
2410Messages being deferred
2411(due to a host being down, etc.).
2412.ip 10
2413Database expansion (alias, forward, and userdb lookups).
2414.ip 11
2415NIS errors and end of job processing.
2416.ip 12
2417Logs all SMTP connections.
2418.ip 13
2419Log bad user shells, files with improper permissions, and other
2420questionable situations.
2421.ip 14
2422Logs refused connections.
2423.ip 15
2424Log all incoming and outgoing SMTP commands.
2425.ip 20
2426Logs attempts to run locked queue files.
2427These are not errors,
2428but can be useful to note if your queue appears to be clogged.
2429.ip 30
2430Lost locks (only if using lockf instead of flock).
2431.lp
2432Additionally,
2433values above 64 are reserved for extremely verbose debugging output.
2434No normal site would ever set these.
2435.sh 2 "File Modes"
2436.pp
2437The modes used for files depend on what functionality you want
2438and the level of security you require.
2439In many cases
2440.i sendmail
2441does careful checking of the modes
2442of files and directories
2443to avoid accidental compromise;
2444if you want to make it possible to have group-writable support files
2445you may need to use the
2446.b DontBlameSendmail
2447option to turn off some of these checks.
2448.sh 3 "To suid or not to suid?"
2449.pp
2450.i Sendmail
2451is normally installed
2452setuid to root.
2453At the point where it is about to
2454.i exec \|(2)
2455a mailer,
2456it checks to see if the userid is zero (root);
2457if so,
2458it resets the userid and groupid to a default
2459(set by the
2460.b U=
2461equate in the mailer line;
2462if that is not set, the
2463.b DefaultUser
2464option is used).
2465This can be overridden
2466by setting the
2467.b S
2468flag to the mailer
2469for mailers that are trusted
2470and must be called as root.
2471However,
2472this will cause mail processing
2473to be accounted
2474(using
2475.i sa \|(8))
2476to root
2477rather than to the user sending the mail.
2478.pp
2479If you don't make
2480.i sendmail
2481setuid to root, it will still run but you lose a lot of functionality
2482and a lot of privacy, since you'll have to make the queue directory
2483world readable.
2484You could also make
2485.i sendmail
2486setuid to some pseudo-user
2487(e.g., create a user called
2488.q sendmail
2489and make
2490.i sendmail
2491setuid to that)
2492which will fix the privacy problems
2493but not the functionality issues.
2494Also, this isn't a guarantee of security:
2495for example,
2496root occasionally sends mail,
2497and the daemon often runs as root.
2498Note however that
2499.i sendmail
2500must run as root in order to create the SMTP listener socket.
2501.pp
2502A middle ground is to make
2503.i sendmail
2504setuid to root,
2505but set the
2506.b RunAsUser
2507option.
2508This causes
2509.i sendmail
2510to become the indicated user as soon as it has done the startup
2511that requires root privileges
2512(primarily, opening the
2513.sm SMTP
2514socket).
2515If you use
2516.b RunAsUser ,
2517the queue directory
2518(normally
2519.i /var/spool/mqueue )
2520should be owned by that user,
2521and all files and databases
2522(including user
2523.i \&.forward
2524files,
2525alias files,
2526:include: files,
2527and external databases)
2528must be readable by that user.
2529.b RunAsUser
2530is probably best suited for firewall configurations
2531that don't have regular user logins.
2532.sh 3 "Turning off security checks"
2533.pp
2534.i Sendmail
2535is very particular about the modes of files that it reads or writes.
2536For example, by default it will refuse to read most files
2537that are group writable
2538on the grounds that they might have been tampered with
2539by someone other than the owner;
2540it will even refuse to read files in group writable directories.
2541.pp
2542If you are
2543.i quite
2544sure that your configuration is safe and you want
2545.i sendmail
2546to avoid these security checks,
2547you can turn off certain checks using the
2548.b DontBlameSendmail
2549option.
2550This option takes one or more names that disable checks.
2551In the descriptions that follow,
2552.q "unsafe directory"
2553means a directory that is writable by anyone other than the owner.
2554The values are:
2555.nr ii 0.5i
2556.ip Safe
2557No special handling.
2558.ip AssumeSafeChown
2559Assume that the
2560.i chown
2561system call is restricted to root.
2562Since some versions of Unix permit regular users
2563to give away their files to other users on some filesystems,
2564.i sendmail
2565often cannot assume that a given file was created by the owner,
2566particularly when it is in a writable directory.
2567You can set this flag if you know that file giveaway is restricted
2568on your system.
2569.ip ClassFileInUnsafeDirPath
2570When reading class files (using the
2571.b F
2572line in the configuration file),
2573allow files that are in unsafe directories.
2574.ip ErrorHeaderInUnsafeDirPath
2575Allow the file named in the
2576.b ErrorHeader
2577option to be in an unsafe directory.
2578.ip GroupWritableDirPathSafe
2579Change the definition of
2580.q "unsafe directory"
2581to consider group-writable directories to be safe.
2582World-writable directories are always unsafe.
2583.ip GroupWritableForwardFileSafe
2584Accept group-writable
2585.i \&.forward
2586files.
2587.ip GroupWritableIncludeFileSafe
2588Accept group-writable
2589.i :include:
2590files.
2591.ip GroupWritableAliasFile
2592Allow group-writable alias files.
2593.ip HelpFileInUnsafeDirPath
2594Allow the file named in the
2595.b HelpFile
2596option to be in an unsafe directory.
2597.ip WorldWritableAliasFile
2598Accept world-writable alias files.
2599.ip ForwardFileInGroupWritableDirPath
2600Allow
2601.i \&.forward
2602files in group writable directories.
2603.ip IncludeFileInGroupWritableDirPath
2604Allow
2605.i :include:
2606files in group writable directories.
2607.ip ForwardFileInUnsafeDirPath
2608Allow
2609.i \&.forward
2610files in unsafe directories.
2611.ip IncludeFileInUnsafeDirPath
2612Allow
2613.i :include:
2614files in unsafe directories.
2615.ip ForwardFileInUnsafeDirPathSafe
2616Allow a
2617.i \&.forward
2618file that is in an unsafe directory to include references
2619to program and files.
2620.ip IncludeFileInUnsafeDirPathSafe
2621Allow a
2622.i :include:
2623file that is in an unsafe directory to include references
2624to program and files.
2625.ip MapInUnsafeDirPath
2626Allow maps (e.g.,
2627.i hash ,
2628.i btree ,
2629and
2630.i dbm
2631files)
2632in unsafe directories.
2633.ip LinkedAliasFileInWritableDir
2634Allow an alias file that is a link in a writable directory.
2635.ip LinkedClassFileInWritableDir
2636Allow class files that are links in writable directories.
2637.ip LinkedForwardFileInWritableDir
2638Allow
2639.i \&.forward
2640files that are links in writable directories.
2641.ip LinkedIncludeFileInWritableDir
2642Allow
2643.i :include:
2644files that are links in writable directories.
2645.ip LinkedMapInWritableDir
2646Allow map files that are links in writable directories.
2647.ip LinkedServiceSwitchFileInWritableDir
2648Allow the service switch file to be a link
2649even if the directory is writable.
2650.ip FileDeliveryToHardLink
2651Allow delivery to files that are hard links.
2652.ip FileDeliveryToSymLink
2653Allow delivery to files that are symbolic links.
2654.ip RunProgramInUnsafeDirPath
2655Go ahead and run programs that are in writable directories.
2656.ip RunWritableProgram
2657Go ahead and run programs that are group- or world-writable.
2658.ip WriteMapToHardLink
2659Allow writes to maps that are hard links.
2660.ip WriteMapToSymLink
2661Allow writes to maps that are symbolic links.
2662.ip WriteStatsToHardLink
2663Allow the status file to be a hard link.
2664.ip WriteStatsToSymLink
2665Allow the status file to be a symbolic link.
2666.sh 2 "Connection Caching"
2667.pp
2668When processing the queue,
2669.i sendmail
2670will try to keep the last few open connections open
2671to avoid startup and shutdown costs.
2672This only applies to IPC connections.
2673.pp
2674When trying to open a connection
2675the cache is first searched.
2676If an open connection is found, it is probed to see if it is still active
2677by sending a
2678.sm RSET
2679command.
2680It is not an error if this fails;
2681instead, the connection is closed and reopened.
2682.pp
2683Two parameters control the connection cache.
2684The
2685.b ConnectionCacheSize
2686(\c
2687.b k )
2688option defines the number of simultaneous open connections
2689that will be permitted.
2690If it is set to zero,
2691connections will be closed as quickly as possible.
2692The default is one.
2693This should be set as appropriate for your system size;
2694it will limit the amount of system resources that
2695.i sendmail
2696will use during queue runs.
2697Never set this higher than 4.
2698.pp
2699The
2700.b ConnectionCacheTimeout
2701(\c
2702.b K )
2703option specifies the maximum time that any cached connection
2704will be permitted to idle.
2705When the idle time exceeds this value
2706the connection is closed.
2707This number should be small
2708(under ten minutes)
2709to prevent you from grabbing too many resources
2710from other hosts.
2711The default is five minutes.
2712.sh 2 "Name Server Access"
2713.pp
2714Control of host address lookups is set by the
2715.b hosts
2716service entry in your service switch file.
2717If you are on a system that has built-in service switch support
2718(e.g., Ultrix, Solaris, or DEC OSF/1)
2719then your system is probably configured properly already.
2720Otherwise,
2721.i sendmail
2722will consult the file
2723.b /etc/service.switch ,
2724which should be created.
2725.i Sendmail
2726only uses two entries:
2727.b hosts
2728and
2729.b aliases ,
2730although system routines may use other services
2731(notably the
2732.b passwd
2733service for user name lookups by
2734.i getpwname ).
2735.pp
2736However, some systems (such as SunOS 4.X)
2737will do DNS lookups
2738regardless of the setting of the service switch entry.
2739In particular, the system routine
2740.i gethostbyname (3)
2741is used to look up host names,
2742and many vendor versions try some combination of DNS, NIS,
2743and file lookup in /etc/hosts
2744without consulting a service switch.
2745.i Sendmail
2746makes no attempt to work around this problem,
2747and the DNS lookup will be done anyway.
2748If you do not have a nameserver configured at all,
2749such as at a UUCP-only site,
2750.i sendmail
2751will get a
2752.q "connection refused"
2753message when it tries to connect to the name server.
2754If the
2755.b hosts
2756switch entry has the service
2757.q dns
2758listed somewhere in the list,
2759.i sendmail
2760will interpret this to mean a temporary failure
2761and will queue the mail for later processing;
2762otherwise, it ignores the name server data.
2763.pp
2764The same technique is used to decide whether to do MX lookups.
2765If you want MX support, you
2766.i must
2767have
2768.q dns
2769listed as a service in the
2770.b hosts
2771switch entry.
2772.pp
2773The
2774.b ResolverOptions
2775(\c
2776.b I )
2777option allows you to tweak name server options.
2778The command line takes a series of flags as documented in
2779.i resolver (3)
2780(with the leading
2781.q RES_
2782deleted).
2783Each can be preceded by an optional `+' or `\(mi'.
2784For example, the line
2785.(b
2786O ResolverOptions=+AAONLY \(miDNSRCH
2787.)b
2788turns on the AAONLY (accept authoritative answers only)
2789and turns off the DNSRCH (search the domain path) options.
2790Most resolver libraries default DNSRCH, DEFNAMES, and RECURSE
2791flags on and all others off.
2792You can also include
2793.q HasWildcardMX
2794to specify that there is a wildcard MX record matching your domain;
2795this turns off MX matching when canonifying names,
2796which can lead to inappropriate canonifications.
2797.pp
2798Version level 1 configurations
2799turn DNSRCH and DEFNAMES off when doing delivery lookups,
2800but leave them on everywhere else.
2801Version 8 of
2802.i sendmail
2803ignores them when doing canonification lookups
2804(that is, when using $[ ... $]),
2805and always does the search.
2806If you don't want to do automatic name extension,
2807don't call $[ ... $].
2808.pp
2809The search rules for $[ ... $] are somewhat different than usual.
2810If the name being looked up
2811has at least one dot, it always tries the unmodified name first.
2812If that fails, it tries the reduced search path,
2813and lastly tries the unmodified name
2814(but only for names without a dot,
2815since names with a dot have already been tried).
2816This allows names such as
2817``utc.CS''
2818to match the site in Czechoslovakia
2819rather than the site in your local Computer Science department.
2820It also prefers A and CNAME records over MX records \*-
2821that is, if it finds an MX record it makes note of it,
2822but keeps looking.
2823This way, if you have a wildcard MX record matching your domain,
2824it will not assume that all names match.
2825.pp
2826To completely turn off all name server access
2827on systems without service switch support
2828(such as SunOS 4.X)
2829you will have to recompile with
2830\-DNAMED_BIND=0
2831and remove \-lresolv from the list of libraries to be searched
2832when linking.
2833.sh 2 "Moving the Per-User Forward Files"
2834.pp
2835Some sites mount each user's home directory
2836from a local disk on their workstation,
2837so that local access is fast.
2838However, the result is that .forward file lookups are slow.
2839In some cases,
2840mail can even be delivered on machines inappropriately
2841because of a file server being down.
2842The performance can be especially bad if you run the automounter.
2843.pp
2844The
2845.b ForwardPath
2846(\c
2847.b J )
2848option allows you to set a path of forward files.
2849For example, the config file line
2850.(b
2851O ForwardPath=/var/forward/$u:$z/.forward.$w
2852.)b
2853would first look for a file with the same name as the user's login
2854in /var/forward;
2855if that is not found (or is inaccessible)
2856the file
2857``.forward.\c
2858.i machinename ''
2859in the user's home directory is searched.
2860A truly perverse site could also search by sender
2861by using $r, $s, or $f.
2862.pp
2863If you create a directory such as /var/forward,
2864it should be mode 1777
2865(that is, the sticky bit should be set).
2866Users should create the files mode 644.
2867Note that you must use the
2868forwardfileinunsafedirpath and
2869forwardfileinunsafedirpathsafe
2870flags with the DontBlameSendmail option
2871to allow forward files in a world
2872writable directory.
|
2873.sh 2 "Free Space"
2874.pp
2875On systems that have one of the system calls in the
2876.i statfs (2)
2877family
2878(including
2879.i statvfs
2880and
2881.i ustat ),
2882you can specify a minimum number of free blocks on the queue filesystem
2883using the
2884.b MinFreeBlocks
2885(\c
2886.b b )
2887option.
2888If there are fewer than the indicated number of blocks free
2889on the filesystem on which the queue is mounted
2890the SMTP server will reject mail
2891with the
2892452 error code.
2893This invites the SMTP client to try again later.
2894.pp
2895Beware of setting this option too high;
2896it can cause rejection of email
2897when that mail would be processed without difficulty.
2898.sh 2 "Maximum Message Size"
2899.pp
2900To avoid overflowing your system with a large message,
2901the
2902.b MaxMessageSize
2903option can be set to set an absolute limit
2904on the size of any one message.
2905This will be advertised in the ESMTP dialogue
2906and checked during message collection.
2907.sh 2 "Privacy Flags"
2908.pp
2909The
2910.b PrivacyOptions
2911(\c
2912.b p )
2913option allows you to set certain
2914``privacy''
2915flags.
2916Actually, many of them don't give you any extra privacy,
2917rather just insisting that client SMTP servers
2918use the HELO command
2919before using certain commands
2920or adding extra headers to indicate possible spoof attempts.
2921.pp
2922The option takes a series of flag names;
2923the final privacy is the inclusive or of those flags.
2924For example:
2925.(b
2926O PrivacyOptions=needmailhelo, noexpn
2927.)b
2928insists that the HELO or EHLO command be used before a MAIL command is accepted
2929and disables the EXPN command.
2930.pp
2931The flags are detailed in section
2932.\"XREF
29335.6.
2934.sh 2 "Send to Me Too"
2935.pp
2936Normally,
2937.i sendmail
2938deletes the (envelope) sender from any list expansions.
2939For example, if
2940.q matt
2941sends to a list that contains
2942.q matt
2943as one of the members he won't get a copy of the message.
2944If the
2945.b \-m
2946(me too)
2947command line flag, or if the
2948.b MeToo
2949(\c
2950.b m )
2951option is set in the configuration file,
2952this behaviour is suppressed.
2953Some sites like to run the
2954.sm SMTP
2955daemon with
2956.b \-m .
2957.sh 1 "THE WHOLE SCOOP ON THE CONFIGURATION FILE"
2958.pp
2959This section describes the configuration file
2960in detail.
2961.pp
2962There is one point that should be made clear immediately:
2963the syntax of the configuration file
2964is designed to be reasonably easy to parse,
2965since this is done every time
2966.i sendmail
2967starts up,
2968rather than easy for a human to read or write.
2969On the
2970.q "future project"
2971list is a
2972configuration-file compiler.
2973.pp
2974The configuration file is organized as a series of lines,
2975each of which begins with a single character
2976defining the semantics for the rest of the line.
2977Lines beginning with a space or a tab
2978are continuation lines
2979(although the semantics are not well defined in many places).
2980Blank lines and lines beginning with a sharp symbol
2981(`#')
2982are comments.
2983.sh 2 "R and S \*- Rewriting Rules"
2984.pp
2985The core of address parsing
2986are the rewriting rules.
2987These are an ordered production system.
2988.i Sendmail
2989scans through the set of rewriting rules
2990looking for a match on the left hand side
2991(LHS)
2992of the rule.
2993When a rule matches,
2994the address is replaced by the right hand side
2995(RHS)
2996of the rule.
2997.pp
2998There are several sets of rewriting rules.
2999Some of the rewriting sets are used internally
3000and must have specific semantics.
3001Other rewriting sets
3002do not have specifically assigned semantics,
3003and may be referenced by the mailer definitions
3004or by other rewriting sets.
3005.pp
3006The syntax of these two commands are:
3007.(b F
3008.b S \c
3009.i n
3010.)b
3011Sets the current ruleset being collected to
3012.i n .
3013If you begin a ruleset more than once
3014it appends to the old definition.
3015.(b F
3016.b R \c
3017.i lhs
3018.i rhs
3019.i comments
3020.)b
3021The
3022fields must be separated
3023by at least one tab character;
3024there may be embedded spaces
3025in the fields.
3026The
3027.i lhs
3028is a pattern that is applied to the input.
3029If it matches,
3030the input is rewritten to the
3031.i rhs .
3032The
3033.i comments
3034are ignored.
3035.pp
3036Macro expansions of the form
3037.b $ \c
3038.i x
3039are performed when the configuration file is read.
3040Expansions of the form
3041.b $& \c
3042.i x
3043are performed at run time using a somewhat less general algorithm.
3044This is intended only for referencing internally defined macros
3045such as
3046.b $h
3047that are changed at runtime.
3048.sh 3 "The left hand side"
3049.pp
3050The left hand side of rewriting rules contains a pattern.
3051Normal words are simply matched directly.
3052Metasyntax is introduced using a dollar sign.
3053The metasymbols are:
3054.(b
3055.ta \w'\fB$=\fP\fIx\fP 'u
3056\fB$*\fP Match zero or more tokens
3057\fB$+\fP Match one or more tokens
3058\fB$\-\fP Match exactly one token
3059\fB$=\fP\fIx\fP Match any phrase in class \fIx\fP
3060\fB$~\fP\fIx\fP Match any word not in class \fIx\fP
3061.)b
3062If any of these match,
3063they are assigned to the symbol
3064.b $ \c
3065.i n
3066for replacement on the right hand side,
3067where
3068.i n
3069is the index in the LHS.
3070For example,
3071if the LHS:
3072.(b
3073$\-:$+
3074.)b
3075is applied to the input:
3076.(b
3077UCBARPA:eric
3078.)b
3079the rule will match, and the values passed to the RHS will be:
3080.(b
3081.ta 4n
3082$1 UCBARPA
3083$2 eric
3084.)b
3085.pp
3086Additionally, the LHS can include
3087.b $@
3088to match zero tokens.
3089This is
3090.i not
3091bound to a
3092.b $ \c
3093.i n
3094on the RHS, and is normally only used when it stands alone
3095in order to match the null input.
3096.sh 3 "The right hand side"
3097.pp
3098When the left hand side of a rewriting rule matches,
3099the input is deleted and replaced by the right hand side.
3100Tokens are copied directly from the RHS
3101unless they begin with a dollar sign.
3102Metasymbols are:
3103.(b
3104.ta \w'$#mailer\0\0\0'u
3105\fB$\fP\fIn\fP Substitute indefinite token \fIn\fP from LHS
3106\fB$[\fP\fIname\fP\fB$]\fP Canonicalize \fIname\fP
3107\fB$(\fP\fImap key\fP \fB$@\fP\fIarguments\fP \fB$:\fP\fIdefault\fP \fB$)\fP
3108 Generalized keyed mapping function
3109\fB$>\fP\fIn\fP \*(lqCall\*(rq ruleset \fIn\fP
3110\fB$#\fP\fImailer\fP Resolve to \fImailer\fP
3111\fB$@\fP\fIhost\fP Specify \fIhost\fP
3112\fB$:\fP\fIuser\fP Specify \fIuser\fP
3113.)b
3114.pp
3115The
3116.b $ \c
3117.i n
3118syntax substitutes the corresponding value from a
3119.b $+ ,
3120.b $\- ,
3121.b $* ,
3122.b $= ,
3123or
3124.b $~
3125match on the LHS.
3126It may be used anywhere.
3127.pp
3128A host name enclosed between
3129.b $[
3130and
3131.b $]
3132is looked up in the host database(s)
3133and replaced by the canonical name\**.
3134.(f
3135\**This is actually
3136completely equivalent
3137to $(host \fIhostname\fP$).
3138In particular, a
3139.b $:
3140default can be used.
3141.)f
3142For example,
3143.q $[ftp$]
3144might become
3145.q ftp.CS.Berkeley.EDU
3146and
3147.q $[[128.32.130.2]$]
3148would become
3149.q vangogh.CS.Berkeley.EDU.
3150.i Sendmail
3151recognizes its numeric IP address
3152without calling the name server
3153and replaces it with its canonical name.
3154.pp
3155The
3156.b $(
3157\&...
3158.b $)
3159syntax is a more general form of lookup;
3160it uses a named map instead of an implicit map.
3161If no lookup is found, the indicated
3162.i default
3163is inserted;
3164if no default is specified and no lookup matches,
3165the value is left unchanged.
3166The
3167.i arguments
3168are passed to the map for possible use.
3169.pp
3170The
3171.b $> \c
3172.i n
3173syntax
3174causes the remainder of the line to be substituted as usual
3175and then passed as the argument to ruleset
3176.i n .
3177The final value of ruleset
3178.i n
3179then becomes
3180the substitution for this rule.
3181The
3182.b $>
3183syntax expands everything after the ruleset name
3184to the end of the replacement string
3185and then passes that as the initial input to the ruleset.
3186Recursive calls are allowed.
3187For example,
3188.(b
3189$>0 $>3 $1
3190.)b
3191expands $1, passes that to ruleset 3, and then passes the result
3192of ruleset 3 to ruleset 0.
3193.pp
3194The
3195.b $#
3196syntax should
3197.i only
3198be used in ruleset zero
3199or a subroutine of ruleset zero.
3200It causes evaluation of the ruleset to terminate immediately,
3201and signals to
3202.i sendmail
3203that the address has completely resolved.
3204The complete syntax is:
3205.(b
3206\fB$#\fP\fImailer\fP \fB$@\fP\fIhost\fP \fB$:\fP\fIuser\fP
3207.)b
3208This specifies the
3209{mailer, host, user}
32103-tuple necessary to direct the mailer.
3211If the mailer is local
3212the host part may be omitted\**.
3213.(f
3214\**You may want to use it for special
3215.q "per user"
3216extensions.
3217For example, in the address
3218.q jgm+foo@CMU.EDU ;
3219the
3220.q +foo
3221part is not part of the user name,
3222and is passed to the local mailer for local use.
3223.)f
3224The
3225.i mailer
3226must be a single word,
3227but the
3228.i host
3229and
3230.i user
3231may be multi-part.
3232If the
3233.i mailer
3234is the builtin IPC mailer,
3235the
3236.i host
3237may be a colon-separated list of hosts
3238that are searched in order for the first working address
3239(exactly like MX records).
3240The
3241.i user
3242is later rewritten by the mailer-specific envelope rewriting set
3243and assigned to the
3244.b $u
3245macro.
3246As a special case, if the mailer specified has the
3247.b F=@
3248flag specified
3249and the first character of the
3250.b $:
3251value is
3252.q @ ,
3253the
3254.q @
3255is stripped off, and a flag is set in the address descriptor
3256that causes sendmail to not do ruleset 5 processing.
3257.pp
3258Normally, a rule that matches is retried,
3259that is,
3260the rule loops until it fails.
3261A RHS may also be preceded by a
3262.b $@
3263or a
3264.b $:
3265to change this behavior.
3266A
3267.b $@
3268prefix causes the ruleset to return with the remainder of the RHS
3269as the value.
3270A
3271.b $:
3272prefix causes the rule to terminate immediately,
3273but the ruleset to continue;
3274this can be used to avoid continued application of a rule.
3275The prefix is stripped before continuing.
3276.pp
3277The
3278.b $@
3279and
3280.b $:
3281prefixes may precede a
3282.b $>
3283spec;
3284for example:
3285.(b
3286.ta 8n
3287R$+ $: $>7 $1
3288.)b
3289matches anything,
3290passes that to ruleset seven,
3291and continues;
3292the
3293.b $:
3294is necessary to avoid an infinite loop.
3295.pp
3296Substitution occurs in the order described,
3297that is,
3298parameters from the LHS are substituted,
3299hostnames are canonicalized,
3300.q subroutines
3301are called,
3302and finally
3303.b $# ,
3304.b $@ ,
3305and
3306.b $:
3307are processed.
3308.sh 3 "Semantics of rewriting rule sets"
3309.pp
3310There are six rewriting sets
3311that have specific semantics.
3312Five of these are related as depicted by figure 1.
3313.(z
3314.hl
3315.ie n \{\
3316.(c
3317 +---+
3318 -->| 0 |-->resolved address
3319 / +---+
3320 / +---+ +---+
3321 / ---->| 1 |-->| S |--
3322 +---+ / +---+ / +---+ +---+ \e +---+
3323addr-->| 3 |-->| D |-- --->| 4 |-->msg
3324 +---+ +---+ \e +---+ +---+ / +---+
3325 --->| 2 |-->| R |--
3326 +---+ +---+
3327.)c
3328
3329.\}
3330.el .ie !"\*(.T"" \
3331\{\
3332.PS
3333boxwid = 0.3i
3334boxht = 0.3i
3335movewid = 0.3i
3336moveht = 0.3i
3337linewid = 0.3i
3338lineht = 0.3i
3339
3340 box invis "addr"; arrow
3341Box3: box "3"
3342A1: arrow
3343BoxD: box "D"; line; L1: Here
3344C: [
3345 C1: arrow; box "1"; arrow; box "S"; line; E1: Here
3346 move to C1 down 0.5; right
3347 C2: arrow; box "2"; arrow; box "R"; line; E2: Here
3348 ] with .w at L1 + (0.5, 0)
3349 move to C.e right 0.5
3350L4: arrow; box "4"; arrow; box invis "msg"
3351 line from L1 to C.C1
3352 line from L1 to C.C2
3353 line from C.E1 to L4
3354 line from C.E2 to L4
3355 move to BoxD.n up 0.6; right
3356Box0: arrow; box "0"
3357 arrow; box invis "resolved address" width 1.3
3358 line from 1/3 of the way between A1 and BoxD.w to Box0
3359.PE
3360.\}
3361.el .sp 2i
3362.ce
3363Figure 1 \*- Rewriting set semantics
3364.(c
3365D \*- sender domain addition
3366S \*- mailer-specific sender rewriting
3367R \*- mailer-specific recipient rewriting
3368.)c
3369.hl
3370.)z
3371.pp
3372Ruleset three
3373should turn the address into
3374.q "canonical form."
3375This form should have the basic syntax:
3376.(b
3377local-part@host-domain-spec
3378.)b
3379Ruleset three
3380is applied by
3381.i sendmail
3382before doing anything with any address.
3383.pp
3384If no
3385.q @
3386sign is specified,
3387then the
3388host-domain-spec
3389.i may
3390be appended (box
3391.q D
3392in Figure 1)
3393from the
3394sender address
3395(if the
3396.b C
3397flag is set in the mailer definition
3398corresponding to the
3399.i sending
3400mailer).
3401.pp
3402Ruleset zero
3403is applied after ruleset three
3404to addresses that are going to actually specify recipients.
3405It must resolve to a
3406.i "{mailer, host, user}"
3407triple.
3408The
3409.i mailer
3410must be defined in the mailer definitions
3411from the configuration file.
3412The
3413.i host
3414is defined into the
3415.b $h
3416macro
3417for use in the argv expansion of the specified mailer.
3418.pp
3419Rulesets one and two
3420are applied to all sender and recipient addresses respectively.
3421They are applied before any specification
3422in the mailer definition.
3423They must never resolve.
3424.pp
3425Ruleset four is applied to all addresses
3426in the message.
3427It is typically used
3428to translate internal to external form.
3429.pp
3430In addition,
3431ruleset 5 is applied to all local addresses
3432(specifically, those that resolve to a mailer with the `F=5'
3433flag set)
3434that do not have aliases.
3435This allows a last minute hook for local names.
3436.sh 3 "Ruleset hooks"
3437.pp
3438A few extra rulesets are defined as
3439.q hooks
3440that can be defined to get special features.
3441They are all named rulesets.
3442The
3443.q check_*
3444forms all give accept/reject status;
3445falling off the end or returning normally is an accept,
3446and resolving to
3447.b $#error
3448is a reject.
3449Many of these can also resolve to the special mailer
3450.b $#discard ;
3451this accepts the message as though it were successful
3452but then discards it without delivery.
3453.sh 4 "check_relay"
3454.pp
3455The
3456.i check_relay
3457ruleset is called after a connection is accepted.
3458It is passed
3459.(b
3460client.host.name $| client.host.address
3461.)b
3462where
3463.b $|
3464is a metacharacter separating the two parts.
3465This ruleset can reject connections from various locations.
3466.sh 4 "check_mail"
3467.pp
3468The
3469.i check_mail
3470ruleset is passed the user name parameter of the
3471.sm "SMTP MAIL"
3472command.
3473It can accept or reject the address.
3474.sh 4 "check_rcpt"
3475.pp
3476The
3477.i check_rcpt
3478ruleset is passed the user name parameter of the
3479.sm "SMTP RCPT"
3480command.
3481It can accept or reject the address.
3482.sh 4 "check_compat"
3483.pp
3484The
3485.i check_compat
3486ruleset is passed
3487.(b
3488sender-address $| recipient-address
3489.)b
3490where
3491.b $|
3492is a metacharacter separating the addresses.
3493It can accept or reject mail transfer between these two addresses
3494much like the
3495.i checkcompat()
3496function.
3497.sh 3 "IPC mailers"
3498.pp
3499Some special processing occurs
3500if the ruleset zero resolves to an IPC mailer
3501(that is, a mailer that has
3502.q [IPC]
3503listed as the Path in the
3504.b M
3505configuration line.
3506The host name passed after
3507.q $@
3508has MX expansion performed;
3509this looks the name up in DNS to find alternate delivery sites.
3510.pp
3511The host name can also be provided as a dotted quad in square brackets;
3512for example:
3513.(b
3514[128.32.149.78]
3515.)b
3516This causes direct conversion of the numeric value
3517to an IP host address.
3518.pp
3519The host name passed in after the
3520.q $@
3521may also be a colon-separated list of hosts.
3522Each is separately MX expanded and the results are concatenated
3523to make (essentially) one long MX list.
3524The intent here is to create
3525.q fake
3526MX records that are not published in DNS
3527for private internal networks.
3528.pp
3529As a final special case, the host name can be passed in
3530as a text string
3531in square brackets:
3532.(b
3533[ucbvax.berkeley.edu]
3534.)b
3535This form avoids the MX mapping.
3536.b N.B.:
3537.i
3538This is intended only for situations where you have a network firewall
3539or other host that will do special processing for all your mail,
3540so that your MX record points to a gateway machine;
3541this machine could then do direct delivery to machines
3542within your local domain.
3543Use of this feature directly violates RFC 1123 section 5.3.5:
3544it should not be used lightly.
3545.r
3546.sh 2 "D \*- Define Macro"
3547.pp
3548Macros are named with a single character
3549or with a word in {braces}.
3550Single character names may be selected from the entire ASCII set,
3551but user-defined macros
3552should be selected from the set of upper case letters only.
3553Lower case letters
3554and special symbols
3555are used internally.
3556Long names beginning with a lower case letter or a punctuation character
3557are reserved for use by sendmail,
3558so user-defined long macro names should begin with an upper case letter.
3559.pp
3560The syntax for macro definitions is:
3561.(b F
3562.b D \c
3563.i x\|val
3564.)b
3565where
3566.i x
3567is the name of the macro
3568(which may be a single character
3569or a word in braces)
3570and
3571.i val
3572is the value it should have.
3573There should be no spaces given
3574that do not actually belong in the macro value.
3575.pp
3576Macros are interpolated
3577using the construct
3578.b $ \c
3579.i x ,
3580where
3581.i x
3582is the name of the macro to be interpolated.
3583This interpolation is done when the configuration file is read,
3584except in
3585.b M
3586lines.
3587The special construct
3588.b $& \c
3589.i x
3590can be used in
3591.b R
3592lines to get deferred interpolation.
3593.pp
3594Conditionals can be specified using the syntax:
3595.(b
3596$?x text1 $| text2 $.
3597.)b
3598This interpolates
3599.i text1
3600if the macro
3601.b $x
3602is set,
3603and
3604.i text2
3605otherwise.
3606The
3607.q else
3608(\c
3609.b $| )
3610clause may be omitted.
3611.pp
3612Lower case macro names are reserved to have
3613special semantics,
3614used to pass information in or out of
3615.i sendmail ,
3616and special characters are reserved to
3617provide conditionals, etc.
3618Upper case names
3619(that is,
3620.b $A
3621through
3622.b $Z )
3623are specifically reserved for configuration file authors.
3624.pp
3625The following macros are defined and/or used internally by
3626.i sendmail
3627for interpolation into argv's for mailers
3628or for other contexts.
3629The ones marked \(dg are information passed into sendmail\**,
3630.(f
3631\**As of version 8.6,
3632all of these macros have reasonable defaults.
3633Previous versions required that they be defined.
3634.)f
3635the ones marked \(dd are information passed both in and out of sendmail,
3636and the unmarked macros are passed out of sendmail
3637but are not otherwise used internally.
3638These macros are:
3639.nr ii 5n
3640.ip $a
3641The origination date in RFC 822 format.
3642This is extracted from the Date: line.
3643.ip $b
3644The current date in RFC 822 format.
3645.ip $c
3646The hop count.
3647This is a count of the number of Received: lines
3648plus the value of the
3649.b \-h
3650command line flag.
3651.ip $d
3652The current date in UNIX (ctime) format.
3653.ip $e\(dg
3654(Obsolete; use SmtpGreetingMessage option instead.)
3655The SMTP entry message.
3656This is printed out when SMTP starts up.
3657The first word must be the
3658.b $j
3659macro as specified by RFC821.
3660Defaults to
3661.q "$j Sendmail $v ready at $b" .
3662Commonly redefined to include the configuration version number, e.g.,
3663.q "$j Sendmail $v/$Z ready at $b"
3664.ip $f
3665The envelope sender (from) address.
3666.ip $g
3667The sender address relative to the recipient.
3668For example, if
3669.b $f
3670is
3671.q foo ,
3672.b $g
3673will be
3674.q host!foo ,
3675.q foo@host.domain ,
3676or whatever is appropriate for the receiving mailer.
3677.ip $h
3678The recipient host.
3679This is set in ruleset 0 from the $@ field of a parsed address.
3680.ip $i
3681The queue id,
3682e.g.,
3683.q HAA12345 .
3684.ip $j\(dd
3685The \*(lqofficial\*(rq domain name for this site.
3686This is fully qualified if the full qualification can be found.
3687It
3688.i must
3689be redefined to be the fully qualified domain name
3690if your system is not configured so that information can find
3691it automatically.
3692.ip $k
3693The UUCP node name (from the uname system call).
3694.ip $l\(dg
3695(Obsolete; use UnixFromLine option instead.)
3696The format of the UNIX from line.
3697Unless you have changed the UNIX mailbox format,
3698you should not change the default,
3699which is
3700.q "From $g $d" .
3701.ip $m
3702The domain part of the \fIgethostname\fP return value.
3703Under normal circumstances,
3704.b $j
3705is equivalent to
3706.b $w.$m .
3707.ip $n\(dg
3708The name of the daemon (for error messages).
3709Defaults to
3710.q MAILER-DAEMON .
3711.ip $o\(dg
3712(Obsolete: use OperatorChars option instead.)
3713The set of \*(lqoperators\*(rq in addresses.
3714A list of characters
3715which will be considered tokens
3716and which will separate tokens
3717when doing parsing.
3718For example, if
3719.q @
3720were in the
3721.b $o
3722macro, then the input
3723.q a@b
3724would be scanned as three tokens:
3725.q a,
3726.q @,
3727and
3728.q b.
3729Defaults to
3730.q ".:@[]" ,
3731which is the minimum set necessary to do RFC 822 parsing;
3732a richer set of operators is
3733.q ".:%@!/[]" ,
3734which adds support for UUCP, the %-hack, and X.400 addresses.
3735.ip $p
3736Sendmail's process id.
3737.ip $q\(dg
3738Default format of sender address.
3739The
3740.b $q
3741macro specifies how an address should appear in a message
3742when it is defaulted.
3743Defaults to
3744.q "<$g>" .
3745It is commonly redefined to be
3746.q "$?x$x <$g>$|$g$."
3747or
3748.q "$g$?x ($x)$." ,
3749corresponding to the following two formats:
3750.(b
3751Eric Allman <eric@CS.Berkeley.EDU>
3752eric@CS.Berkeley.EDU (Eric Allman)
3753.)b
3754.i Sendmail
3755properly quotes names that have special characters
3756if the first form is used.
3757.ip $r
3758Protocol used to receive the message.
3759Set from the
3760.b \-p
3761command line flag or by the SMTP server code.
3762.ip $s
3763Sender's host name.
3764Set from the
3765.b \-p
3766command line flag or by the SMTP server code.
3767.ip $t
3768A numeric representation of the current time.
3769.ip $u
3770The recipient user.
3771.ip $v
3772The version number of the
3773.i sendmail
3774binary.
3775.ip $w\(dd
3776The hostname of this site.
3777This is the root name of this host (but see below for caveats).
3778.ip $x
3779The full name of the sender.
3780.ip $z
3781The home directory of the recipient.
3782.ip $_
3783The validated sender address.
3784.ip ${bodytype}
3785The message body type
3786(7BIT or 8BITMIME),
3787as determined from the envelope.
3788.ip ${client_addr}
3789The IP address of the SMTP client.
3790Defined in the SMTP server only.
3791.ip ${client_name}
3792The host name of the SMTP client.
3793This may be the client's bracketed IP address
3794in the form [ nnn.nnn.nnn.nnn ] if the client's
3795IP address is not resolvable.
3796Defined in the SMTP server only.
3797.ip ${client_port}
3798The port number of the SMTP client.
3799Defined in the SMTP server only.
3800.ip ${envid}
3801The envelope id passed to sendmail as part of the envelope.
3802.ip ${opMode}
3803The current operation mode (from the
3804.b \-b
3805flag).
3806.ip ${deliveryMode}
3807The current delivery mode
3808(from the
3809.b DeliveryMode
3810option).
3811.pp
3812There are three types of dates that can be used.
3813The
3814.b $a
3815and
3816.b $b
3817macros are in RFC 822 format;
3818.b $a
3819is the time as extracted from the
3820.q Date:
3821line of the message
3822(if there was one),
3823and
3824.b $b
3825is the current date and time
3826(used for postmarks).
3827If no
3828.q Date:
3829line is found in the incoming message,
3830.b $a
3831is set to the current time also.
3832The
3833.b $d
3834macro is equivalent to the
3835.b $b
3836macro in UNIX
3837(ctime)
3838format.
3839.pp
3840The macros
3841.b $w ,
3842.b $j ,
3843and
3844.b $m
3845are set to the identity of this host.
3846.i Sendmail
3847tries to find the fully qualified name of the host
3848if at all possible;
3849it does this by calling
3850.i gethostname (2)
3851to get the current hostname
3852and then passing that to
3853.i gethostbyname (3)
3854which is supposed to return the canonical version of that host name.\**
3855.(f
3856\**For example, on some systems
3857.i gethostname
3858might return
3859.q foo
3860which would be mapped to
3861.q foo.bar.com
3862by
3863.i gethostbyname .
3864.)f
3865Assuming this is successful,
3866.b $j
3867is set to the fully qualified name
3868and
3869.b $m
3870is set to the domain part of the name
3871(everything after the first dot).
3872The
3873.b $w
3874macro is set to the first word
3875(everything before the first dot)
3876if you have a level 5 or higher configuration file;
3877otherwise, it is set to the same value as
3878.b $j .
3879If the canonification is not successful,
3880it is imperative that the config file set
3881.b $j
3882to the fully qualified domain name\**.
3883.(f
3884\**Older versions of sendmail didn't pre-define
3885.b $j
3886at all, so up until 8.6,
3887config files
3888.i always
3889had to define
3890.b $j .
3891.)f
3892.pp
3893The
3894.b $f
3895macro is the id of the sender
3896as originally determined;
3897when mailing to a specific host
3898the
3899.b $g
3900macro is set to the address of the sender
3901.ul
3902relative to the recipient.
3903For example,
3904if I send to
3905.q bollard@matisse.CS.Berkeley.EDU
3906from the machine
3907.q vangogh.CS.Berkeley.EDU
3908the
3909.b $f
3910macro will be
3911.q eric
3912and the
3913.b $g
3914macro will be
3915.q eric@vangogh.CS.Berkeley.EDU.
3916.pp
3917The
3918.b $x
3919macro is set to the full name of the sender.
3920This can be determined in several ways.
3921It can be passed as flag to
3922.i sendmail .
3923It can be defined in the
3924.sm NAME
3925environment variable.
3926The third choice is the value of the
3927.q Full-Name:
3928line in the header if it exists,
3929and the fourth choice is the comment field
3930of a
3931.q From:
3932line.
3933If all of these fail,
3934and if the message is being originated locally,
3935the full name is looked up in the
3936.i /etc/passwd
3937file.
3938.pp
3939When sending,
3940the
3941.b $h ,
3942.b $u ,
3943and
3944.b $z
3945macros get set to the host, user, and home directory
3946(if local)
3947of the recipient.
3948The first two are set from the
3949.b $@
3950and
3951.b $:
3952part of the rewriting rules, respectively.
3953.pp
3954The
3955.b $p
3956and
3957.b $t
3958macros are used to create unique strings
3959(e.g., for the
3960.q Message-Id:
3961field).
3962The
3963.b $i
3964macro is set to the queue id on this host;
3965if put into the timestamp line
3966it can be extremely useful for tracking messages.
3967The
3968.b $v
3969macro is set to be the version number of
3970.i sendmail ;
3971this is normally put in timestamps
3972and has been proven extremely useful for debugging.
3973.pp
3974The
3975.b $c
3976field is set to the
3977.q "hop count,"
3978i.e., the number of times this message has been processed.
3979This can be determined
3980by the
3981.b \-h
3982flag on the command line
3983or by counting the timestamps in the message.
3984.pp
3985The
3986.b $r
3987and
3988.b $s
3989fields are set to the protocol used to communicate with
3990.i sendmail
3991and the sending hostname.
3992They can be set together using the
3993.b \-p
3994command line flag or separately using the
3995.b \-M
3996or
3997.b \-oM
3998flags.
3999.pp
4000The
4001.b $_
4002is set to a validated sender host name.
4003If the sender is running an RFC 1413 compliant IDENT server
4004and the receiver has the IDENT protocol turned on,
4005it will include the user name on that host.
4006.pp
4007The
4008.b ${client_name} ,
4009.b ${client_addr} ,
4010and
4011.b ${client_port}
4012macros
4013are set to the name, address, and port number of the SMTP client
4014who is invoking
4015.i sendmail
4016as a server.
4017These can be used in the
4018.i check_*
4019rulesets (using the
4020.b $&
4021deferred evaluation form, of course!).
4022.sh 2 "C and F \*- Define Classes"
4023.pp
4024Classes of phrases may be defined
4025to match on the left hand side of rewriting rules,
4026where a
4027.q phrase
4028is a sequence of characters that does not contain space characters.
4029For example
4030a class of all local names for this site
4031might be created
4032so that attempts to send to oneself
4033can be eliminated.
4034These can either be defined directly in the configuration file
4035or read in from another file.
4036Classes are named as a single letter or a word in {braces}.
4037Class names beginning with lower case letters
4038and special characters are reserved for system use.
4039Classes defined in config files may be given names
4040from the set of upper case letters for short names
4041or beginning with an upper case letter for long names.
4042.pp
4043The syntax is:
4044.(b F
4045.b C \c
4046.i c\|phrase1
4047.i phrase2...
4048.br
4049.b F \c
4050.i c\|file
4051.)b
4052The first form defines the class
4053.i c
4054to match any of the named words.
4055It is permissible to split them among multiple lines;
4056for example, the two forms:
4057.(b
4058CHmonet ucbmonet
4059.)b
4060and
4061.(b
4062CHmonet
4063CHucbmonet
4064.)b
4065are equivalent.
4066The ``F'' form
4067reads the elements of the class
4068.i c
4069from the named
4070.i file .
4071.pp
4072Elements of classes can be accessed in rules using
4073.b $=
4074or
4075.b $~ .
4076The
4077.b $~
4078(match entries not in class)
4079only matches a single word;
4080multi-word entries in the class are ignored in this context.
4081.pp
4082Some classes have internal meaning to
4083.i sendmail :
4084.nr ii 0.5i
4085.\".ip $=b
4086.\"A set of Content-Types that will not have the newline character
4087.\"translated to CR-LF before encoding into base64 MIME.
4088.\"The class can have major times
4089.\"(e.g.,
4090.\".q image )
4091.\"or full types
4092.\"(such as
4093.\".q application/octet-stream ).
4094.\"The class is initialized with
4095.\".q application/octet-stream ,
4096.\".q image ,
4097.\".q audio ,
4098.\"and
4099.\".q video .
4100.ip $=e
4101contains the Content-Transfer-Encodings that can be 8\(->7 bit encoded.
4102It is predefined to contain
4103.q 7bit ,
4104.q 8bit ,
4105and
4106.q binary .
4107.ip $=k
4108set to be the same as
4109.b $k ,
4110that is, the UUCP node name.
4111.ip $=m
4112set to the set of domains by which this host is known,
4113initially just
4114.b $m .
4115.ip $=n
4116can be set to the set of MIME body types
4117that can never be eight to seven bit encoded.
4118It defaults to
4119.q multipart/signed .
4120Message types
4121.q message/*
4122and
4123.q multipart/*
4124are never encoded directly.
4125Multipart messages are always handled recursively.
4126The handling of message/* messages
4127are controlled by class
4128.b $=s .
4129.ip $=q
4130A set of Content-Types that will never be encoded as base64
4131(if they have to be encoded, they will be encoded as quoted-printable).
4132It can have primary types
4133(e.g.,
4134.q text )
4135or full types
4136(such as
4137.q text/plain ).
4138The class is initialized to have
4139.q text/plain
4140only.
4141.ip $=s
4142contains the set of subtypes of message that can be treated recursively.
4143By default it contains only
4144.q rfc822 .
4145Other
4146.q message/*
4147types cannot be 8\(->7 bit encoded.
4148If a message containing eight bit data is sent to a seven bit host,
4149and that message cannot be encoded into seven bits,
4150it will be stripped to 7 bits.
4151.ip $=t
4152set to the set of trusted users by the
4153.b T
4154configuration line.
4155If you want to read trusted users from a file, use
4156.b Ft \c
4157.i /file/name .
4158.ip $=w
4159set to be the set of all names
4160this host is known by.
4161This can be used to match local hostnames.
4162.pp
4163.i Sendmail
4164can be compiled to allow a
4165.i scanf (3)
4166string on the
4167.b F
4168line.
4169This lets you do simplistic parsing of text files.
4170For example, to read all the user names in your system
4171.i /etc/passwd
4172file into a class, use
4173.(b
4174FL/etc/passwd %[^:]
4175.)b
4176which reads every line up to the first colon.
4177.sh 2 "M \*- Define Mailer"
4178.pp
4179Programs and interfaces to mailers
4180are defined in this line.
4181The format is:
4182.(b F
4183.b M \c
4184.i name ,
4185{\c
4186.i field =\c
4187.i value \|}*
4188.)b
4189where
4190.i name
4191is the name of the mailer
4192(used internally only)
4193and the
4194.q field=name
4195pairs define attributes of the mailer.
4196Fields are:
4197.(b
4198.ta 1i
4199Path The pathname of the mailer
4200Flags Special flags for this mailer
4201Sender Rewriting set(s) for sender addresses
4202Recipient Rewriting set(s) for recipient addresses
4203Argv An argument vector to pass to this mailer
4204Eol The end-of-line string for this mailer
4205Maxsize The maximum message length to this mailer
4206Linelimit The maximum line length in the message body
4207Directory The working directory for the mailer
4208Userid The default user and group id to run as
4209Nice The nice(2) increment for the mailer
4210Charset The default character set for 8-bit characters
4211Type The MTS type information (used for error messages)
4212.)b
4213Only the first character of the field name is checked.
4214.pp
4215The following flags may be set in the mailer description.
4216Any other flags may be used freely
4217to conditionally assign headers to messages
4218destined for particular mailers.
4219Flags marked with \(dg
4220are not interpreted by the
4221.i sendmail
4222binary;
4223these are the conventionally used to correlate to the flags portion
4224of the
4225.b H
4226line.
4227Flags marked with \(dd
4228apply to the mailers for the sender address
4229rather than the usual recipient mailers.
4230.nr ii 4n
4231.ip a
4232Run Extended SMTP (ESMTP) protocol (defined in RFCs 1869, 1652, and 1870).
4233This flag defaults on if the SMTP greeting message includes the word
4234.q ESMTP .
4235.ip A
4236Look up the user part of the address in the alias database.
4237Normally this is only set for local mailers.
4238.ip b
4239Force a blank line on the end of a message.
4240This is intended to work around some stupid versions of
4241/bin/mail
4242that require a blank line, but do not provide it themselves.
4243It would not normally be used on network mail.
4244.ip c
4245Do not include comments in addresses.
4246This should only be used if you have to work around
4247a remote mailer that gets confused by comments.
4248This strips addresses of the form
4249.q "Phrase <address>"
4250or
4251.q "address (Comment)"
4252down to just
4253.q address .
4254.ip C\(dd
4255If mail is
4256.i received
4257from a mailer with this flag set,
4258any addresses in the header that do not have an at sign
4259(\c
4260.q @ )
4261after being rewritten by ruleset three
4262will have the
4263.q @domain
4264clause from the sender envelope address
4265tacked on.
4266This allows mail with headers of the form:
4267.(b
4268From: usera@hosta
4269To: userb@hostb, userc
4270.)b
4271to be rewritten as:
4272.(b
4273From: usera@hosta
4274To: userb@hostb, userc@hosta
4275.)b
4276automatically.
4277However, it doesn't really work reliably.
4278.ip d
4279Do not include angle brackets around route-address syntax addresses.
4280This is useful on mailers that are going to pass addresses to a shell
4281that might interpret angle brackets as I/O redirection.
4282.ip D\(dg
4283This mailer wants a
4284.q Date:
4285header line.
4286.ip e
4287This mailer is expensive to connect to,
4288so try to avoid connecting normally;
4289any necessary connection will occur during a queue run.
4290.ip E
4291Escape lines beginning with
4292.q From\0
4293in the message with a `>' sign.
4294.ip f
4295The mailer wants a
4296.b \-f
4297.i from
4298flag,
4299but only if this is a network forward operation
4300(i.e.,
4301the mailer will give an error
4302if the executing user
4303does not have special permissions).
4304.ip F\(dg
4305This mailer wants a
4306.q From:
4307header line.
4308.ip g
4309Normally,
4310.i sendmail
4311sends internally generated email (e.g., error messages)
4312using the null return address
4313as required by RFC 1123.
4314However, some mailers don't accept a null return address.
4315If necessary,
4316you can set the
4317.b g
4318flag to prevent
4319.i sendmail
4320from obeying the standards;
4321error messages will be sent as from the MAILER-DAEMON
4322(actually, the value of the
4323.b $n
4324macro).
4325.ip h
4326Upper case should be preserved in host names
4327for this mailer.
4328.ip i
4329Do User Database rewriting on envelope sender address.
4330.ip I
4331This mailer will be speaking SMTP
4332to another
4333.i sendmail
4334\*-
4335as such it can use special protocol features.
4336This option is not required
4337(i.e.,
4338if this option is omitted the transmission will still operate successfully,
4339although perhaps not as efficiently as possible).
4340.ip j
4341Do User Database rewriting on recipients as well as senders.
4342.ip k
4343Normally when
4344.i sendmail
4345connects to a host via SMTP,
4346it checks to make sure that this isn't accidently the same host name
4347as might happen if
4348.i sendmail
4349is misconfigured or if a long-haul network interface is set in loopback mode.
4350This flag disables the loopback check.
4351It should only be used under very unusual circumstances.
4352.ip K
4353Currently unimplemented.
4354Reserved for chunking.
4355.ip l
4356This mailer is local
4357(i.e.,
4358final delivery will be performed).
4359.ip L
4360Limit the line lengths as specified in RFC821.
4361This deprecated option should be replaced by the
4362.b L=
4363mail declaration.
4364For historic reasons, the
4365.b L
4366flag also sets the
4367.b 7
4368flag.
4369.ip m
4370This mailer can send to multiple users
4371on the same host
4372in one transaction.
4373When a
4374.b $u
4375macro occurs in the
4376.i argv
4377part of the mailer definition,
4378that field will be repeated as necessary
4379for all qualifying users.
4380.ip M\(dg
4381This mailer wants a
4382.q Message-Id:
4383header line.
4384.ip n
4385Do not insert a UNIX-style
4386.q From
4387line on the front of the message.
4388.ip o
4389Always run as the owner of the recipient mailbox.
4390Normally
4391.i sendmail
4392runs as the sender for locally generated mail
4393or as
4394.q daemon
4395(actually, the user specified in the
4396.b u
4397option)
4398when delivering network mail.
4399The normal behaviour is required by most local mailers,
4400which will not allow the envelope sender address
4401to be set unless the mailer is running as daemon.
4402This flag is ignored if the
4403.b S
4404flag is set.
4405.ip p
4406Use the route-addr style reverse-path in the SMTP
4407.q "MAIL FROM:"
4408command
4409rather than just the return address;
4410although this is required in RFC821 section 3.1,
4411many hosts do not process reverse-paths properly.
4412Reverse-paths are officially discouraged by RFC 1123.
4413.ip P\(dg
4414This mailer wants a
4415.q Return-Path:
4416line.
4417.ip q
4418When an address that resolves to this mailer is verified
4419(SMTP VRFY command),
4420generate 250 responses instead of 252 responses.
4421This will imply that the address is local.
4422.ip r
4423Same as
4424.b f ,
4425but sends a
4426.b \-r
4427flag.
4428.ip R
4429Open SMTP connections from a
4430.q secure
4431port.
4432Secure ports aren't
4433(secure, that is)
4434except on UNIX machines,
4435so it is unclear that this adds anything.
4436.ip s
4437Strip quote characters (" and \e) off of the address
4438before calling the mailer.
4439.ip S
4440Don't reset the userid
4441before calling the mailer.
4442This would be used in a secure environment
4443where
4444.i sendmail
4445ran as root.
4446This could be used to avoid forged addresses.
4447If the
4448.b U=
4449field is also specified,
4450this flag causes the user id to always be set to that user and group
4451(instead of leaving it as root).
4452.ip u
4453Upper case should be preserved in user names
4454for this mailer.
4455.ip U
4456This mailer wants UUCP-style
4457.q From
4458lines with the ugly
4459.q "remote from <host>"
4460on the end.
4461.ip w
4462The user must have a valid account on this machine,
4463i.e.,
4464getpwnam
4465must succeed.
4466If not,
4467the mail is bounced.
4468This is required to get
4469.q \&.forward
4470capability.
4471.ip x\(dg
4472This mailer wants a
4473.q Full-Name:
4474header line.
4475.ip X
4476This mailer want to use the hidden dot algorithm
4477as specified in RFC821;
4478basically,
4479any line beginning with a dot
4480will have an extra dot prepended
4481(to be stripped at the other end).
4482This insures that lines in the message containing a dot
4483will not terminate the message prematurely.
4484.ip z
4485Run Local Mail Transfer Protocol (LMTP)
4486between
4487.i sendmail
4488and the local mailer.
4489This is a variant on SMTP
4490defined in RFC 2033
4491that is specifically designed for delivery to a local mailbox.
4492.ip 0
4493Don't look up MX records for hosts sent via SMTP.
4494.ip 3
4495Extend the list of characters converted to =XX notation
4496when converting to Quoted-Printable
4497to include those that don't map cleanly between ASCII and EBCDIC.
4498Useful if you have IBM mainframes on site.
4499.ip 5
4500If no aliases are found for this address,
4501pass the address through ruleset 5 for possible alternate resolution.
4502This is intended to forward the mail to an alternate delivery spot.
4503.ip 7
4504Strip all output to seven bits.
4505This is the default if the
4506.b L
4507flag is set.
4508Note that clearing this option is not
4509sufficient to get full eight bit data passed through
4510.i sendmail .
4511If the
4512.b 7
4513option is set, this is essentially always set,
4514since the eighth bit was stripped on input.
4515Note that this option will only impact messages
4516that didn't have 8\(->7 bit MIME conversions performed.
4517.ip 8
4518If set,
4519it is acceptable to send eight bit data to this mailer;
4520the usual attempt to do 8\(->7 bit MIME conversions will be bypassed.
4521.ip 9
4522If set,
4523do
4524.i limited
45257\(->8 bit MIME conversions.
4526These conversions are limited to text/plain data.
4527.ip :
4528Check addresses to see if they begin
4529.q :include: ;
4530if they do, convert them to the
4531.q *include*
4532mailer.
4533.ip |
4534Check addresses to see if they begin with a `|';
4535if they do, convert them to the
4536.q prog
4537mailer.
4538.ip /
4539Check addresses to see if they begin with a `/';
4540if they do, convert them to the
4541.q *file*
4542mailer.
4543.ip @
4544Look up addresses in the user database.
4545.pp
4546Configuration files prior to level 6
4547assume the `A', `w', `5', `:', `|', `/', and `@' options
4548on the mailer named
4549.q local .
4550.pp
4551The mailer with the special name
4552.q error
4553can be used to generate a user error.
4554The (optional) host field is an exit status to be returned,
4555and the user field is a message to be printed.
4556The exit status may be numeric or one of the values
4557USAGE, NOUSER, NOHOST, UNAVAILABLE, SOFTWARE, TEMPFAIL, PROTOCOL, or CONFIG
4558to return the corresponding EX_ exit code,
4559or an enhanced error code as described in RFC 1893,
4560.ul
4561Enhanced Mail System Status Codes.
4562For example, the entry:
4563.(b
4564$#error $@ NOHOST $: Host unknown in this domain
4565.)b
4566on the RHS of a rule
4567will cause the specified error to be generated
4568and the
4569.q "Host unknown"
4570exit status to be returned
4571if the LHS matches.
4572This mailer is only functional in rulesets 0, 5,
4573or one of the check_* rulesets.
4574.pp
4575The mailer with the special name
4576.q discard
4577causes any mail sent to it to be discarded
4578but otherwise treated as though it were successfully delivered.
4579.pp
4580The mailer named
4581.q local
4582.i must
4583be defined in every configuration file.
4584This is used to deliver local mail,
4585and is treated specially in several ways.
4586Additionally, three other mailers named
4587.q prog ,
4588.q *file* ,
4589and
4590.q *include*
4591may be defined to tune the delivery of messages to programs,
4592files,
4593and :include: lists respectively.
4594They default to:
4595.(b
4596Mprog, P=/bin/sh, F=lsoDq9, T=DNS/RFC822/X-Unix, A=sh \-c $u
4597M*file*, P=[FILE], F=lsDFMPEouq9, T=DNS/RFC822/X-Unix, A=FILE $u
4598M*include*, P=/dev/null, F=su, A=INCLUDE $u
4599.)b
4600.pp
4601The Sender and Recipient rewriting sets
4602may either be a simple ruleset id
4603or may be two ids separated by a slash;
4604if so, the first rewriting set is applied to envelope
4605addresses
4606and the second is applied to headers.
4607Setting any value zero disables corresponding mailer-specific rewriting.
4608.pp
4609The Directory
4610is actually a colon-separated path of directories to try.
4611For example, the definition
4612.q D=$z:/
4613first tries to execute in the recipient's home directory;
4614if that is not available,
4615it tries to execute in the root of the filesystem.
4616This is intended to be used only on the
4617.q prog
4618mailer,
4619since some shells (such as
4620.i csh )
4621refuse to execute if they cannot read the home directory.
4622Since the queue directory is not normally readable by unprivileged users
4623.i csh
4624scripts as recipients can fail.
4625.pp
4626The Userid
4627specifies the default user and group id to run as,
4628overriding the
4629.b DefaultUser
4630option (q.v.).
4631If the
4632.b S
4633mailer flag is also specified,
4634this is the user and group to run as in all circumstances.
4635This may be given as
4636.i user:group
4637to set both the user and group id;
4638either may be an integer or a symbolic name to be looked up
4639in the
4640.i passwd
4641and
4642.i group
4643files respectively.
4644If only a symbolic user name is specified,
4645the group id in the
4646.i passwd
4647file for that user is used as the group id.
4648.pp
4649The Charset field
4650is used when converting a message to MIME;
4651this is the character set used in the
4652Content-Type: header.
4653If this is not set, the
4654.b DefaultCharset
4655option is used,
4656and if that is not set, the value
4657.q unknown-8bit
4658is used.
4659.b WARNING:
4660this field applies to the sender's mailer,
4661not the recipient's mailer.
4662For example, if the envelope sender address
4663lists an address on the local network
4664and the recipient is on an external network,
4665the character set will be set from the Charset= field
4666for the local network mailer,
4667not that of the external network mailer.
4668.pp
4669The Type= field
4670sets the type information
4671used in MIME error messages
4672as defined by
4673RFC 1894.
4674It is actually three values separated by slashes:
4675the MTA-type (that is, the description of how hosts are named),
4676the address type (the description of e-mail addresses),
4677and the diagnostic type (the description of error diagnostic codes).
4678Each of these must be a registered value
4679or begin with
4680.q X\- .
4681The default is
4682.q dns/rfc822/smtp .
4683.sh 2 "H \*- Define Header"
4684.pp
4685The format of the header lines that
4686.i sendmail
4687inserts into the message
4688are defined by the
4689.b H
4690line.
4691The syntax of this line is:
4692.(b F
4693.b H [\c
4694.b ? \c
4695.i mflags \c
4696.b ? ]\c
4697.i hname \c
4698.b :
4699.i htemplate
4700.)b
4701Continuation lines in this spec
4702are reflected directly into the outgoing message.
4703The
4704.i htemplate
4705is macro-expanded before insertion into the message.
4706If the
4707.i mflags
4708(surrounded by question marks)
4709are specified,
4710at least one of the specified flags
4711must be stated in the mailer definition
4712for this header to be automatically output.
4713If one of these headers is in the input
4714it is reflected to the output
4715regardless of these flags.
4716.pp
4717Some headers have special semantics
4718that will be described later.
4719.pp
4720A secondary syntax allows validation of headers as they are being read.
4721To enable validation, use:
4722.(b
4723.b H \c
4724.i Header \c
4725.b ": $>" \c
4726.i Ruleset
4727.)b
4728The indicated
4729.i Ruleset
4730is called for the specified
4731.i Header ,
4732and can return
4733.b $#error
4734to reject the message or
4735.b $#discard
4736to discard the message
4737(as with the other
4738.b check_ *
4739rulesets).
4740The header is treated as a structured field,
4741that is,
4742comments (in parentheses) are deleted before processing.
4743.pp
4744For example, the configuration lines:
4745.(b
4746HMessage-Id: $>CheckMessageId
4747
4748SCheckMessageId
4749R< $+ @ $+ > $@ OK
4750R$* $#error $: Illegal Message-Id header
4751.)b
4752would refuse any message that had a Message-Id: header of any of the
4753following forms:
4754.(b
4755Message-Id: <>
4756Message-Id: some text
4757Message-Id: <legal text@domain> extra crud
4758.)b
4759.sh 2 "O \*- Set Option"
4760.pp
4761There are a number of
4762global
4763options that
4764can be set from a configuration file.
4765Options are represented by full words;
4766some are also representable as single characters
4767for back compatibility.
4768The syntax of this line is:
4769.(b F
4770.b O \0
4771.i option \c
4772.b = \c
4773.i value
4774.)b
4775This sets option
4776.i option
4777to be
4778.i value .
4779Note that there
4780.i must
4781be a space between the letter `O' and the name of the option.
4782An older version is:
4783.(b F
4784.b O \c
4785.i o\|value
4786.)b
4787where the option
4788.i o
4789is a single character.
4790Depending on the option,
4791.i value
4792may be a string, an integer,
4793a boolean
4794(with legal values
4795.q t ,
4796.q T ,
4797.q f ,
4798or
4799.q F ;
4800the default is TRUE),
4801or
4802a time interval.
4803.pp
4804The options supported (with the old, one character names in brackets) are:
4805.nr ii 1i
4806.ip "AliasFile=\fIspec, spec, ...\fP"
4807[A]
4808Specify possible alias file(s).
4809Each
4810.i spec
4811should be in the format
4812``\c
4813.i class \c
4814.b :
4815.i file ''
4816where
4817.i class \c
4818.b :
4819is optional and defaults to ``implicit''.
4820Depending on how
4821.i sendmail
4822is compiled, valid classes are
4823.q implicit
4824(search through a compiled-in list of alias file types,
4825for back compatibility),
4826.q hash
4827(if
4828.sm NEWDB
4829is specified),
4830.q dbm
4831(if
4832.sm NDBM
4833is specified),
4834.q stab
4835(internal symbol table \*- not normally used
4836unless you have no other database lookup),
4837or
4838.q nis
4839(if
4840.sm NIS
4841is specified).
4842If a list of
4843.i spec s
4844are provided,
4845.i sendmail
4846searches them in order.
4847.ip AliasWait=\fItimeout\fP
4848[a]
4849If set,
4850wait up to
4851.i timeout
4852(units default to minutes)
4853for an
4854.q @:@
4855entry to exist in the alias database
4856before starting up.
4857If it does not appear in the
4858.i timeout
4859interval
4860rebuild the database
4861(if the
4862.b AutoRebuildAliases
4863option is also set)
4864or issue a warning.
4865.ip AllowBogusHELO
4866[no short name]
4867If set, allow HELO SMTP commands that don't include a host name.
4868Setting this violates RFC 1123 section 5.2.5,
4869but is necessary to interoperate with several SMTP clients.
4870If there is a value, it is still checked for legitimacy.
4871.ip AutoRebuildAliases
4872[D]
4873If set,
4874rebuild the alias database if necessary and possible.
4875If this option is not set,
4876.i sendmail
4877will never rebuild the alias database
4878unless explicitly requested
4879using
4880.b \-bi .
4881Not recommended \(em can cause thrashing.
4882.ip BlankSub=\fIc\fP
4883[B]
4884Set the blank substitution character to
4885.i c .
4886Unquoted spaces in addresses are replaced by this character.
4887Defaults to space (i.e., no change is made).
4888.ip CheckAliases
4889[n]
4890Validate the RHS of aliases when rebuilding the alias database.
4891.ip CheckpointInterval=\fIN\fP
4892[C]
4893Checkpoints the queue every
4894.i N
4895(default 10)
4896addresses sent.
4897If your system crashes during delivery to a large list,
4898this prevents retransmission to any but the last
4899.I N
4900recipients.
4901.ip ClassFactor=\fIfact\fP
4902[z]
4903The indicated
4904.i fact or
4905is multiplied by the message class
4906(determined by the Precedence: field in the user header
4907and the
4908.b P
4909lines in the configuration file)
4910and subtracted from the priority.
4911Thus, messages with a higher Priority: will be favored.
4912Defaults to 1800.
4913.ip ColonOkInAddr
4914[no short name]
4915If set, colons are acceptable in e-mail addresses
4916(e.g.,
4917.q host:user ).
4918If not set, colons indicate the beginning of a RFC 822 group construct
4919(\c
4920.q "groupname: member1, member2, ... memberN;" ).
4921Doubled colons are always acceptable
4922(\c
4923.q nodename::user )
4924and proper route-addr nesting is understood
4925(\c
4926.q <@relay:user@host> ).
4927Furthermore, this option defaults on if the configuration version level
4928is less than 6 (for back compatibility).
4929However, it must be off for full compatibility with RFC 822.
4930.ip ConnectionCacheSize=\fIN\fP
4931[k]
4932The maximum number of open connections that will be cached at a time.
4933The default is one.
4934This delays closing the current connection until
4935either this invocation of
4936.i sendmail
4937needs to connect to another host
4938or it terminates.
4939Setting it to zero defaults to the old behavior,
4940that is, connections are closed immediately.
4941Since this consumes file descriptors,
4942the connection cache should be kept small:
49434 is probably a practical maximum.
4944.ip ConnectionCacheTimeout=\fItimeout\fP
4945[K]
4946The maximum amount of time a cached connection will be permitted to idle
4947without activity.
4948If this time is exceeded,
4949the connection is immediately closed.
4950This value should be small (on the order of ten minutes).
4951Before
4952.i sendmail
4953uses a cached connection,
4954it always sends a RSET command
4955to check the connection;
4956if this fails, it reopens the connection.
4957This keeps your end from failing if the other end times out.
4958The point of this option is to be a good network neighbor
4959and avoid using up excessive resources
4960on the other end.
4961The default is five minutes.
4962.ip ConnectionRateThrottle=\fIN\fP
4963[no short name]
4964If set to a positive value,
4965allow no more than
4966.i N
4967incoming daemon connections in a one second period.
4968This is intended to flatten out peaks
4969and allow the load average checking to cut in.
4970Defaults to zero (no limits).
4971.ip DaemonPortOptions=\fIoptions\fP
4972[O]
4973Set server SMTP options.
4974The options are
4975.i key=value
4976pairs.
4977Known keys are:
4978.(b
4979.ta 1i
4980Port Name/number of listening port (defaults to "smtp")
4981Addr Address mask (defaults INADDR_ANY)
4982Family Address family (defaults to INET)
4983Listen Size of listen queue (defaults to 10)
4984SndBufSize Size of TCP send buffer
4985RcvBufSize Size of TCP receive buffer
4986.)b
4987The
4988.i Addr ess
4989mask may be a numeric address in dot notation
4990or a network name.
4991.ip DefaultCharSet=\fIcharset\fP
4992[no short name]
4993When a message that has 8-bit characters but is not in MIME format
4994is converted to MIME
4995(see the EightBitMode option)
4996a character set must be included in the Content-Type: header.
4997This character set is normally set from the Charset= field
4998of the mailer descriptor.
4999If that is not set, the value of this option is used.
5000If this option is not set, the value
5001.q unknown-8bit
5002is used.
5003.ip DefaultUser=\fIuser:group\fP
5004[u]
5005Set the default userid for mailers to
5006.i user:group .
5007If
5008.i group
5009is omitted and
5010.i user
5011is a user name
5012(as opposed to a numeric user id)
5013the default group listed in the /etc/passwd file for that user is used
5014as the default group.
5015Both
5016.i user
5017and
5018.i group
5019may be numeric.
5020Mailers without the
5021.i S
5022flag in the mailer definition
5023will run as this user.
5024Defaults to 1:1.
5025The value can also be given as a symbolic user name.\**
5026.(f
5027\**The old
5028.b g
5029option has been combined into the
5030.b DefaultUser
5031option.
5032.)f
5033.ip DeliveryMode=\fIx\fP
5034[d]
5035Deliver in mode
5036.i x .
5037Legal modes are:
5038.(b
5039.ta 4n
5040i Deliver interactively (synchronously)
5041b Deliver in background (asynchronously)
5042q Just queue the message (deliver during queue run)
5043d Defer delivery and all map lookups (deliver during queue run)
5044.)b
5045Defaults to ``b'' if no option is specified,
5046``i'' if it is specified but given no argument
5047(i.e., ``Od'' is equivalent to ``Odi'').
5048The
5049.b \-v
5050command line flag sets this to
5051.b i .
5052.ip DialDelay=\fIsleeptime\fP
5053[no short name]
5054Dial-on-demand network connections can see timeouts
5055if a connection is opened before the call is set up.
5056If this is set to an interval and a connection times out
5057on the first connection being attempted
5058.i sendmail
5059will sleep for this amount of time and try again.
5060This should give your system time to establish the connection
5061to your service provider.
5062Units default to seconds, so
5063.q DialDelay=5
5064uses a five second delay.
5065Defaults to zero
5066(no retry).
5067.ip DontBlameSendmail=\fIoption,option,...\fP
5068[no short name]
5069In order to avoid possible cracking attempts
5070caused by world- and group-writable files and directories,
5071.i sendmail
5072does paranoid checking when opening most of its support files.
5073If for some reason you absolutely must run with,
5074for example,
5075a group-writable
5076.i /etc
5077directory,
5078then you will have to turn off this checking
5079(at the cost of making your system more vulnerable to attack).
5080The arguments are individual options that turn off checking:
5081.(b
5082Safe
5083AssumeSafeChown
5084ClassFileInUnsafeDirPath
5085ErrorHeaderInUnsafeDirPath
5086FileDeliveryToHardLink
5087FileDeliveryToSymLink
5088ForwardFileInUnsafeDirPath
5089ForwardFileInUnsafeDirPathSafe
5090ForwardFileIngroupWritableDirPath
5091GroupWritableAliasFile
5092GroupWritableDirPathSafe
5093GroupWritableForwardFileSafe
5094GroupWritableIncludeFileSafe
5095HelpFileinUnsafeDirPath
5096IncludeFileInUnsafeDirPath
5097IncludeFileInUnsafeDirPathSafe
5098IncludeFileIngroupWritableDirPath
5099LinkedAliasFileInWritableDir
5100LinkedClassFileInWritableDir
5101LinkedForwardFileInWritableDir
5102LinkedIncludeFileInWritableDir
5103LinkedMapInWritableDir
5104LinkedServiceSwitchFileInWritableDir
5105MapInUnsafeDirPath
5106RunProgramInUnsafeDirPath
5107RunWritableProgram
5108WorldWritableAliasFile
5109WriteMapToHardLink
5110WriteMapToSymLink
5111WriteStatsToHardLink
5112WriteStatsToSymLink
5113.)b
5114.b Safe
5115is the default.
5116The details of these flags are described above.
5117.\"XXX should have more here!!! XXX
5118.b "Use of this option is not recommended."
5119.ip DontExpandCnames
5120[no short name]
5121The standards say that all host addresses used in a mail message
5122must be fully canonical.
5123For example, if your host is named
5124.q Cruft.Foo.ORG
5125and also has an alias of
5126.q FTP.Foo.ORG ,
5127the former name must be used at all times.
5128This is enforced during host name canonification
5129($[ ... $] lookups).
5130If this option is set, the protocols are ignored and the
5131.q wrong
5132thing is done.
5133However, the IETF is moving toward changing this standard,
5134so the behaviour may become acceptable.
5135Please note that hosts downstream may still rewrite the address
5136to be the true canonical name however.
5137.ip DontInitGroups
5138[no short name]
5139If set,
5140.i sendmail
5141will avoid using the initgroups(3) call.
5142If you are running NIS,
5143this causes a sequential scan of the groups.byname map,
5144which can cause your NIS server to be badly overloaded in a large domain.
5145The cost of this is that the only group found for users
5146will be their primary group (the one in the password file),
5147which will make file access permissions somewhat more restrictive.
5148Has no effect on systems that don't have group lists.
5149.ip DontProbeInterfaces
5150[no short name]
5151.i Sendmail
5152normally finds the names of all interfaces active on your machine
5153when it starts up
5154and adds their name to the
5155.b $=w
5156class of known host aliases.
5157If you have a large number of virtual interfaces
5158or if your DNS inverse lookups are slow
5159this can be time consuming.
5160This option turns off that probing.
5161However, you will need to be certain to include all variant names
5162in the
5163.b $=w
5164class by some other mechanism.
5165.ip DontPruneRoutes
5166[R]
5167Normally,
5168.i sendmail
5169tries to eliminate any unnecessary explicit routes
5170when sending an error message
5171(as discussed in RFC 1123 \(sc 5.2.6).
5172For example,
5173when sending an error message to
5174.(b
5175<@known1,@known2,@known3:user@unknown>
5176.)b
5177.i sendmail
5178will strip off the
5179.q @known1,@known2
5180in order to make the route as direct as possible.
5181However, if the
5182.b R
5183option is set, this will be disabled,
5184and the mail will be sent to the first address in the route,
5185even if later addresses are known.
5186This may be useful if you are caught behind a firewall.
5187.ip DoubleBounceAddress=\fIerror-address\fP
5188[no short name]
5189If an error occurs when sending an error message,
5190send the error report
5191(termed a
5192.q "double bounce"
5193because it is an error
5194.q bounce
5195that occurs when trying to send another error
5196.q bounce )
5197to the indicated address.
5198If not set, defaults to
5199.q postmaster .
5200.ip EightBitMode=\fIaction\fP
5201[8]
5202Set handling of eight-bit data.
5203There are two kinds of eight-bit data:
5204that declared as such using the
5205.b BODY=8BITMIME
5206ESMTP declaration or the
5207.b \-B8BITMIME
5208command line flag,
5209and undeclared 8-bit data, that is,
5210input that just happens to be eight bits.
5211There are three basic operations that can happen:
5212undeclared 8-bit data can be automatically converted to 8BITMIME,
5213undeclared 8-bit data can be passed as-is without conversion to MIME
5214(``just send 8''),
5215and declared 8-bit data can be converted to 7-bits
5216for transmission to a non-8BITMIME mailer.
5217The possible
5218.i action s
5219are:
5220.(b
5221.\" r Reject undeclared 8-bit data;
5222.\" don't convert 8BITMIME\(->7BIT (``reject'')
5223 s Reject undeclared 8-bit data (``strict'')
5224.\" do convert 8BITMIME\(->7BIT (``strict'')
5225.\" c Convert undeclared 8-bit data to MIME;
5226.\" don't convert 8BITMIME\(->7BIT (``convert'')
5227 m Convert undeclared 8-bit data to MIME (``mime'')
5228.\" do convert 8BITMIME\(->7BIT (``mime'')
5229.\" j Pass undeclared 8-bit data;
5230.\" don't convert 8BITMIME\(->7BIT (``just send 8'')
5231 p Pass undeclared 8-bit data (``pass'')
5232.\" do convert 8BITMIME\(->7BIT (``pass'')
5233.\" a Adaptive algorithm: see below
5234.)b
5235.\"The adaptive algorithm is to accept 8-bit data,
5236.\"converting it to 8BITMIME only if the receiver understands that,
5237.\"otherwise just passing it as undeclared 8-bit data;
5238.\"8BITMIME\(->7BIT conversions are done.
5239In all cases properly declared 8BITMIME data will be converted to 7BIT
5240as needed.
5241.ip ErrorHeader=\fIfile-or-message\fP
5242[E]
5243Prepend error messages with the indicated message.
5244If it begins with a slash,
5245it is assumed to be the pathname of a file
5246containing a message (this is the recommended setting).
5247Otherwise, it is a literal message.
5248The error file might contain the name, email address, and/or phone number
5249of a local postmaster who could provide assistance
5250in to end users.
5251If the option is missing or null,
5252or if it names a file which does not exist or which is not readable,
5253no message is printed.
5254.ip ErrorMode=\fIx\fP
5255[e]
5256Dispose of errors using mode
5257.i x .
5258The values for
5259.i x
5260are:
5261.(b
5262p Print error messages (default)
5263q No messages, just give exit status
5264m Mail back errors
5265w Write back errors (mail if user not logged in)
5266e Mail back errors and give zero exit stat always
5267.)b
5268.ip FallbackMXhost=\fIfallbackhost\fP
5269[V]
5270If specified, the
5271.i fallbackhost
5272acts like a very low priority MX
5273on every host.
5274This is intended to be used by sites with poor network connectivity.
5275.ip ForkEachJob
5276[Y]
5277If set,
5278deliver each job that is run from the queue in a separate process.
5279Use this option if you are short of memory,
5280since the default tends to consume considerable amounts of memory
5281while the queue is being processed.
5282.ip ForwardPath=\fIpath\fP
5283[J]
5284Set the path for searching for users' .forward files.
5285The default is
5286.q $z/.forward .
5287Some sites that use the automounter may prefer to change this to
5288.q /var/forward/$u
5289to search a file with the same name as the user in a system directory.
5290It can also be set to a sequence of paths separated by colons;
5291.i sendmail
5292stops at the first file it can successfully and safely open.
5293For example,
5294.q /var/forward/$u:$z/.forward
5295will search first in /var/forward/\c
5296.i username
5297and then in
5298.i ~username /.forward
5299(but only if the first file does not exist).
5300.ip HelpFile=\fIfile\fP
5301[H]
5302Specify the help file
5303for SMTP.
5304.ip HoldExpensive
5305[c]
5306If an outgoing mailer is marked as being expensive,
5307don't connect immediately.
5308This requires that queueing be compiled in,
5309since it will depend on a queue run process to
5310actually send the mail.
5311.ip HostsFile=\fIpath\fP
5312[no short name]
5313The path to the hosts database,
5314normally
5315.q /etc/hosts .
5316This option is only consulted when sendmail
5317is canonifying addresses,
5318and then only when
5319.q files
5320is in the
5321.q hosts
5322service switch entry.
5323In particular, this file is
5324.i never
5325used when looking up host addresses;
5326that is under the control of the system
5327.i gethostbyname (3)
5328routine.
5329.ip HostStatusDirectory=\fIpath\fP
5330[no short name]
5331The location of the long term host status information.
5332When set,
5333information about the status of hosts
5334(e.g., host down or not accepting connections)
5335will be shared between all
5336.i sendmail
5337processes;
5338normally, this information is only held within a single queue run.
5339This option requires a connection cache of at least 1 to function.
5340If the option begins with a leading `/',
5341it is an absolute pathname;
5342otherwise,
5343it is relative to the mail queue directory.
5344A suggested value for sites desiring persistent host status is
5345.q \&.hoststat
5346(i.e., a subdirectory of the queue directory).
5347.ip IgnoreDots
5348[i]
5349Ignore dots in incoming messages.
5350This is always disabled (that is, dots are always accepted)
5351when reading SMTP mail.
5352.ip LogLevel=\fIn\fP
5353[L]
5354Set the log level to
5355.i n .
5356Defaults to 9.
5357.ip M\fIx\|value\fP
5358[no long version]
5359Set the macro
5360.i x
5361to
5362.i value .
5363This is intended only for use from the command line.
5364The
5365.b \-M
5366flag is preferred.
5367.ip MatchGECOS
5368[G]
5369Allow fuzzy matching on the GECOS field.
5370If this flag is set,
5371and the usual user name lookups fail
5372(that is, there is no alias with this name and a
5373.i getpwnam
5374fails),
5375sequentially search the password file
5376for a matching entry in the GECOS field.
5377This also requires that MATCHGECOS
5378be turned on during compilation.
5379This option is not recommended.
5380.ip MaxDaemonChildren=\fIN\fP
5381[no short name]
5382If set,
5383.i sendmail
5384will refuse connections when it has more than
5385.i N
5386children processing incoming mail.
5387This does not limit the number of outgoing connections.
5388If not set, there is no limit to the number of children --
5389that is, the system load averaging controls this.
5390.ip MaxHopCount=\fIN\fP
5391[h]
5392The maximum hop count.
5393Messages that have been processed more than
5394.i N
5395times are assumed to be in a loop and are rejected.
5396Defaults to 25.
5397.ip MaxHostStatAge=\fIage\fP
5398[no short name]
5399Not yet implemented.
5400This option specifies how long host status information will be retained.
5401For example, if a host is found to be down,
5402connections to that host will not be retried for this interval.
5403The units default to minutes.
5404.ip MaxMessageSize=\fIN\fP
5405[no short name]
5406Specify the maximum message size
5407to be advertised in the ESMTP EHLO response.
5408Messages larger than this will be rejected.
5409.ip MaxQueueRunSize=\fIN\fP
5410[no short name]
5411The maximum number of jobs that will be processed
5412in a single queue run.
5413If not set, there is no limit on the size.
5414If you have very large queues or a very short queue run interval
5415this could be unstable.
5416However, since the first
5417.i N
5418jobs in queue directory order are run (rather than the
5419.i N
5420highest priority jobs)
5421this should be set as high as possible to avoid
5422.q losing
5423jobs that happen to fall late in the queue directory.
5424.ip MaxRecipientsPerMessage=\fIN\fP
5425[no short name]
5426The maximum number of recipients that will be accepted per message
5427in an SMTP transaction.
5428Note: setting this too low can interfere with sending mail from
5429MUAs that use SMTP for initial submission.
5430If not set, there is no limit on the number of recipients per envelope.
5431.ip MeToo
5432[m]
5433Send to me too,
5434even if I am in an alias expansion.
5435.ip MinFreeBlocks=\fIN\fP
5436[b]
5437Insist on at least
5438.i N
5439blocks free on the filesystem that holds the queue files
5440before accepting email via SMTP.
5441If there is insufficient space
5442.i sendmail
5443gives a 452 response
5444to the MAIL command.
5445This invites the sender to try again later.
5446.ip MinQueueAge=\fPage\fP
5447[no short name]
5448Don't process any queued jobs
5449that have been in the queue less than the indicated time interval.
5450This is intended to allow you to get responsiveness
5451by processing the queue fairly frequently
5452without thrashing your system by trying jobs too often.
5453The default units are minutes.
5454.ip MustQuoteChars=\fIs\fP
5455[no short name]
5456Sets the list of characters that must be quoted if used in a full name
5457that is in the phrase part of a ``phrase <address>'' syntax.
5458The default is ``\'.''.
5459The characters ``@,;:\e()[]'' are always added to this list.
5460.ip NoRecipientAction
5461[no short name]
5462The action to take when you receive a message that has no valid
5463recipient headers (To:, Cc:, Bcc:, or Apparently-To: \(em
5464the last included for back compatibility with old
5465.i sendmail s).
5466It can be
5467.b None
5468to pass the message on unmodified,
5469which violates the protocol,
5470.b Add-To
5471to add a To: header with any recipients it can find in the envelope
5472(which might expose Bcc: recipients),
5473.b Add-Apparently-To
5474to add an Apparently-To: header
5475(this is only for back-compatibility
5476and is officially deprecated),
5477.b Add-To-Undisclosed
5478to add a header
5479.q "To: undisclosed-recipients:;"
5480to make the header legal without disclosing anything,
5481or
5482.b Add-Bcc
5483to add an empty Bcc: header.
5484.ip OldStyleHeaders
5485[o]
5486Assume that the headers may be in old format,
5487i.e.,
5488spaces delimit names.
5489This actually turns on
5490an adaptive algorithm:
5491if any recipient address contains a comma, parenthesis,
5492or angle bracket,
5493it will be assumed that commas already exist.
5494If this flag is not on,
5495only commas delimit names.
5496Headers are always output with commas between the names.
5497Defaults to off.
5498.ip OperatorChars=\fIcharlist\fP
5499[$o macro]
5500The list of characters that are considered to be
5501.q operators ,
5502that is, characters that delimit tokens.
5503All operator characters are tokens by themselves;
5504sequences of non-operator characters are also tokens.
5505White space characters separate tokens
5506but are not tokens themselves \(em for example,
5507.q AAA.BBB
5508has three tokens, but
5509.q "AAA BBB"
5510has two.
5511If not set, OperatorChars defaults to
5512.q \&.\|:\|@\|[\|] ;
5513additionally, the characters
5514.q (\|)\|<\|>\|,\|;
5515are always operators.
5516.ip PostmasterCopy=\fIpostmaster\fP
5517[P]
5518If set,
5519copies of error messages will be sent to the named
5520.i postmaster .
5521Only the header of the failed message is sent.
5522Since most errors are user problems,
5523this is probably not a good idea on large sites,
5524and arguably contains all sorts of privacy violations,
5525but it seems to be popular with certain operating systems vendors.
5526Defaults to no postmaster copies.
5527.ip PrivacyOptions=\fI\|opt,opt,...\fP
5528[p]
5529Set the privacy
5530.i opt ions.
5531``Privacy'' is really a misnomer;
5532many of these are just a way of insisting on stricter adherence
5533to the SMTP protocol.
5534The
5535.i opt ions
5536can be selected from:
5537.(b
5538.ta \w'needvrfyhelo'u+3n
5539public Allow open access
5540needmailhelo Insist on HELO or EHLO command before MAIL
5541needexpnhelo Insist on HELO or EHLO command before EXPN
5542noexpn Disallow EXPN entirely
5543needvrfyhelo Insist on HELO or EHLO command before VRFY
5544novrfy Disallow VRFY entirely
5545noetrn Disallow ETRN entirely
5546noverb Disallow VERB entirely
5547restrictmailq Restrict mailq command
5548restrictqrun Restrict \-q command line flag
5549noreceipts Don't return success DSNs\**
5550goaway Disallow essentially all SMTP status queries
5551authwarnings Put X-Authentication-Warning: headers in messages
5552.)b
5553.(f
5554\**N.B.:
5555the
5556.b noreceipts
5557flag causes
5558.i sendmail
5559to violate RFC 1891,
5560which requires that return receipts be provided
5561if Delivery Status Notifications are supported.
5562.)f
5563The
5564.q goaway
5565pseudo-flag sets all flags except
5566.q restrictmailq
5567and
5568.q restrictqrun .
5569If mailq is restricted,
5570only people in the same group as the queue directory
5571can print the queue.
5572If queue runs are restricted,
5573only root and the owner of the queue directory
5574can run the queue.
5575Authentication Warnings add warnings about various conditions
5576that may indicate attempts to spoof the mail system,
5577such as using an non-standard queue directory.
5578.ip QueueDirectory=\fIdir\fP
5579[Q]
5580Use the named
5581.i dir
5582as the queue directory.
5583.ip QueueFactor=\fIfactor\fP
5584[q]
5585Use
5586.i factor
5587as the multiplier in the map function
5588to decide when to just queue up jobs rather than run them.
5589This value is divided by the difference between the current load average
5590and the load average limit
5591(\c
5592.b QueueLA
5593option)
5594to determine the maximum message priority
5595that will be sent.
5596Defaults to 600000.
5597.ip QueueLA=\fILA\fP
5598[x]
5599When the system load average exceeds
5600.i LA ,
5601just queue messages
5602(i.e., don't try to send them).
5603Defaults to 8.
5604.ip QueueSortOrder=\fIalgorithm\fP
5605[no short name]
5606Sets the
5607.i algorithm
5608used for sorting the queue.
5609Only the first character of the value is used.
5610Legal values are
5611.q host
5612(to order by the name of the first host name of the first recipient),
5613.q time
5614(to order by the submission time),
5615and
5616.q priority
5617(to order by message priority).
5618Host ordering makes better use of the connection cache,
5619but may tend to process low priority messages
5620that go to a single host
5621over high priority messages that go to several hosts;
5622it probably shouldn't be used on slow network links.
5623Time ordering is almost always a bad idea,
5624since it allows large, bulk mail to go out
5625before smaller, personal mail,
5626but may have applicability on some hosts with very fast connections.
5627Priority ordering is the default.
5628.ip QueueTimeout=\fItimeout\fP
5629[T]
5630A synonym for
5631.q Timeout.queuereturn .
5632Use that form instead of the
5633.q QueueTimeout
5634form.
5635.ip ResolverOptions=\fIoptions\fP
5636[I]
5637Set resolver options.
5638Values can be set using
5639.b + \c
5640.i flag
5641and cleared using
5642.b \- \c
5643.i flag ;
5644the
5645.i flag s
5646can be
5647.q debug ,
5648.q aaonly ,
5649.q usevc ,
5650.q primary ,
5651.q igntc ,
5652.q recurse ,
5653.q defnames ,
5654.q stayopen ,
5655or
5656.q dnsrch .
5657The string
5658.q HasWildcardMX
5659(without a
5660.b +
5661or
5662.b \- )
5663can be specified to turn off matching against MX records
5664when doing name canonifications.
5665.b N.B.
5666Prior to 8.7,
5667this option indicated that the name server be responding
5668in order to accept addresses.
5669This has been replaced by checking to see
5670if the
5671.q dns
5672method is listed in the service switch entry for the
5673.q hosts
5674service.
5675.ip RunAsUser=\fIuser\fP
5676[no short name]
5677The
5678.i user
5679parameter may be a user name
5680(looked up in
5681.i /etc/passwd )
5682or a numeric user id;
5683either form can have
5684.q ":group"
5685attached
5686(where group can be numeric or symbolic).
5687If set to a non-zero (non-root) value,
5688.i sendmail
5689will change to this user id shortly after startup\**.
5690.(f
5691\**When running as a daemon,
5692it changes to this user after accepting a connection
5693but before reading any
5694.sm SMTP
5695commands.
5696.)f
5697This avoids a certain class of security problems.
5698However, this means that all
5699.q \&.forward
5700and
5701.q :include:
5702files must be readable by the indicated
5703.i user ,
5704and on systems that don't support the saved uid bit properly,
5705all files to be written must be writable by
5706.i user
5707and all programs will be executed by
5708.i user .
5709It is also incompatible with the
5710.b SafeFileEnvironment
5711option.
5712In other words, it may not actually add much to security on an average system,
5713and may in fact detract from security
5714(because other file permissions must be loosened).
5715However, it should be useful on firewalls and other
5716places where users don't have accounts and the aliases file is
5717well constrained.
5718.ip RecipientFactor=\fIfact\fP
5719[y]
5720The indicated
5721.i fact or
5722is added to the priority (thus
5723.i lowering
5724the priority of the job)
5725for each recipient,
5726i.e., this value penalizes jobs with large numbers of recipients.
5727Defaults to 30000.
5728.ip RefuseLA=\fILA\fP
5729[X]
5730When the system load average exceeds
5731.i LA ,
5732refuse incoming SMTP connections.
5733Defaults to 12.
5734.ip RetryFactor=\fIfact\fP
5735[Z]
5736The
5737.i fact or
5738is added to the priority
5739every time a job is processed.
5740Thus,
5741each time a job is processed,
5742its priority will be decreased by the indicated value.
5743In most environments this should be positive,
5744since hosts that are down are all too often down for a long time.
5745Defaults to 90000.
5746.ip SafeFileEnvironment=\fIdir\fP
5747[no short name]
5748If this option is set,
5749.i sendmail
5750will do a
5751.i chroot (2)
5752call into the indicated
5753.i dir ectory
5754before doing any file writes.
5755If the file name specified by the user begins with
5756.i dir ,
5757that partial path name will be stripped off before writing,
5758so (for example)
5759if the SafeFileEnvironment variable is set to
5760.q /safe
5761then aliases of
5762.q /safe/logs/file
5763and
5764.q /logs/file
5765actually indicate the same file.
5766Additionally, if this option is set,
5767.i sendmail
5768refuses to deliver to symbolic links.
5769.ip SaveFromLine
5770[f]
5771Save
5772Unix-style
5773.q From
5774lines at the front of headers.
5775Normally they are assumed redundant
5776and discarded.
5777.ip SendMIMEErrors
5778[j]
5779If set, send error messages in MIME format
5780(see RFC2045 and RFC1344 for details).
5781If disabled,
5782.i sendmail
5783will not return the DSN keyword in response to an EHLO
5784and will not do Delivery Status Notification processing as described in
5785RFC1891.
5786.ip ServiceSwitchFile=\fIfilename\fP
5787[no short name]
5788If your host operating system has a service switch abstraction
5789(e.g., /etc/nsswitch.conf on Solaris
5790or /etc/svc.conf on Ultrix and DEC OSF/1)
5791that service will be consulted and this option is ignored.
5792Otherwise, this is the name of a file
5793that provides the list of methods used to implement particular services.
5794The syntax is a series of lines,
5795each of which is a sequence of words.
5796The first word is the service name,
5797and following words are service types.
5798The services that
5799.i sendmail
5800consults directly are
5801.q aliases
5802and
5803.q hosts.
5804Service types can be
5805.q dns ,
5806.q nis ,
5807.q nisplus ,
5808or
5809.q files
5810(with the caveat that the appropriate support
5811must be compiled in
5812before the service can be referenced).
5813If ServiceSwitchFile is not specified, it defaults to /etc/service.switch.
5814If that file does not exist, the default switch is:
5815.(b
5816aliases files
5817hosts dns nis files
5818.)b
5819The default file is
5820.q /etc/service.switch .
5821.ip SevenBitInput
5822[7]
5823Strip input to seven bits for compatibility with old systems.
5824This shouldn't be necessary.
5825.ip SingleLineFromHeader
5826[no short name]
5827If set, From: lines that have embedded newlines are unwrapped
5828onto one line.
5829This is to get around a botch in Lotus Notes
5830that apparently cannot understand legally wrapped RFC822 headers.
5831.ip SingleThreadDelivery
5832[no short name]
5833If set, a client machine will never try to open two SMTP connections
5834to a single server machine at the same time,
5835even in different processes.
5836That is, if another
5837.i sendmail
5838is already talking to some host a new
5839.i sendmail
5840will not open another connection.
5841This property is of mixed value;
5842although this reduces the load on the other machine,
5843it can cause mail to be delayed
5844(for example, if one
5845.i sendmail
5846is delivering a huge message, other
5847.i sendmail s
5848won't be able to send even small messages).
5849Also, it requires another file descriptor
5850(for the lock file)
5851per connection, so you may have to reduce the
5852.b ConnectionCacheSize
5853option to avoid running out of per-process file descriptors.
5854Requires the
5855.b HostStatusDirectory
5856option.
5857.ip SmtpGreetingMessage=\fImessage\fP
5858[$e macro]
5859The message printed when the SMTP server starts up.
5860Defaults to
5861.q "$j Sendmail $v ready at $b".
5862.ip StatusFile=\fIfile\fP
5863[S]
5864Log summary statistics in the named
5865.i file .
5866If not set,
5867no summary statistics are saved.
5868This file does not grow in size.
5869It can be printed using the
5870.i mailstats (8)
5871program.
5872.ip SuperSafe
5873[s]
5874Be super-safe when running things,
5875i.e.,
5876always instantiate the queue file,
5877even if you are going to attempt immediate delivery.
5878.i Sendmail
5879always instantiates the queue file
5880before returning control to the client
5881under any circumstances.
5882This should really
5883.i always
5884be set.
5885.ip TempFileMode=\fImode\fP
5886[F]
5887The file mode for queue files.
5888It is interpreted in octal by default.
5889Defaults to 0600.
5890.ip Timeout.\fItype\fP=\|\fItimeout\fP
5891[r; subsumes old T option as well]
5892Set timeout values.
5893The actual timeout is indicated by the
5894.i type .
5895The recognized timeouts and their default values, and their
5896minimum values specified in RFC 1123 section 5.3.2 are:
5897.(b
5898.ta \w'datafinal'u+3n
5899initial wait for initial greeting message [5m, 5m]
5900helo reply to HELO or EHLO command [5m, none]
5901mail reply to MAIL command [10m, 5m]
5902rcpt reply to RCPT command [1h, 5m]
5903datainit reply to DATA command [5m, 2m]
5904datablock data block read [1h, 3m]
5905datafinal reply to final ``.'' in data [1h, 10m]
5906rset reply to RSET command [5m, none]
5907quit reply to QUIT command [2m, none]
5908misc reply to NOOP and VERB commands [2m, none]
5909ident IDENT protocol timeout [30s, none]
5910fileopen\(dg timeout on opening .forward and :include: files [60s, none]
5911command\(dg command read [1h, 5m]
5912queuereturn\(dg how long until a message is returned [5d, 5d]
5913queuewarn\(dg how long until a warning is sent [none, none]
5914hoststatus\(dg how long until host status is ``stale'' [30m, none]
5915.)b
5916All but those marked with a dagger (\(dg)
5917apply to client SMTP.
5918If the message is submitted using the
5919.sm NOTIFY
5920.sm SMTP
5921extension,
5922warning messages will only be sent if
5923.sm NOTIFY=DELAY
5924is specified.
5925The queuereturn and queuewarn timeouts
5926can be further qualified with a tag based on the Precedence: field
5927in the message;
5928they must be one of
5929.q urgent
5930(indicating a positive non-zero precedence)
5931.q normal
5932(indicating a zero precedence), or
5933.q non-urgent
5934(indicating negative precedences).
5935For example, setting
5936.q Timeout.queuewarn.urgent=1h
5937sets the warning timeout for urgent messages only
5938to one hour.
5939The default if no precedence is indicated
5940is to set the timeout for all precedences.
5941.ip TimeZoneSpec=\fItzinfo\fP
5942[t]
5943Set the local time zone info to
5944.i tzinfo
5945\*- for example,
5946.q PST8PDT .
5947Actually, if this is not set,
5948the TZ environment variable is cleared (so the system default is used);
5949if set but null, the user's TZ variable is used,
5950and if set and non-null the TZ variable is set to this value.
5951.ip TryNullMXList
5952[w]
5953If this system is the
5954.q best
5955(that is, lowest preference)
5956MX for a given host,
5957its configuration rules should normally detect this situation
5958and treat that condition specially
5959by forwarding the mail to a UUCP feed,
5960treating it as local,
5961or whatever.
5962However, in some cases (such as Internet firewalls)
5963you may want to try to connect directly to that host
5964as though it had no MX records at all.
5965Setting this option causes
5966.i sendmail
5967to try this.
5968The downside is that errors in your configuration
5969are likely to be diagnosed as
5970.q "host unknown"
5971or
5972.q "message timed out"
5973instead of something more meaningful.
5974This option is disrecommended.
5975.ip UnixFromLine=\fIfromline\fP
5976[$l macro]
5977Defines the format used when
5978.i sendmail
5979must add a UNIX-style From_ line
5980(that is, a line beginning
5981.q From<space>user ).
5982Defaults to
5983.q "From $g $d" .
5984Don't change this unless your system uses a different UNIX mailbox format
5985(very unlikely).
5986.ip UnsafeGroupWrites
5987[no short name]
5988If set,
5989:include: and .forward files that are group writable are considered
5990.q unsafe ,
5991that is,
5992they cannot reference programs or write directly to files.
5993World writable :include: and .forward files
5994are always unsafe..
5995.ip UseErrorsTo
5996[l]
5997If there is an
5998.q Errors-To:
5999header, send error messages to the addresses listed there.
6000They normally go to the envelope sender.
6001Use of this option causes
6002.i sendmail
6003to violate RFC 1123.
6004This option is disrecommended and deprecated.
6005.ip UserDatabaseSpec=\fIudbspec\fP
6006[U]
6007The user database specification.
6008.ip UserSubmission
6009[no short name]
6010This is an initial submission directly from a Mail User Agent.
6011This can be set in the configuration file if you have
6012MUAs that don't pass the
6013.b \-U
6014flag or use the
6015XUSR
6016ESMTP extension,
6017but some relayed mail may get inappropriately rewritten if you do.
6018.ip Verbose
6019[v]
6020Run in verbose mode.
6021If this is set,
6022.i sendmail
6023adjusts options
6024.b HoldExpensive
6025(old
6026.b c )
6027and
6028.b DeliveryMode
6029(old
6030.b d )
6031so that all mail is delivered completely
6032in a single job
6033so that you can see the entire delivery process.
6034Option
6035.b Verbose
6036should
6037.i never
6038be set in the configuration file;
6039it is intended for command line use only.
6040.lp
6041All options can be specified on the command line using the
6042\-O or \-o flag,
6043but most will cause
6044.i sendmail
6045to relinquish its setuid permissions.
6046The options that will not cause this are
6047MinFreeBlocks [b],
6048DeliveryMode [d],
6049ErrorMode [e],
6050IgnoreDots [i],
6051LogLevel [L],
6052MeToo [m],
6053OldStyleHeaders [o],
6054PrivacyOptions [p],
6055Timeouts [r],
6056SuperSafe [s],
6057Verbose [v],
6058CheckpointInterval [C],
6059and
6060SevenBitInput [7].
6061Also, M (define macro) when defining the r or s macros
6062is also considered
6063.q safe .
6064.sh 2 "P \*- Precedence Definitions"
6065.pp
6066Values for the
6067.q "Precedence:"
6068field may be defined using the
6069.b P
6070control line.
6071The syntax of this field is:
6072.(b
6073\fBP\fP\fIname\fP\fB=\fP\fInum\fP
6074.)b
6075When the
6076.i name
6077is found in a
6078.q Precedence:
6079field,
6080the message class is set to
6081.i num .
6082Higher numbers mean higher precedence.
6083Numbers less than zero
6084have the special property
6085that if an error occurs during processing
6086the body of the message will not be returned;
6087this is expected to be used for
6088.q "bulk"
6089mail such as through mailing lists.
6090The default precedence is zero.
6091For example,
6092our list of precedences is:
6093.(b
6094Pfirst-class=0
6095Pspecial-delivery=100
6096Plist=\-30
6097Pbulk=\-60
6098Pjunk=\-100
6099.)b
6100People writing mailing list exploders
6101are encouraged to use
6102.q "Precedence: list" .
6103Older versions of
6104.i sendmail
6105(which discarded all error returns for negative precedences)
6106didn't recognize this name, giving it a default precedence of zero.
6107This allows list maintainers to see error returns
6108on both old and new versions of
6109.i sendmail .
6110.sh 2 "V \*- Configuration Version Level"
6111.pp
6112To provide compatibility with old configuration files,
6113the
6114.b V
6115line has been added to define some very basic semantics
6116of the configuration file.
6117These are not intended to be long term supports;
6118rather, they describe compatibility features
6119which will probably be removed in future releases.
6120.pp
6121.b N.B.:
6122these version
6123.i levels
6124have nothing
6125to do with the version
6126.i number
6127on the files.
6128For example,
6129as of this writing
6130version 8 config files
6131(specifically, 8.9)
6132used version level 8 configurations.
6133.pp
6134.q Old
6135configuration files are defined as version level one.
6136Version level two files make the following changes:
6137.np
6138Host name canonification ($[ ... $])
6139appends a dot if the name is recognized;
6140this gives the config file a way of finding out if anything matched.
6141(Actually, this just initializes the
6142.q host
6143map with the
6144.q \-a.
6145flag \*- you can reset it to anything you prefer
6146by declaring the map explicitly.)
6147.np
6148Default host name extension is consistent throughout processing;
6149version level one configurations turned off domain extension
6150(that is, adding the local domain name)
6151during certain points in processing.
6152Version level two configurations are expected to include a trailing dot
6153to indicate that the name is already canonical.
6154.np
6155Local names that are not aliases
6156are passed through a new distinguished ruleset five;
6157this can be used to append a local relay.
6158This behaviour can be prevented by resolving the local name
6159with an initial `@'.
6160That is, something that resolves to a local mailer and a user name of
6161.q vikki
6162will be passed through ruleset five,
6163but a user name of
6164.q @vikki
6165will have the `@' stripped,
6166will not be passed through ruleset five,
6167but will otherwise be treated the same as the prior example.
6168The expectation is that this might be used to implement a policy
6169where mail sent to
6170.q vikki
6171was handled by a central hub,
6172but mail sent to
6173.q vikki@localhost
6174was delivered directly.
6175.pp
6176Version level three files
6177allow # initiated comments on all lines.
6178Exceptions are backslash escaped # marks
6179and the $# syntax.
6180.pp
6181Version level four configurations
6182are completely equivalent to level three
6183for historical reasons.
6184.pp
6185Version level five configuration files
6186change the default definition of
6187.b $w
6188to be just the first component of the hostname.
6189.pp
6190Version level six configuration files
6191change many of the local processing options
6192(such as aliasing and matching the beginning of the address for
6193`|' characters)
6194to be mailer flags;
6195this allows fine-grained control over the special local processing.
6196Level six configuration files may also use long option names.
6197The
6198.b ColonOkInAddr
6199option (to allow colons in the local-part of addresses)
6200defaults
6201.b on
6202for lower numbered configuration files;
6203the configuration file requires some additional intelligence
6204to properly handle the RFC 822 group construct.
6205.pp
6206Version level seven configuration files
6207used new option names to replace old macros
6208(\c
6209.b $e
6210became
6211.b SmtpGreeetingMessage ,
6212.b $l
6213became
6214.b UnixFromLine ,
6215and
6216.b $o
6217became
6218.b OperatorChars .
6219Also, prior to version seven,
6220the
6221.b F=q
6222flag (use 250 instead of 252 return value for
6223.sm "SMTP VRFY"
6224commands)
6225was assumed.
6226.pp
6227Version level eight configuration files allow
6228.b $#
6229on the left hand side of ruleset lines.
6230.pp
6231The
6232.b V
6233line may have an optional
6234.b / \c
6235.i vendor
6236to indicate that this configuration file uses modifications
6237specific to a particular vendor\**.
6238.(f
6239\**And of course, vendors are encouraged to add themselves
6240to the list of recognized vendors by editing the routine
6241.i setvendor
6242in
6243.i conf.c .
6244Please send e-mail to sendmail@Sendmail.ORG
6245to register your vendor dialect.
6246.)f
6247You may use
6248.q /Berkeley
6249to emphasize that this configuration file
6250uses the Berkeley dialect of
6251.i sendmail .
6252.sh 2 "K \*- Key File Declaration"
6253.pp
6254Special maps can be defined using the line:
6255.(b
6256Kmapname mapclass arguments
6257.)b
6258The
6259.i mapname
6260is the handle by which this map is referenced in the rewriting rules.
6261The
6262.i mapclass
6263is the name of a type of map;
6264these are compiled in to
6265.i sendmail .
6266The
6267.i arguments
6268are interpreted depending on the class;
6269typically,
6270there would be a single argument naming the file containing the map.
6271.pp
6272Maps are referenced using the syntax:
6273.(b
6274$( \fImap\fP \fIkey\fP $@ \fIarguments\fP $: \fIdefault\fP $)
6275.)b
6276where either or both of the
6277.i arguments
6278or
6279.i default
6280portion may be omitted.
6281The
6282.i "$@ arguments"
6283may appear more than once.
6284The indicated
6285.i key
6286and
6287.i arguments
6288are passed to the appropriate mapping function.
6289If it returns a value, it replaces the input.
6290If it does not return a value and the
6291.i default
6292is specified, the
6293.i default
6294replaces the input.
6295Otherwise, the input is unchanged.
6296.pp
6297The
6298.i arguments
6299are passed to the map for arbitrary use.
6300Most map classes can interpolate these arguments
6301into their values using the syntax
6302.q %\fIn\fP
6303(where
6304.i n
6305is a digit)
6306to indicate the corresponding
6307.i argument .
6308Argument
6309.q %0
6310indicates the database key.
6311For example, the rule
6312.(b
6313.ta 1.5i
6314R$\- ! $+ $: $(uucp $1 $@ $2 $: %1 @ %0 . UUCP $)
6315.)b
6316Looks up the UUCP name in a (user defined) UUCP map;
6317if not found it turns it into
6318.q \&.UUCP
6319form.
6320The database might contain records like:
6321.(b
6322decvax %1@%0.DEC.COM
6323research %1@%0.ATT.COM
6324.)b
6325Note that
6326.i default
6327clauses never do this mapping.
6328.pp
6329The built in map with both name and class
6330.q host
6331is the host name canonicalization lookup.
6332Thus,
6333the syntax:
6334.(b
6335$(host \fIhostname\fP$)
6336.)b
6337is equivalent to:
6338.(b
6339$[\fIhostname\fP$]
6340.)b
6341.pp
6342There are many defined classes.
6343.ip dbm
6344Database lookups using the ndbm(3) library.
6345.i Sendmail
6346must be compiled with
6347.b NDBM
6348defined.
6349.ip btree
6350Database lookups using the btree interface to the Berkeley DB
6351library.
6352.i Sendmail
6353must be compiled with
6354.b NEWDB
6355defined.
6356.ip hash
6357Database lookups using the hash interface to the Berkeley DB
6358library.
6359.i Sendmail
6360must be compiled with
6361.b NEWDB
6362defined.
6363.ip nis
6364NIS lookups.
6365.i Sendmail
6366must be compiled with
6367.b NIS
6368defined.
6369.ip nisplus
6370NIS+ lookups.
6371.i Sendmail
6372must be compiled with
6373.b NISPLUS
6374defined.
6375The argument is the name of the table to use for lookups,
6376and the
6377.b \-k
6378and
6379.b \-v
6380flags may be used to set the key and value columns respectively.
6381.ip hesiod
6382Hesiod lookups.
6383.i Sendmail
6384must be compiled with
6385.b HESIOD
6386defined.
6387.ip ldapx
6388LDAP X500 directory lookups.
6389.i Sendmail
6390must be compiled with
6391.b LDAPMAP
6392defined.
6393The map supports most of the standard arguments
6394and most of the command line arguments of the
6395.i ldapsearch
6396program.
6397.ip netinfo
6398NeXT NetInfo lookups.
6399.i Sendmail
6400must be compiled with
6401.b NETINFO
6402defined.
6403.ip text
6404Text file lookups.
6405The format of the text file is defined by the
6406.b \-k
6407(key field number),
6408.b \-v
6409(value field number),
6410and
6411.b \-z
6412(field delimiter)
6413flags.
6414.ip stab
6415Internal symbol table lookups.
6416Used internally for aliasing.
6417.ip implicit
6418Really should be called
6419.q alias
6420\(em this is used to get the default lookups
6421for alias files,
6422and is the default if no class is specified for alias files.
6423.ip user
6424Looks up users using
6425.i getpwnam (3).
6426The
6427.b \-v
6428flag can be used to specify the name of the field to return
6429(although this is normally used only to check the existence
6430of a user).
6431.ip host
6432Canonifies host domain names.
6433Given a host name it calls the name server
6434to find the canonical name for that host.
6435.ip bestmx
6436Returns the best MX record for a host name given as the key.
6437The current machine is always preferred \*-
6438that is, if the current machine is one of the hosts listed as a
6439lowest-preference MX record, then it will be guaranteed to be returned.
6440This can be used to find out if this machine is the target for an MX record,
6441and mail can be accepted on that basis.
6442If the
6443.b \-z
6444flag is given, then all MX names are returned,
6445separated by the given delimiter.
6446.ip sequence
6447The arguments on the `K' line are a list of maps;
6448the resulting map searches the argument maps in order
6449until it finds a match for the indicated key.
6450For example, if the key definition is:
6451.(b
6452Kmap1 ...
6453Kmap2 ...
6454Kseqmap sequence map1 map2
6455.)b
6456then a lookup against
6457.q seqmap
6458first does a lookup in map1.
6459If that is found, it returns immediately.
6460Otherwise, the same key is used for map2.
6461.ip switch
6462Much like the
6463.q sequence
6464map except that the order of maps is determined by the service switch.
6465The argument is the name of the service to be looked up;
6466the values from the service switch are appended to the map name
6467to create new map names.
6468For example, consider the key definition:
6469.(b
6470Kali switch aliases
6471.)b
6472together with the service switch entry:
6473.(b
6474aliases nis files
6475.)b
6476This causes a query against the map
6477.q ali
6478to search maps named
6479.q ali.nis
6480and
6481.q ali.files
6482in that order.
6483.ip dequote
6484Strip double quotes (") from a name.
6485It does not strip backslashes,
6486and will not strip quotes if the resulting string
6487would contain unscannable syntax
6488(that is, basic errors like unbalanced angle brackets;
6489more sophisticated errors such as unknown hosts are not checked).
6490The intent is for use when trying to accept mail from systems such as
6491DECnet
6492that routinely quote odd syntax such as
6493.(b
6494"49ers::ubell"
6495.)b
6496A typical usage is probably something like:
6497.(b
6498Kdequote dequote
6499
6500\&...
6501
6502R$\- $: $(dequote $1 $)
6503R$\- $+ $: $>3 $1 $2
6504.)b
6505Care must be taken to prevent unexpected results;
6506for example,
6507.(b
6508"|someprogram < input > output"
6509.)b
6510will have quotes stripped,
6511but the result is probably not what you had in mind.
6512Fortunately these cases are rare.
6513.ip regex
6514The map definition on the
6515.b K
6516line contains a regular expression.
6517Any key input is compared to that expression using the
6518POSIX regular expressions routines regcomp(), regerr(), and regexec().
6519Refer to the documentation for those routines for more information
6520about the regular expression matching.
6521No rewriting of the key is done if the
6522.b \-m
6523flag is used. Without it, the key is discarded or if
6524.b \-s
6525if used, it is substituted by the substring matches, delimited by
6526.b $|
6527or the string specified with the the
6528.b \-d
6529flag. The flags available for the map are
6530.(b
6531-n not
6532-f case sensitive
6533-b basic regular expressions
6534 (default is extended)
6535-s substring match
6536-d set the delimiter used for -s
6537-a append string to key
6538-m match only, do not
6539 replace/discard value
6540.)b
6541The
6542.b \-s
6543flag can include an optional parameter which can be used
6544to select the substrings in the result of the lookup. For example,
6545.(b
6546-s1,3,4
6547.)b
6548.ip program
6549The arguments on the
6550.b K
6551line are the pathname to a program and any initial parameters to be passed.
6552When the map is called,
6553the key is added to the initial parameters
6554and the program is invoked
6555as the default user/group id.
6556The first line of standard output is returned as the value of the lookup.
6557This has many potential security problems,
6558and has terrible performance;
6559it should be used only when absolutely necessary.
6560.pp
6561Most of these accept as arguments the same optional flags
6562and a filename
6563(or a mapname for NIS;
6564the filename is the root of the database path,
6565so that
6566.q .db
6567or some other extension appropriate for the database type
6568will be added to get the actual database name).
6569Known flags are:
6570.ip "\-o"
6571Indicates that this map is optional \*- that is,
6572if it cannot be opened,
6573no error is produced,
6574and
6575.i sendmail
6576will behave as if the map existed but was empty.
6577.ip "\-N, \-O"
6578If neither
6579.b \-N
6580or
6581.b \-O
6582are specified,
6583.i sendmail
6584uses an adaptive algorithm to decide whether or not to look for null bytes
6585on the end of keys.
6586It starts by trying both;
6587if it finds any key with a null byte it never tries again without a null byte
6588and vice versa.
6589If
6590.b \-N
6591is specified it never tries without a null byte and
6592if
6593.b \-O
6594is specified it never tries with a null byte.
6595Setting one of
6596these can speed matches but are never necessary.
6597If both
6598.b \-N
6599and
6600.b \-O
6601are specified,
6602.i sendmail
6603will never try any matches at all \(em
6604that is, everything will appear to fail.
6605.ip "\-a\fIx\fP"
6606Append the string
6607.i x
6608on successful matches.
6609For example, the default
6610.i host
6611map appends a dot on successful matches.
6612.ip "\-T\fIx\fP"
6613Append the string
6614.i x
6615on temporary failures.
6616For example,
6617.i x
6618would be appended if a DNS lookup returned
6619.q "server failed"
6620or an NIS lookup could not locate a server.
6621See also the
6622.b \-t
6623flag.
6624.ip "\-f"
6625Do not fold upper to lower case before looking up the key.
6626.ip "\-m"
6627Match only (without replacing the value).
6628If you only care about the existence of a key and not the value
6629(as you might when searching the NIS map
6630.q hosts.byname
6631for example),
6632this flag prevents the map from substituting the value.
6633However,
6634The \-a argument is still appended on a match,
6635and the default is still taken if the match fails.
6636.ip "\-k\fIkeycol\fP"
6637The key column name (for NIS+) or number
6638(for text lookups).
6639For LDAP maps this is a filter string
6640passed to printf with a %s where the string to be
6641.q "mapped"
6642is inserted.
6643.ip "\-v\fIvalcol\fP"
6644The value column name (for NIS+) or number
6645(for text lookups).
6646For LDAP maps this is the name of the
6647attribute to be returned.
6648.ip "\-z\fIdelim\fP"
6649The column delimiter (for text lookups).
6650It can be a single character or one of the special strings
6651.q \|\en
6652or
6653.q \|\et
6654to indicate newline or tab respectively.
6655If omitted entirely,
6656the column separator is any sequence of whitespace.
6657.ip "\-t"
6658Normally, when a map attempts to do a lookup
6659and the server fails
6660(e.g.,
6661.i sendmail
6662couldn't contact any name server;
6663this is
6664.i not
6665the same as an entry not being found in the map),
6666the message being processed is queued for future processing.
6667The
6668.b \-t
6669flag turns off this behaviour,
6670letting the temporary failure (server down)
6671act as though it were a permanent failure (entry not found).
6672It is particularly useful for DNS lookups,
6673where someone else's misconfigured name server can cause problems
6674on your machine.
6675However, care must be taken to ensure that you don't bounce mail
6676that would be resolved correctly if you tried again.
6677A common strategy is to forward such mail
6678to another, possibly better connected, mail server.
6679.ip "\-s\fIspacesub\fP
6680For the dequote map only,
6681the character to use to replace space characters
6682after a successful dequote.
6683.ip "\-q"
6684Don't dequote the key before lookup.
6685.ip "\-A"
6686When rebuilding an alias file,
6687the
6688.b \-A
6689flag causes duplicate entries in the text version
6690to be merged.
6691For example, two entries:
6692.(b
6693list: user1, user2
6694list: user3
6695.)b
6696would be treated as though it were the single entry
6697.(b
6698list: user1, user2, user3
6699.)b
6700in the presence of the
6701.b \-A
6702flag.
6703.pp
6704The
6705.i dbm
6706map appends the strings
6707.q \&.pag
6708and
6709.q \&.dir
6710to the given filename;
6711the
6712.i hash
6713and
6714.i btree
6715maps append
6716.q \&.db .
6717For example, the map specification
6718.(b
6719Kuucp dbm \-o \-N /usr/lib/uucpmap
6720.)b
6721specifies an optional map named
6722.q uucp
6723of class
6724.q dbm ;
6725it always has null bytes at the end of every string,
6726and the data is located in
6727/usr/lib/uucpmap.{dir,pag}.
6728.pp
6729The program
6730.i makemap (8)
6731can be used to build any of the three database-oriented maps.
6732It takes the following flags:
6733.ip \-f
6734Do not fold upper to lower case in the map.
6735.ip \-N
6736Include null bytes in keys.
6737.ip \-o
6738Append to an existing (old) file.
6739.ip \-r
6740Allow replacement of existing keys;
6741normally, re-inserting an existing key is an error.
6742.ip \-v
6743Print what is happening.
6744.lp
6745The
6746.i sendmail
6747daemon does not have to be restarted to read the new maps
6748as long as you change them in place;
6749file locking is used so that the maps won't be read
6750while they are being updated.\**
6751.(f
6752\**That is, don't create new maps and then use
6753.i mv (1)
6754to move them into place.
6755Since the maps are already open
6756the new maps will never be seen.
6757.)f
6758.pp
6759New classes can be added in the routine
6760.b setupmaps
6761in file
6762.b conf.c .
6763.sh 2 "The User Database"
6764.pp
6765If you have a version of
6766.i sendmail
6767with the user database package
6768compiled in,
6769the handling of sender and recipient addresses
6770is modified.
6771.pp
6772The location of this database is controlled with the
6773.b UserDatabaseSpec
6774option.
6775.sh 3 "Structure of the user database"
6776.pp
6777The database is a sorted (BTree-based) structure.
6778User records are stored with the key:
6779.(b
6780\fIuser-name\fP\fB:\fP\fIfield-name\fP
6781.)b
6782The sorted database format ensures that user records are clustered together.
6783Meta-information is always stored with a leading colon.
6784.pp
6785Field names define both the syntax and semantics of the value.
6786Defined fields include:
6787.nr ii 1i
6788.ip maildrop
6789The delivery address for this user.
6790There may be multiple values of this record.
6791In particular,
6792mailing lists will have one
6793.i maildrop
6794record for each user on the list.
6795.ip "mailname"
6796The outgoing mailname for this user.
6797For each outgoing name,
6798there should be an appropriate
6799.i maildrop
6800record for that name to allow return mail.
6801See also
6802.i :default:mailname .
6803.ip mailsender
6804Changes any mail sent to this address to have the indicated envelope sender.
6805This is intended for mailing lists,
6806and will normally be the name of an appropriate -request address.
6807It is very similar to the owner-\c
6808.i list
6809syntax in the alias file.
6810.ip fullname
6811The full name of the user.
6812.ip office-address
6813The office address for this user.
6814.ip office-phone
6815The office phone number for this user.
6816.ip office-fax
6817The office FAX number for this user.
6818.ip home-address
6819The home address for this user.
6820.ip home-phone
6821The home phone number for this user.
6822.ip home-fax
6823The home FAX number for this user.
6824.ip project
6825A (short) description of the project this person is affiliated with.
6826In the University this is often just the name of their graduate advisor.
6827.ip plan
6828A pointer to a file from which plan information can be gathered.
6829.pp
6830As of this writing,
6831only a few of these fields are actually being used by
6832.i sendmail :
6833.i maildrop
6834and
6835.i mailname .
6836A
6837.i finger
6838program that uses the other fields is planned.
6839.sh 3 "User database semantics"
6840.pp
6841When the rewriting rules submit an address to the local mailer,
6842the user name is passed through the alias file.
6843If no alias is found (or if the alias points back to the same address),
6844the name (with
6845.q :maildrop
6846appended)
6847is then used as a key in the user database.
6848If no match occurs (or if the maildrop points at the same address),
6849forwarding is tried.
6850.pp
6851If the first token of the user name returned by ruleset 0
6852is an
6853.q @
6854sign, the user database lookup is skipped.
6855The intent is that the user database will act as a set of defaults
6856for a cluster (in our case, the Computer Science Division);
6857mail sent to a specific machine should ignore these defaults.
6858.pp
6859When mail is sent,
6860the name of the sending user is looked up in the database.
6861If that user has a
6862.q mailname
6863record,
6864the value of that record is used as their outgoing name.
6865For example, I might have a record:
6866.(b
6867eric:mailname Eric.Allman@CS.Berkeley.EDU
6868.)b
6869This would cause my outgoing mail to be sent as Eric.Allman.
6870.pp
6871If a
6872.q maildrop
6873is found for the user,
6874but no corresponding
6875.q mailname
6876record exists,
6877the record
6878.q :default:mailname
6879is consulted.
6880If present, this is the name of a host to override the local host.
6881For example, in our case we would set it to
6882.q CS.Berkeley.EDU .
6883The effect is that anyone known in the database
6884gets their outgoing mail stamped as
6885.q user@CS.Berkeley.EDU ,
6886but people not listed in the database use the local hostname.
6887.sh 3 "Creating the database\**"
6888.(f
6889\**These instructions are known to be incomplete.
6890A future version of the user database is planned
6891including things such as finger service \*- and good documentation.
6892.)f
6893.pp
6894The user database is built from a text file
6895using the
6896.i makemap
6897utility
6898(in the distribution in the makemap subdirectory).
6899The text file is a series of lines corresponding to userdb records;
6900each line has a key and a value separated by white space.
6901The key is always in the format described above \*-
6902for example:
6903.(b
6904eric:maildrop
6905.)b
6906This file is normally installed in a system directory;
6907for example, it might be called
6908.i /etc/userdb .
6909To make the database version of the map, run the program:
6910.(b
6911makemap btree /etc/userdb.db < /etc/userdb
6912.)b
6913Then create a config file that uses this.
6914For example, using the V8 M4 configuration, include the
6915following line in your .mc file:
6916.(b
6917define(\`confUSERDB_SPEC\', /etc/userdb.db)
6918.)b
6919.sh 1 "OTHER CONFIGURATION"
6920.pp
6921There are some configuration changes that can be made by
6922recompiling
6923.i sendmail .
6924This section describes what changes can be made
6925and what has to be modified to make them.
6926In most cases this should be unnecessary
6927unless you are porting
6928.i sendmail
6929to a new environment.
6930.sh 2 "Parameters in BuildTools/OS/$oscf"
6931.pp
6932These parameters are intended to describe the compilation environment,
6933not site policy,
6934and should normally be defined in the operating system
6935configuration file.
6936.b "This section needs a complete rewrite."
6937.ip NDBM
6938If set,
6939the new version of the DBM library
6940that allows multiple databases will be used.
6941If neither NDBM nor NEWDB are set,
6942a much less efficient method of alias lookup is used.
6943.ip NEWDB
6944If set, use the new database package from Berkeley (from 4.4BSD).
6945This package is substantially faster than DBM or NDBM.
6946If NEWDB and NDBM are both set,
6947.i sendmail
6948will read DBM files,
6949but will create and use NEWDB files.
6950.ip NIS
6951Include support for NIS.
6952If set together with
6953.i both
6954NEWDB and NDBM,
6955.i sendmail
6956will create both DBM and NEWDB files if and only if
6957an alias file includes the substring
6958.q /yp/
6959in the name.
6960This is intended for compatibility with Sun Microsystems'
6961.i mkalias
6962program used on YP masters.
6963.ip NISPLUS
6964Compile in support for NIS+.
6965.ip NETINFO
6966Compile in support for NetInfo (NeXT stations).
6967.ip LDAPMAP
6968Compile in support for LDAP X500 queries.
6969Requires libldap and liblber
6970from the Umich LDAP 3.2 or 3.3 release.
6971.ip HESIOD
6972Compile in support for Hesiod.
6973.ip _PATH_SENDMAILCF
6974The pathname of the sendmail.cf file.
6975.ip _PATH_SENDMAILPID
6976The pathname of the sendmail.pid file.
6977.pp
6978There are also several compilation flags to indicate the environment
6979such as
6980.q _AIX3
6981and
6982.q _SCO_unix_ .
6983See the src/README
6984file for the latest scoop on these flags.
6985.sh 2 "Parameters in src/conf.h"
6986.pp
6987Parameters and compilation options
6988are defined in conf.h.
6989Most of these need not normally be tweaked;
6990common parameters are all in sendmail.cf.
6991However, the sizes of certain primitive vectors, etc.,
6992are included in this file.
6993The numbers following the parameters
6994are their default value.
6995.pp
6996This document is not the best source of information
6997for compilation flags in conf.h \(em
6998see src/README or src/conf.h itself.
6999.nr ii 1.2i
7000.ip "MAXLINE [2048]"
7001The maximum line length of any input line.
7002If message lines exceed this length
7003they will still be processed correctly;
7004however, header lines,
7005configuration file lines,
7006alias lines,
7007etc.,
7008must fit within this limit.
7009.ip "MAXNAME [256]"
7010The maximum length of any name,
7011such as a host or a user name.
7012.ip "MAXPV [40]"
7013The maximum number of parameters to any mailer.
7014This limits the number of recipients that may be passed in one transaction.
7015It can be set to any arbitrary number above about 10,
7016since
7017.i sendmail
7018will break up a delivery into smaller batches as needed.
7019A higher number may reduce load on your system, however.
7020.ip "MAXATOM [100]"
7021The maximum number of atoms
7022(tokens)
7023in a single address.
7024For example,
7025the address
7026.q "eric@CS.Berkeley.EDU"
7027is seven atoms.
7028.ip "MAXMAILERS [25]"
7029The maximum number of mailers that may be defined
7030in the configuration file.
7031.ip "MAXRWSETS [200]"
7032The maximum number of rewriting sets
7033that may be defined.
7034The first half of these are reserved for numeric specification
7035(e.g., ``S92''),
7036while the upper half are reserved for auto-numbering
7037(e.g., ``Sfoo'').
7038Thus, with a value of 200 an attempt to use ``S99'' will succeed,
7039but ``S100'' will fail.
7040.ip "MAXPRIORITIES [25]"
7041The maximum number of values for the
7042.q Precedence:
7043field that may be defined
7044(using the
7045.b P
7046line in sendmail.cf).
7047.ip "MAXUSERENVIRON [100]"
7048The maximum number of items in the user environment
7049that will be passed to subordinate mailers.
7050.ip "MAXMXHOSTS [100]"
7051The maximum number of MX records we will accept for any single host.
7052.ip "MAXALIASDB [12]"
7053The maximum number of alias databases that can be open at any time.
7054Note that there may also be an open file limit.
7055.ip "MAXMAPSTACK [12]"
7056The maximum number of maps that may be "stacked" in a
7057.b sequence
7058class map.
7059.ip "MAXMIMEARGS [20]"
7060The maximum number of arguments in a MIME Content-Type: header;
7061additional arguments will be ignored.
7062.ip "MAXMIMENESTING [20]"
7063The maximum depth to which MIME messages may be nested
7064(that is, nested Message or Multipart documents;
7065this does not limit the number of components in a single Multipart document).
7066.lp
7067A number of other compilation options exist.
7068These specify whether or not specific code should be compiled in.
7069Ones marked with \(dg
7070are 0/1 valued.
7071.nr ii 1.2i
7072.ip NETINET\(dg
7073If set,
7074support for Internet protocol networking is compiled in.
7075Previous versions of
7076.i sendmail
7077referred to this as
7078.sm DAEMON ;
7079this old usage is now incorrect.
7080Defaults on;
7081turn it off in the Makefile
7082if your system doesn't support the Internet protocols.
7083.ip NETISO\(dg
7084If set,
7085support for ISO protocol networking is compiled in
7086(it may be appropriate to #define this in the Makefile instead of conf.h).
7087.ip LOG
7088If set,
7089the
7090.i syslog
7091routine in use at some sites is used.
7092This makes an informational log record
7093for each message processed,
7094and makes a higher priority log record
7095for internal system errors.
7096.b "STRONGLY RECOMMENDED"
7097\(em if you want no logging, turn it off in the configuration file.
7098.ip MATCHGECOS\(dg
7099Compile in the code to do ``fuzzy matching'' on the GECOS field
7100in /etc/passwd.
7101This also requires that the
7102.b MatchGECOS
7103option be turned on.
7104.ip NAMED_BIND\(dg
7105Compile in code to use the
7106Berkeley Internet Name Domain (BIND) server
7107to resolve TCP/IP host names.
7108.ip NOTUNIX
7109If you are using a non-UNIX mail format,
7110you can set this flag to turn off special processing
7111of UNIX-style
7112.q "From "
7113lines.
7114.ip QUEUE\(dg
7115This flag should be set to compile in the queueing code.
7116If this is not set,
7117mailers must accept the mail immediately
7118or it will be returned to the sender.
7119.ip SMTP\(dg
7120If set,
7121the code to handle user and server SMTP will be compiled in.
7122This is only necessary if your machine has some mailer
7123that speaks SMTP
7124(this means most machines everywhere).
7125.ip USERDB\(dg
7126Include the
7127.b experimental
7128Berkeley user information database package.
7129This adds a new level of local name expansion
7130between aliasing and forwarding.
7131It also uses the NEWDB package.
7132This may change in future releases.
7133.lp
7134The following options are normally turned on
7135in per-operating-system clauses in conf.h.
7136.ip IDENTPROTO\(dg
7137Compile in the IDENT protocol as defined in RFC 1413.
7138This defaults on for all systems except Ultrix,
7139which apparently has the interesting
7140.q feature
7141that when it receives a
7142.q "host unreachable"
7143message it closes all open connections to that host.
7144Since some firewall gateways send this error code
7145when you access an unauthorized port (such as 113, used by IDENT),
7146Ultrix cannot receive email from such hosts.
7147.ip SYSTEM5
7148Set all of the compilation parameters appropriate for System V.
7149.ip HASFLOCK\(dg
7150Use Berkeley-style
7151.b flock
7152instead of System V
7153.b lockf
7154to do file locking.
7155Due to the highly unusual semantics of locks
7156across forks in
7157.b lockf ,
7158this should always be used if at all possible.
7159.ip HASINITGROUPS
7160Set this if your system has the
7161.i initgroups()
7162call
7163(if you have multiple group support).
7164This is the default if SYSTEM5 is
7165.i not
7166defined or if you are on HPUX.
7167.ip HASUNAME
7168Set this if you have the
7169.i uname (2)
7170system call (or corresponding library routine).
7171Set by default if
7172SYSTEM5
7173is set.
7174.ip HASGETDTABLESIZE
7175Set this if you have the
7176.i getdtablesize (2)
7177system call.
7178.ip HASWAITPID
7179Set this if you have the
7180.i haswaitpid (2)
7181system call.
7182.ip SFS_TYPE
7183The mechanism that can be used to get file system capacity information.
7184The values can be one of
7185SFS_USTAT (use the ustat(2) syscall),
7186SFS_4ARGS (use the four argument statfs(2) syscall),
7187SFS_VFS (use the two argument statfs(2) syscall including <sys/vfs.h>),
7188SFS_MOUNT (use the two argument statfs(2) syscall including <sys/mount.h>),
7189SFS_STATFS (use the two argument statfs(2) syscall including <sys/statfs.h>),
7190SFS_STATVFS (use the two argument statfs(2) syscall including <sys/statvfs.h>),
7191or
7192SFS_NONE (no way to get this information).
7193.ip LA_TYPE
7194The load average type.
7195Details are described below.
7196.lp
7197The are several built-in ways of computing the load average.
7198.i Sendmail
7199tries to auto-configure them based on imperfect guesses;
7200you can select one using the
7201.i cc
7202option
7203.b \-DLA_TYPE= \c
7204.i type ,
7205where
7206.i type
7207is:
7208.ip LA_INT
7209The kernel stores the load average in the kernel as an array of long integers.
7210The actual values are scaled by a factor FSCALE
7211(default 256).
7212.ip LA_SHORT
7213The kernel stores the load average in the kernel as an array of short integers.
7214The actual values are scaled by a factor FSCALE
7215(default 256).
7216.ip LA_FLOAT
7217The kernel stores the load average in the kernel as an array of
7218double precision floats.
7219.ip LA_MACH
7220Use MACH-style load averages.
7221.ip LA_SUBR
7222Call the
7223.i getloadavg
7224routine to get the load average as an array of doubles.
7225.ip LA_ZERO
7226Always return zero as the load average.
7227This is the fallback case.
7228.lp
7229If type
7230.sm LA_INT ,
7231.sm LA_SHORT ,
7232or
7233.sm LA_FLOAT
7234is specified,
7235you may also need to specify
7236.sm _PATH_UNIX
7237(the path to your system binary)
7238and
7239.sm LA_AVENRUN
7240(the name of the variable containing the load average in the kernel;
7241usually
7242.q _avenrun
7243or
7244.q avenrun ).
7245.sh 2 "Configuration in src/conf.c"
7246.pp
7247The following changes can be made in conf.c.
7248.sh 3 "Built-in Header Semantics"
7249.pp
7250Not all header semantics are defined in the configuration file.
7251Header lines that should only be included by certain mailers
7252(as well as other more obscure semantics)
7253must be specified in the
7254.i HdrInfo
7255table in
7256.i conf.c .
7257This table contains the header name
7258(which should be in all lower case)
7259and a set of header control flags (described below),
7260The flags are:
7261.ip H_ACHECK
7262Normally when the check is made to see if a header line is compatible
7263with a mailer,
7264.i sendmail
7265will not delete an existing line.
7266If this flag is set,
7267.i sendmail
7268will delete
7269even existing header lines.
7270That is,
7271if this bit is set and the mailer does not have flag bits set
7272that intersect with the required mailer flags
7273in the header definition in
7274sendmail.cf,
7275the header line is
7276.i always
7277deleted.
7278.ip H_EOH
7279If this header field is set,
7280treat it like a blank line,
7281i.e.,
7282it will signal the end of the header
7283and the beginning of the message text.
7284.ip H_FORCE
7285Add this header entry
7286even if one existed in the message before.
7287If a header entry does not have this bit set,
7288.i sendmail
7289will not add another header line if a header line
7290of this name already existed.
7291This would normally be used to stamp the message
7292by everyone who handled it.
7293.ip H_TRACE
7294If set,
7295this is a timestamp
7296(trace)
7297field.
7298If the number of trace fields in a message
7299exceeds a preset amount
7300the message is returned
7301on the assumption that it has an aliasing loop.
7302.ip H_RCPT
7303If set,
7304this field contains recipient addresses.
7305This is used by the
7306.b \-t
7307flag to determine who to send to
7308when it is collecting recipients from the message.
7309.ip H_FROM
7310This flag indicates that this field
7311specifies a sender.
7312The order of these fields in the
7313.i HdrInfo
7314table specifies
7315.i sendmail 's
7316preference
7317for which field to return error messages to.
7318.ip H_ERRORSTO
7319Addresses in this header should receive error messages.
7320.ip H_CTE
7321This header is a Content-Transfer-Encoding header.
7322.ip H_CTYPE
7323This header is a Content-Type header.
7324.ip H_STRIPVAL
7325Strip the value from the header (for Bcc:).
7326.nr ii 5n
7327.lp
7328Let's look at a sample
7329.i HdrInfo
7330specification:
7331.(b
7332.ta 4n +\w'"content-transfer-encoding", 'u
7333struct hdrinfo HdrInfo[] =
7334\&{
7335 /* originator fields, most to least significant */
7336 "resent-sender", H_FROM,
7337 "resent-from", H_FROM,
7338 "sender", H_FROM,
7339 "from", H_FROM,
7340 "full-name", H_ACHECK,
7341 "errors-to", H_FROM\^|\^H_ERRORSTO,
7342 /* destination fields */
7343 "to", H_RCPT,
7344 "resent-to", H_RCPT,
7345 "cc", H_RCPT,
7346 "bcc", H_RCPT\^|\^H_STRIPVAL,
7347 /* message identification and control */
7348 "message", H_EOH,
7349 "text", H_EOH,
7350 /* trace fields */
7351 "received", H_TRACE\^|\^H_FORCE,
7352 /* miscellaneous fields */
7353 "content-transfer-encoding", H_CTE,
7354 "content-type", H_CTYPE,
7355
7356 NULL, 0,
7357};
7358.)b
7359This structure indicates that the
7360.q To: ,
7361.q Resent-To: ,
7362and
7363.q Cc:
7364fields
7365all specify recipient addresses.
7366Any
7367.q Full-Name:
7368field will be deleted unless the required mailer flag
7369(indicated in the configuration file)
7370is specified.
7371The
7372.q Message:
7373and
7374.q Text:
7375fields will terminate the header;
7376these are used by random dissenters around the network world.
7377The
7378.q Received:
7379field will always be added,
7380and can be used to trace messages.
7381.pp
7382There are a number of important points here.
7383First,
7384header fields are not added automatically just because they are in the
7385.i HdrInfo
7386structure;
7387they must be specified in the configuration file
7388in order to be added to the message.
7389Any header fields mentioned in the configuration file but not
7390mentioned in the
7391.i HdrInfo
7392structure have default processing performed;
7393that is,
7394they are added unless they were in the message already.
7395Second,
7396the
7397.i HdrInfo
7398structure only specifies cliched processing;
7399certain headers are processed specially by ad hoc code
7400regardless of the status specified in
7401.i HdrInfo .
7402For example,
7403the
7404.q Sender:
7405and
7406.q From:
7407fields are always scanned on ARPANET mail
7408to determine the sender\**;
7409.(f
7410\**Actually, this is no longer true in SMTP;
7411this information is contained in the envelope.
7412The older ARPANET protocols did not completely distinguish
7413envelope from header.
7414.)f
7415this is used to perform the
7416.q "return to sender"
7417function.
7418The
7419.q "From:"
7420and
7421.q "Full-Name:"
7422fields are used to determine the full name of the sender
7423if possible;
7424this is stored in the macro
7425.b $x
7426and used in a number of ways.
7427.sh 3 "Restricting Use of Email"
7428.pp
7429If it is necessary to restrict mail through a relay,
7430the
7431.i checkcompat
7432routine can be modified.
7433This routine is called for every recipient address.
7434It returns an exit status
7435indicating the status of the message.
7436The status
7437.sm EX_OK
7438accepts the address,
7439.sm EX_TEMPFAIL
7440queues the message for a later try,
7441and other values
7442(commonly
7443.sm EX_UNAVAILABLE )
7444reject the message.
7445It is up to
7446.i checkcompat
7447to print an error message
7448(using
7449.i usrerr )
7450if the message is rejected.
7451For example,
7452.i checkcompat
7453could read:
7454.(b
7455.re
7456.sz -1
7457.ta 4n +4n +4n +4n +4n +4n +4n
7458int
7459checkcompat(to, e)
7460 register ADDRESS *to;
7461 register ENVELOPE *e;
7462\&{
7463 register STAB *s;
7464
7465 s = stab("private", ST_MAILER, ST_FIND);
7466 if (s != NULL && e\->e_from.q_mailer != LocalMailer &&
7467 to->q_mailer == s->s_mailer)
7468 {
7469 usrerr("No private net mail allowed through this machine");
7470 return (EX_UNAVAILABLE);
7471 }
7472 if (MsgSize > 50000 && bitnset(M_LOCALMAILER, to\->q_mailer))
7473 {
7474 usrerr("Message too large for non-local delivery");
7475 e\->e_flags |= EF_NORETURN;
7476 return (EX_UNAVAILABLE);
7477 }
7478 return (EX_OK);
7479}
7480.sz
7481.)b
7482This would reject messages greater than 50000 bytes
7483unless they were local.
7484The
7485.i EF_NORETURN
7486flag can be set in
7487.i e\(->e_flags
7488to suppress the return of the actual body
7489of the message in the error return.
7490The actual use of this routine is highly dependent on the
7491implementation,
7492and use should be limited.
7493.sh 3 "New Database Map Classes"
7494.pp
7495New key maps can be added by creating a class initialization function
7496and a lookup function.
7497These are then added to the routine
7498.i setupmaps.
7499.pp
7500The initialization function is called as
7501.(b
7502\fIxxx\fP_map_init(MAP *map, char *args)
7503.)b
7504The
7505.i map
7506is an internal data structure.
7507The
7508.i args
7509is a pointer to the portion of the configuration file line
7510following the map class name;
7511flags and filenames can be extracted from this line.
7512The initialization function must return
7513.sm TRUE
7514if it successfully opened the map,
7515.sm FALSE
7516otherwise.
7517.pp
7518The lookup function is called as
7519.(b
7520\fIxxx\fP_map_lookup(MAP *map, char buf[], char **av, int *statp)
7521.)b
7522The
7523.i map
7524defines the map internally.
7525The
7526.i buf
7527has the input key.
7528This may be (and often is) used destructively.
7529The
7530.i av
7531is a list of arguments passed in from the rewrite line.
7532The lookup function should return a pointer to the new value.
7533If the map lookup fails,
7534.i *statp
7535should be set to an exit status code;
7536in particular, it should be set to
7537.sm EX_TEMPFAIL
7538if recovery is to be attempted by the higher level code.
7539.sh 3 "Queueing Function"
7540.pp
7541The routine
7542.i shouldqueue
7543is called to decide if a message should be queued
7544or processed immediately.
7545Typically this compares the message priority to the current load average.
7546The default definition is:
7547.(b
7548bool
7549shouldqueue(pri, ctime)
7550 long pri;
7551 time_t ctime;
7552{
7553 if (CurrentLA < QueueLA)
7554 return (FALSE);
7555 return (pri > (QueueFactor / (CurrentLA \- QueueLA + 1)));
7556}
7557.)b
7558If the current load average
7559(global variable
7560.i CurrentLA ,
7561which is set before this function is called)
7562is less than the low threshold load average
7563(option
7564.b x ,
7565variable
7566.i QueueLA ),
7567.i shouldqueue
7568returns
7569.sm FALSE
7570immediately
7571(that is, it should
7572.i not
7573queue).
7574If the current load average exceeds the high threshold load average
7575(option
7576.b X ,
7577variable
7578.i RefuseLA ),
7579.i shouldqueue
7580returns
7581.sm TRUE
7582immediately.
7583Otherwise, it computes the function based on the message priority,
7584the queue factor
7585(option
7586.b q ,
7587global variable
7588.i QueueFactor ),
7589and the current and threshold load averages.
7590.pp
7591An implementation wishing to take the actual age of the message into account
7592can also use the
7593.i ctime
7594parameter,
7595which is the time that the message was first submitted to
7596.i sendmail .
7597Note that the
7598.i pri
7599parameter is already weighted
7600by the number of times the message has been tried
7601(although this tends to lower the priority of the message with time);
7602the expectation is that the
7603.i ctime
7604would be used as an
7605.q "escape clause"
7606to ensure that messages are eventually processed.
7607.sh 3 "Refusing Incoming SMTP Connections"
7608.pp
7609The function
7610.i refuseconnections
7611returns
7612.sm TRUE
7613if incoming SMTP connections should be refused.
7614The current implementation is based exclusively on the current load average
7615and the refuse load average option
7616(option
7617.b X ,
7618global variable
7619.i RefuseLA ):
7620.(b
7621bool
7622refuseconnections()
7623{
7624 return (CurrentLA >= RefuseLA);
7625}
7626.)b
7627A more clever implementation
7628could look at more system resources.
7629.sh 3 "Load Average Computation"
7630.pp
7631The routine
7632.i getla
7633returns the current load average (as a rounded integer).
7634The distribution includes several possible implementations.
7635If you are porting to a new environment
7636you may need to add some new tweaks.\**
7637.(f
7638\**If you do, please send updates to
7639sendmail@Sendmail.ORG.
7640.)f
7641.sh 2 "Configuration in src/daemon.c"
7642.pp
7643The file
7644.i src/daemon.c
7645contains a number of routines that are dependent
7646on the local networking environment.
7647The version supplied assumes you have BSD style sockets.
7648.pp
7649In previous releases,
7650we recommended that you modify the routine
7651.i maphostname
7652if you wanted to generalize
7653.b $[
7654\&...\&
7655.b $]
7656lookups.
7657We now recommend that you create a new keyed map instead.
7658.sh 1 "ACKNOWLEDGEMENTS"
7659.pp
7660I've worked on
7661.i sendmail
7662for many years,
7663and many employers have been remarkably patient
7664about letting me work on a large project
7665that was not part of my official job.
7666This includes time on the INGRES Project at
7667the University of California at Berkeley,
7668at Britton Lee,
7669and again on the Mammoth and Titan Projects at Berkeley.
7670.pp
7671Much of the second wave of improvements
7672resulting in version 8.1
7673should be credited to Bryan Costales of the
7674International Computer Science Institute.
7675As he passed me drafts of his book on
7676.i sendmail
7677I was inspired to start working on things again.
7678Bryan was also available to bounce ideas off of.
7679.pp
7680Gregory Neil Shapiro
7681of Worchester Polytechnic Institute
7682has become instrumental in all phases of
7683.i sendmail
7684support and development,
7685and was largely responsible for getting versions 8.8 and 8.9
7686out the door.
7687.pp
7688Many, many people contributed chunks of code and ideas to
7689.i sendmail .
7690It has proven to be a group network effort.
7691Version 8 in particular was a group project.
7692The following people made notable contributions:
7693.(l
7694John Beck, Hewlett-Packard & Sun Microsystems
7695Keith Bostic, CSRG, University of California, Berkeley
7696Andrew Cheng, Sun Microsystems
7697Michael J. Corrigan, University of California, San Diego
7698Bryan Costales, International Computer Science Institute & InfoBeat
7699Pa\*:r (Pell) Emanuelsson
7700Craig Everhart, Transarc Corporation
7701Per Hedeland, Ericsson
7702Tom Ivar Helbekkmo, Norwegian School of Economics
7703Kari Hurtta, Finnish Meteorological Institute
7704Allan E. Johannesen, WPI
7705Jonathan Kamens, OpenVision Technologies, Inc.
7706Takahiro Kanbe, Fuji Xerox Information Systems Co., Ltd.
7707Brian Kantor, University of California, San Diego
7708John Kennedy, Cal State University, Chico
7709Murray S. Kucherawy, HookUp Communication Corp.
7710Bruce Lilly, Sony U.S.
7711Karl London
7712Motonori Nakamura, Ritsumeikan University & Kyoto University
7713John Gardiner Myers, Carnegie Mellon University
7714Neil Rickert, Northern Illinois University
7715Gregory Neil Shapiro, WPI
7716Eric Schnoebelen, Convex Computer Corp.
7717Eric Wassenaar, National Institute for Nuclear and High Energy Physics, Amsterdam
7718Randall Winchester, University of Maryland
7719Christophe Wolfhugel, Pasteur Institute & Herve Schauer Consultants (Paris)
7720.)l
7721I apologize for anyone I have omitted, misspelled, misattributed, or
7722otherwise missed.
7723At this point, I suspect that at least a hundred people
7724have contributed code,
7725and many more have contributed ideas, comments, and encouragement.
7726I've tried to list them in the RELEASE_NOTES in the distribution directory.
7727I appreciate their contribution as well.
7728.pp
7729Special thanks are reserved for Michael Corrigan and Christophe Wolfhugel,
7730who besides being wonderful guinea pigs and contributors
7731have also consented to be added to the ``sendmail@Sendmail.ORG'' list
7732and, by answering the bulk of the questions sent to that list,
7733have freed me up to do other work.
7734.++ A
7735.+c "COMMAND LINE FLAGS"
7736.ba 0
7737.nr ii 1i
7738.pp
7739Arguments must be presented with flags before addresses.
7740The flags are:
7741.ip \-b\fIx\fP
7742Set operation mode to
7743.i x .
7744Operation modes are:
7745.(b
7746.ta 4n
7747m Deliver mail (default)
7748s Speak SMTP on input side
7749a\(dg ``Arpanet'' mode (get envelope sender information from header)
7750d Run as a daemon in background
7751D Run as a daemon in foreground
7752t Run in test mode
7753v Just verify addresses, don't collect or deliver
7754i Initialize the alias database
7755p Print the mail queue
7756.)b
7757.(f
7758\(dgDeprecated.
7759.)f
7760.ip \-B\fItype\fP
7761Indicate body type.
7762.ip \-C\fIfile\fP
7763Use a different configuration file.
7764.i Sendmail
7765runs as the invoking user (rather than root)
7766when this flag is specified.
7767.ip \-d\fIlevel\fP
7768Set debugging level.
7769.ip "\-f\ \fIaddr\fP"
7770The sender's machine address is
7771.i addr .
7772.ip \-F\ \fIname\fP
7773Sets the full name of this user to
7774.i name .
7775.ip "\-h\ \fIcnt\fP"
7776Sets the
7777.q "hop count"
7778to
7779.i cnt .
7780This represents the number of times this message has been processed
7781by
7782.i sendmail
7783(to the extent that it is supported by the underlying networks).
7784.i Cnt
7785is incremented during processing,
7786and if it reaches
7787MAXHOP
7788(currently 30)
7789.i sendmail
7790throws away the message with an error.
7791.ip \-n
7792Don't do aliasing or forwarding.
7793.ip "\-N \fInotifications\fP"
7794Tag all addresses being sent as wanting the indicated
7795.i notifications ,
7796which consists of the word
7797.q NEVER
7798or a comma-separated list of
7799.q SUCCESS ,
7800.q FAILURE ,
7801and
7802.q DELAY
7803for successful delivery,
7804failure,
7805and a message that is stuck in a queue somewhere.
7806The default is
7807.q FAILURE,DELAY .
7808.ip "\-r\ \fIaddr\fP"
7809An obsolete form of
7810.b \-f .
7811.ip \-o\fIx\|value\fP
7812Set option
7813.i x
7814to the specified
7815.i value .
7816These options are described in Section 5.6.
7817.ip \-O\fIoption\fP\fB=\fP\fIvalue\fP
7818Set
7819.i option
7820to the specified
7821.i value
7822(for long form option names).
7823These options are described in Section 5.6.
7824.ip \-M\fIx\|value
7825Set macro
7826.i x
7827to the specified
7828.i value .
7829.ip \-p\fIprotocol\fP
7830Set the sending protocol.
7831Programs are encouraged to set this.
7832The protocol field can be in the form
7833.i protocol \c
7834.b : \c
7835.i host
7836to set both the sending protocol and sending host.
7837For example,
7838.q \-pUUCP:uunet
7839sets the sending protocol to UUCP
7840and the sending host to uunet.
7841(Some existing programs use \-oM to set the r and s macros;
7842this is equivalent to using \-p.)
7843.ip \-q\fItime\fP
7844Try to process the queued up mail.
7845If the time is given,
7846a
7847.i sendmail
7848will run through the queue at the specified interval
7849to deliver queued mail;
7850otherwise, it only runs once.
7851.ip \-q\fIXstring\fP
7852Run the queue once,
7853limiting the jobs to those matching
7854.i Xstring .
7855The key letter
7856.i X
7857can be
7858.b I
7859to limit based on queue identifier,
7860.b R
7861to limit based on recipient,
7862or
7863.b S
7864to limit based on sender.
7865A particular queued job is accepted if one of the corresponding addresses
7866contains the indicated
7867.i string .
7868Multiple
7869.i \-q\fIX\fP
7870flags are permitted,
7871with items with the same key letter
7872.q or'ed
7873together, and items with different key letters
7874.q and'ed
7875together.
7876.ip "\-R ret"
7877What information you want returned if the message bounces;
7878.i ret
7879can be
7880.q HDRS
7881for headers only or
7882.q FULL
7883for headers plus body.
7884This is a request only;
7885the other end is not required to honor the parameter.
7886.ip \-t
7887Read the header for
7888.q To: ,
7889.q Cc: ,
7890and
7891.q Bcc:
7892lines, and send to everyone listed in those lists.
7893The
7894.q Bcc:
7895line will be deleted before sending.
7896Any addresses in the argument vector will be deleted
7897from the send list.
7898.ip "\-U"
7899Indicate that this is an initial User Agent submission.
7900In future releases, sendmail may complain about syntactically invalid messages
7901rather than fixing them when this flag is not set.
7902.ip "\-V envid"
7903The indicated
7904.i envid
7905is passed with the envelope of the message
7906and returned if the message bounces.
7907.ip "\-X \fIlogfile\fP"
7908Log all traffic in and out of
7909.i sendmail
7910in the indicated
7911.i logfile
7912for debugging mailer problems.
7913This produces a lot of data very quickly and should be used sparingly.
7914.pp
7915There are a number of options that may be specified as
7916primitive flags.
7917These are the e, i, m, and v options.
7918Also,
7919the f option
7920may be specified as the
7921.b \-s
7922flag.
7923.+c "QUEUE FILE FORMATS"
7924.pp
7925This appendix describes the format of the queue files.
7926These files live in the directory defined by the
7927.b Q
7928option in the
7929.i sendmail.cf
7930file, usually
7931.i /var/spool/mqueue
7932or
7933.i /usr/spool/mqueue .
7934.pp
7935All queue files have the name
7936\fIx\fP\|\fBf\fP\fIAAA99999\fP
7937where
7938.i AAA99999
7939is the
7940.i id
7941for this message
7942and the
7943.i x
7944is a type.
7945The first letter of the id encodes the hour of the day
7946that the message was received by the system
7947(with A being the hour between midnight and 1:00AM).
7948All files with the same id collectively define one message.
7949.pp
7950The types are:
7951.nr ii 0.5i
7952.ip d
7953The data file.
7954The message body (excluding the header) is kept in this file.
7955.ip q
7956The queue control file.
7957This file contains the information necessary to process the job.
7958.ip t
7959A temporary file.
7960These are an image of the
7961.b qf
7962file when it is being rebuilt.
7963It should be renamed to a
7964.b qf
7965file very quickly.
7966.ip x
7967A transcript file,
7968existing during the life of a session
7969showing everything that happens
7970during that session.
7971.pp
7972The
7973.b qf
7974file is structured as a series of lines
7975each beginning with a code letter.
7976The lines are as follows:
7977.ip V
7978The version number of the queue file format,
7979used to allow new
7980.i sendmail
7981binaries to read queue files created by older versions.
7982Defaults to version zero.
7983Must be the first line of the file if present.
7984.ip H
7985A header definition.
7986There may be any number of these lines.
7987The order is important:
7988they represent the order in the final message.
7989These use the same syntax
7990as header definitions in the configuration file.
7991.ip C
7992The controlling address.
7993The syntax is
7994.q localuser:aliasname .
7995Recipient addresses following this line
7996will be flagged so that deliveries will be run as the
7997.i localuser
7998(a user name from the /etc/passwd file);
7999.i aliasname
8000is the name of the alias that expanded to this address
8001(used for printing messages).
8002.ip Q
8003The ``original recipient'',
8004specified by the ORCPT= field in an ESMTP transaction.
8005Used exclusively for Delivery Status Notifications.
8006It applies only to the immediately following `R' line.
8007.ip R
8008A recipient address.
8009This will normally be completely aliased,
8010but is actually realiased when the job is processed.
8011There will be one line
8012for each recipient.
8013Version 1 qf files
8014also include a leading colon-terminated list of flags,
8015which can be
8016`S' to return a message on successful final delivery,
8017`F' to return a message on failure,
8018`D' to return a message if the message is delayed,
8019`B' to indicate that the body should be returned,
8020`N' to suppress returning the body,
8021and
8022`P' to declare this as a ``primary'' (command line or SMTP-session) address.
8023.ip S
8024The sender address.
8025There may only be one of these lines.
8026.ip T
8027The job creation time.
8028This is used to compute when to time out the job.
8029.ip P
8030The current message priority.
8031This is used to order the queue.
8032Higher numbers mean lower priorities.
8033The priority changes
8034as the message sits in the queue.
8035The initial priority depends on the message class
8036and the size of the message.
8037.ip M
8038A message.
8039This line is printed by the
8040.i mailq
8041command,
8042and is generally used to store status information.
8043It can contain any text.
8044.ip F
8045Flag bits, represented as one letter per flag.
8046Defined flag bits are
8047.b r
8048indicating that this is a response message
8049and
8050.b w
8051indicating that a warning message has been sent
8052announcing that the mail has been delayed.
8053.ip N
8054The total number of delivery attempts.
8055.ip K
8056The time (as seconds since January 1, 1970)
8057of the last delivery attempt.
8058.ip I
8059The i-number of the data file;
8060this can be used to recover your mail queue
8061after a disastrous disk crash.
8062.ip $
8063A macro definition.
8064The values of certain macros
8065(as of this writing, only
8066.b $r
8067and
8068.b $s )
8069are passed through to the queue run phase.
8070.ip B
8071The body type.
8072The remainder of the line is a text string defining the body type.
8073If this field is missing,
8074the body type is assumed to be
8075.q "undefined"
8076and no special processing is attempted.
8077Legal values are
8078.q 7BIT
8079and
8080.q 8BITMIME .
8081.ip O
8082The original MTS value (from the ESMTP transaction).
8083For Deliver Status Notifications only.
8084.ip Z
8085The original envelope id (from the ESMTP transaction).
8086For Deliver Status Notifications only.
8087.pp
8088As an example,
8089the following is a queue file sent to
8090.q eric@mammoth.Berkeley.EDU
8091and
8092.q bostic@okeeffe.CS.Berkeley.EDU \**:
8093.(f
8094\**This example is contrived and probably inaccurate for your environment.
8095Glance over it to get an idea;
8096nothing can replace looking at what your own system generates.
8097.)f
8098.(b
8099P835771
8100T404261372
8101Seric
8102Ceric:sendmail@vangogh.CS.Berkeley.EDU
8103Reric@mammoth.Berkeley.EDU
8104Rbostic@okeeffe.CS.Berkeley.EDU
8105H?P?Return-path: <owner-sendmail@vangogh.CS.Berkeley.EDU>
8106HReceived: by vangogh.CS.Berkeley.EDU (5.108/2.7) id AAA06703;
8107 Fri, 17 Jul 1992 00:28:55 -0700
8108HReceived: from mail.CS.Berkeley.EDU by vangogh.CS.Berkeley.EDU (5.108/2.7)
8109 id AAA06698; Fri, 17 Jul 1992 00:28:54 -0700
8110HReceived: from [128.32.31.21] by mail.CS.Berkeley.EDU (5.96/2.5)
8111 id AA22777; Fri, 17 Jul 1992 03:29:14 -0400
8112HReceived: by foo.bar.baz.de (5.57/Ultrix3.0-C)
8113 id AA22757; Fri, 17 Jul 1992 09:31:25 GMT
8114H?F?From: eric@foo.bar.baz.de (Eric Allman)
8115H?x?Full-name: Eric Allman
8116HMessage-id: <9207170931.AA22757@foo.bar.baz.de>
8117HTo: sendmail@vangogh.CS.Berkeley.EDU
8118HSubject: this is an example message
8119.)b
8120This shows
8121the person who sent the message,
8122the submission time
8123(in seconds since January 1, 1970),
8124the message priority,
8125the message class,
8126the recipients,
8127and the headers for the message.
8128.+c "SUMMARY OF SUPPORT FILES"
8129.pp
8130This is a summary of the support files
8131that
8132.i sendmail
8133creates or generates.
8134Many of these can be changed by editing the sendmail.cf file;
8135check there to find the actual pathnames.
8136.nr ii 1i
8137.ip "/usr/\*(SD/sendmail"
8138The binary of
8139.i sendmail .
8140.ip /usr/\*(SB/newaliases
8141A link to /usr/\*(SD/sendmail;
8142causes the alias database to be rebuilt.
8143Running this program is completely equivalent to giving
8144.i sendmail
8145the
8146.b \-bi
8147flag.
8148.ip /usr/\*(SB/mailq
8149Prints a listing of the mail queue.
8150This program is equivalent to using the
8151.b \-bp
8152flag to
8153.i sendmail .
8154.ip /etc/sendmail.cf
8155The configuration file,
8156in textual form.
8157.ip /usr/lib/sendmail.hf
8158The SMTP help file.
8159.ip /etc/sendmail.st
8160A statistics file; need not be present.
8161.ip /etc/sendmail.pid
8162Created in daemon mode;
8163it contains the process id of the current SMTP daemon.
8164If you use this in scripts;
8165use ``head \-1'' to get just the first line;
8166the second line contains the command line used to invoke the daemon,
8167and later versions of
8168.i sendmail
8169may add more information to subsequent lines.
8170.ip /etc/aliases
8171The textual version of the alias file.
8172.ip /etc/aliases.db
8173The alias file in
8174.i hash \|(3)
8175format.
8176.ip /etc/aliases.{pag,dir}
8177The alias file in
8178.i ndbm \|(3)
8179format.
8180.ip /var/spool/mqueue
8181The directory in which the mail queue
8182and temporary files reside.
8183.ip /var/spool/mqueue/qf*
8184Control (queue) files for messages.
8185.ip /var/spool/mqueue/df*
8186Data files.
8187.ip /var/spool/mqueue/tf*
8188Temporary versions of the qf files,
8189used during queue file rebuild.
8190.ip /var/spool/mqueue/xf*
8191A transcript of the current session.
8192.if o \
8193\{\
8194. bp
8195. rs
8196. sp |4i
8197. ce 2
8198This page intentionally left blank;
8199replace it with a blank sheet for double-sided output.
8200.\}
8201.\".ro
8202.\".ls 1
8203.\".tp
8204.\".sp 2i
8205.\".in 0
8206.\".ce 100
8207.\".sz 24
8208.\".b SENDMAIL
8209.\".sz 14
8210.\".sp
8211.\"INSTALLATION AND OPERATION GUIDE
8212.\".sp
8213.\".sz 10
8214.\"Eric Allman
8215.\".sp
| 2884.sh 2 "Free Space"
2885.pp
2886On systems that have one of the system calls in the
2887.i statfs (2)
2888family
2889(including
2890.i statvfs
2891and
2892.i ustat ),
2893you can specify a minimum number of free blocks on the queue filesystem
2894using the
2895.b MinFreeBlocks
2896(\c
2897.b b )
2898option.
2899If there are fewer than the indicated number of blocks free
2900on the filesystem on which the queue is mounted
2901the SMTP server will reject mail
2902with the
2903452 error code.
2904This invites the SMTP client to try again later.
2905.pp
2906Beware of setting this option too high;
2907it can cause rejection of email
2908when that mail would be processed without difficulty.
2909.sh 2 "Maximum Message Size"
2910.pp
2911To avoid overflowing your system with a large message,
2912the
2913.b MaxMessageSize
2914option can be set to set an absolute limit
2915on the size of any one message.
2916This will be advertised in the ESMTP dialogue
2917and checked during message collection.
2918.sh 2 "Privacy Flags"
2919.pp
2920The
2921.b PrivacyOptions
2922(\c
2923.b p )
2924option allows you to set certain
2925``privacy''
2926flags.
2927Actually, many of them don't give you any extra privacy,
2928rather just insisting that client SMTP servers
2929use the HELO command
2930before using certain commands
2931or adding extra headers to indicate possible spoof attempts.
2932.pp
2933The option takes a series of flag names;
2934the final privacy is the inclusive or of those flags.
2935For example:
2936.(b
2937O PrivacyOptions=needmailhelo, noexpn
2938.)b
2939insists that the HELO or EHLO command be used before a MAIL command is accepted
2940and disables the EXPN command.
2941.pp
2942The flags are detailed in section
2943.\"XREF
29445.6.
2945.sh 2 "Send to Me Too"
2946.pp
2947Normally,
2948.i sendmail
2949deletes the (envelope) sender from any list expansions.
2950For example, if
2951.q matt
2952sends to a list that contains
2953.q matt
2954as one of the members he won't get a copy of the message.
2955If the
2956.b \-m
2957(me too)
2958command line flag, or if the
2959.b MeToo
2960(\c
2961.b m )
2962option is set in the configuration file,
2963this behaviour is suppressed.
2964Some sites like to run the
2965.sm SMTP
2966daemon with
2967.b \-m .
2968.sh 1 "THE WHOLE SCOOP ON THE CONFIGURATION FILE"
2969.pp
2970This section describes the configuration file
2971in detail.
2972.pp
2973There is one point that should be made clear immediately:
2974the syntax of the configuration file
2975is designed to be reasonably easy to parse,
2976since this is done every time
2977.i sendmail
2978starts up,
2979rather than easy for a human to read or write.
2980On the
2981.q "future project"
2982list is a
2983configuration-file compiler.
2984.pp
2985The configuration file is organized as a series of lines,
2986each of which begins with a single character
2987defining the semantics for the rest of the line.
2988Lines beginning with a space or a tab
2989are continuation lines
2990(although the semantics are not well defined in many places).
2991Blank lines and lines beginning with a sharp symbol
2992(`#')
2993are comments.
2994.sh 2 "R and S \*- Rewriting Rules"
2995.pp
2996The core of address parsing
2997are the rewriting rules.
2998These are an ordered production system.
2999.i Sendmail
3000scans through the set of rewriting rules
3001looking for a match on the left hand side
3002(LHS)
3003of the rule.
3004When a rule matches,
3005the address is replaced by the right hand side
3006(RHS)
3007of the rule.
3008.pp
3009There are several sets of rewriting rules.
3010Some of the rewriting sets are used internally
3011and must have specific semantics.
3012Other rewriting sets
3013do not have specifically assigned semantics,
3014and may be referenced by the mailer definitions
3015or by other rewriting sets.
3016.pp
3017The syntax of these two commands are:
3018.(b F
3019.b S \c
3020.i n
3021.)b
3022Sets the current ruleset being collected to
3023.i n .
3024If you begin a ruleset more than once
3025it appends to the old definition.
3026.(b F
3027.b R \c
3028.i lhs
3029.i rhs
3030.i comments
3031.)b
3032The
3033fields must be separated
3034by at least one tab character;
3035there may be embedded spaces
3036in the fields.
3037The
3038.i lhs
3039is a pattern that is applied to the input.
3040If it matches,
3041the input is rewritten to the
3042.i rhs .
3043The
3044.i comments
3045are ignored.
3046.pp
3047Macro expansions of the form
3048.b $ \c
3049.i x
3050are performed when the configuration file is read.
3051Expansions of the form
3052.b $& \c
3053.i x
3054are performed at run time using a somewhat less general algorithm.
3055This is intended only for referencing internally defined macros
3056such as
3057.b $h
3058that are changed at runtime.
3059.sh 3 "The left hand side"
3060.pp
3061The left hand side of rewriting rules contains a pattern.
3062Normal words are simply matched directly.
3063Metasyntax is introduced using a dollar sign.
3064The metasymbols are:
3065.(b
3066.ta \w'\fB$=\fP\fIx\fP 'u
3067\fB$*\fP Match zero or more tokens
3068\fB$+\fP Match one or more tokens
3069\fB$\-\fP Match exactly one token
3070\fB$=\fP\fIx\fP Match any phrase in class \fIx\fP
3071\fB$~\fP\fIx\fP Match any word not in class \fIx\fP
3072.)b
3073If any of these match,
3074they are assigned to the symbol
3075.b $ \c
3076.i n
3077for replacement on the right hand side,
3078where
3079.i n
3080is the index in the LHS.
3081For example,
3082if the LHS:
3083.(b
3084$\-:$+
3085.)b
3086is applied to the input:
3087.(b
3088UCBARPA:eric
3089.)b
3090the rule will match, and the values passed to the RHS will be:
3091.(b
3092.ta 4n
3093$1 UCBARPA
3094$2 eric
3095.)b
3096.pp
3097Additionally, the LHS can include
3098.b $@
3099to match zero tokens.
3100This is
3101.i not
3102bound to a
3103.b $ \c
3104.i n
3105on the RHS, and is normally only used when it stands alone
3106in order to match the null input.
3107.sh 3 "The right hand side"
3108.pp
3109When the left hand side of a rewriting rule matches,
3110the input is deleted and replaced by the right hand side.
3111Tokens are copied directly from the RHS
3112unless they begin with a dollar sign.
3113Metasymbols are:
3114.(b
3115.ta \w'$#mailer\0\0\0'u
3116\fB$\fP\fIn\fP Substitute indefinite token \fIn\fP from LHS
3117\fB$[\fP\fIname\fP\fB$]\fP Canonicalize \fIname\fP
3118\fB$(\fP\fImap key\fP \fB$@\fP\fIarguments\fP \fB$:\fP\fIdefault\fP \fB$)\fP
3119 Generalized keyed mapping function
3120\fB$>\fP\fIn\fP \*(lqCall\*(rq ruleset \fIn\fP
3121\fB$#\fP\fImailer\fP Resolve to \fImailer\fP
3122\fB$@\fP\fIhost\fP Specify \fIhost\fP
3123\fB$:\fP\fIuser\fP Specify \fIuser\fP
3124.)b
3125.pp
3126The
3127.b $ \c
3128.i n
3129syntax substitutes the corresponding value from a
3130.b $+ ,
3131.b $\- ,
3132.b $* ,
3133.b $= ,
3134or
3135.b $~
3136match on the LHS.
3137It may be used anywhere.
3138.pp
3139A host name enclosed between
3140.b $[
3141and
3142.b $]
3143is looked up in the host database(s)
3144and replaced by the canonical name\**.
3145.(f
3146\**This is actually
3147completely equivalent
3148to $(host \fIhostname\fP$).
3149In particular, a
3150.b $:
3151default can be used.
3152.)f
3153For example,
3154.q $[ftp$]
3155might become
3156.q ftp.CS.Berkeley.EDU
3157and
3158.q $[[128.32.130.2]$]
3159would become
3160.q vangogh.CS.Berkeley.EDU.
3161.i Sendmail
3162recognizes its numeric IP address
3163without calling the name server
3164and replaces it with its canonical name.
3165.pp
3166The
3167.b $(
3168\&...
3169.b $)
3170syntax is a more general form of lookup;
3171it uses a named map instead of an implicit map.
3172If no lookup is found, the indicated
3173.i default
3174is inserted;
3175if no default is specified and no lookup matches,
3176the value is left unchanged.
3177The
3178.i arguments
3179are passed to the map for possible use.
3180.pp
3181The
3182.b $> \c
3183.i n
3184syntax
3185causes the remainder of the line to be substituted as usual
3186and then passed as the argument to ruleset
3187.i n .
3188The final value of ruleset
3189.i n
3190then becomes
3191the substitution for this rule.
3192The
3193.b $>
3194syntax expands everything after the ruleset name
3195to the end of the replacement string
3196and then passes that as the initial input to the ruleset.
3197Recursive calls are allowed.
3198For example,
3199.(b
3200$>0 $>3 $1
3201.)b
3202expands $1, passes that to ruleset 3, and then passes the result
3203of ruleset 3 to ruleset 0.
3204.pp
3205The
3206.b $#
3207syntax should
3208.i only
3209be used in ruleset zero
3210or a subroutine of ruleset zero.
3211It causes evaluation of the ruleset to terminate immediately,
3212and signals to
3213.i sendmail
3214that the address has completely resolved.
3215The complete syntax is:
3216.(b
3217\fB$#\fP\fImailer\fP \fB$@\fP\fIhost\fP \fB$:\fP\fIuser\fP
3218.)b
3219This specifies the
3220{mailer, host, user}
32213-tuple necessary to direct the mailer.
3222If the mailer is local
3223the host part may be omitted\**.
3224.(f
3225\**You may want to use it for special
3226.q "per user"
3227extensions.
3228For example, in the address
3229.q jgm+foo@CMU.EDU ;
3230the
3231.q +foo
3232part is not part of the user name,
3233and is passed to the local mailer for local use.
3234.)f
3235The
3236.i mailer
3237must be a single word,
3238but the
3239.i host
3240and
3241.i user
3242may be multi-part.
3243If the
3244.i mailer
3245is the builtin IPC mailer,
3246the
3247.i host
3248may be a colon-separated list of hosts
3249that are searched in order for the first working address
3250(exactly like MX records).
3251The
3252.i user
3253is later rewritten by the mailer-specific envelope rewriting set
3254and assigned to the
3255.b $u
3256macro.
3257As a special case, if the mailer specified has the
3258.b F=@
3259flag specified
3260and the first character of the
3261.b $:
3262value is
3263.q @ ,
3264the
3265.q @
3266is stripped off, and a flag is set in the address descriptor
3267that causes sendmail to not do ruleset 5 processing.
3268.pp
3269Normally, a rule that matches is retried,
3270that is,
3271the rule loops until it fails.
3272A RHS may also be preceded by a
3273.b $@
3274or a
3275.b $:
3276to change this behavior.
3277A
3278.b $@
3279prefix causes the ruleset to return with the remainder of the RHS
3280as the value.
3281A
3282.b $:
3283prefix causes the rule to terminate immediately,
3284but the ruleset to continue;
3285this can be used to avoid continued application of a rule.
3286The prefix is stripped before continuing.
3287.pp
3288The
3289.b $@
3290and
3291.b $:
3292prefixes may precede a
3293.b $>
3294spec;
3295for example:
3296.(b
3297.ta 8n
3298R$+ $: $>7 $1
3299.)b
3300matches anything,
3301passes that to ruleset seven,
3302and continues;
3303the
3304.b $:
3305is necessary to avoid an infinite loop.
3306.pp
3307Substitution occurs in the order described,
3308that is,
3309parameters from the LHS are substituted,
3310hostnames are canonicalized,
3311.q subroutines
3312are called,
3313and finally
3314.b $# ,
3315.b $@ ,
3316and
3317.b $:
3318are processed.
3319.sh 3 "Semantics of rewriting rule sets"
3320.pp
3321There are six rewriting sets
3322that have specific semantics.
3323Five of these are related as depicted by figure 1.
3324.(z
3325.hl
3326.ie n \{\
3327.(c
3328 +---+
3329 -->| 0 |-->resolved address
3330 / +---+
3331 / +---+ +---+
3332 / ---->| 1 |-->| S |--
3333 +---+ / +---+ / +---+ +---+ \e +---+
3334addr-->| 3 |-->| D |-- --->| 4 |-->msg
3335 +---+ +---+ \e +---+ +---+ / +---+
3336 --->| 2 |-->| R |--
3337 +---+ +---+
3338.)c
3339
3340.\}
3341.el .ie !"\*(.T"" \
3342\{\
3343.PS
3344boxwid = 0.3i
3345boxht = 0.3i
3346movewid = 0.3i
3347moveht = 0.3i
3348linewid = 0.3i
3349lineht = 0.3i
3350
3351 box invis "addr"; arrow
3352Box3: box "3"
3353A1: arrow
3354BoxD: box "D"; line; L1: Here
3355C: [
3356 C1: arrow; box "1"; arrow; box "S"; line; E1: Here
3357 move to C1 down 0.5; right
3358 C2: arrow; box "2"; arrow; box "R"; line; E2: Here
3359 ] with .w at L1 + (0.5, 0)
3360 move to C.e right 0.5
3361L4: arrow; box "4"; arrow; box invis "msg"
3362 line from L1 to C.C1
3363 line from L1 to C.C2
3364 line from C.E1 to L4
3365 line from C.E2 to L4
3366 move to BoxD.n up 0.6; right
3367Box0: arrow; box "0"
3368 arrow; box invis "resolved address" width 1.3
3369 line from 1/3 of the way between A1 and BoxD.w to Box0
3370.PE
3371.\}
3372.el .sp 2i
3373.ce
3374Figure 1 \*- Rewriting set semantics
3375.(c
3376D \*- sender domain addition
3377S \*- mailer-specific sender rewriting
3378R \*- mailer-specific recipient rewriting
3379.)c
3380.hl
3381.)z
3382.pp
3383Ruleset three
3384should turn the address into
3385.q "canonical form."
3386This form should have the basic syntax:
3387.(b
3388local-part@host-domain-spec
3389.)b
3390Ruleset three
3391is applied by
3392.i sendmail
3393before doing anything with any address.
3394.pp
3395If no
3396.q @
3397sign is specified,
3398then the
3399host-domain-spec
3400.i may
3401be appended (box
3402.q D
3403in Figure 1)
3404from the
3405sender address
3406(if the
3407.b C
3408flag is set in the mailer definition
3409corresponding to the
3410.i sending
3411mailer).
3412.pp
3413Ruleset zero
3414is applied after ruleset three
3415to addresses that are going to actually specify recipients.
3416It must resolve to a
3417.i "{mailer, host, user}"
3418triple.
3419The
3420.i mailer
3421must be defined in the mailer definitions
3422from the configuration file.
3423The
3424.i host
3425is defined into the
3426.b $h
3427macro
3428for use in the argv expansion of the specified mailer.
3429.pp
3430Rulesets one and two
3431are applied to all sender and recipient addresses respectively.
3432They are applied before any specification
3433in the mailer definition.
3434They must never resolve.
3435.pp
3436Ruleset four is applied to all addresses
3437in the message.
3438It is typically used
3439to translate internal to external form.
3440.pp
3441In addition,
3442ruleset 5 is applied to all local addresses
3443(specifically, those that resolve to a mailer with the `F=5'
3444flag set)
3445that do not have aliases.
3446This allows a last minute hook for local names.
3447.sh 3 "Ruleset hooks"
3448.pp
3449A few extra rulesets are defined as
3450.q hooks
3451that can be defined to get special features.
3452They are all named rulesets.
3453The
3454.q check_*
3455forms all give accept/reject status;
3456falling off the end or returning normally is an accept,
3457and resolving to
3458.b $#error
3459is a reject.
3460Many of these can also resolve to the special mailer
3461.b $#discard ;
3462this accepts the message as though it were successful
3463but then discards it without delivery.
3464.sh 4 "check_relay"
3465.pp
3466The
3467.i check_relay
3468ruleset is called after a connection is accepted.
3469It is passed
3470.(b
3471client.host.name $| client.host.address
3472.)b
3473where
3474.b $|
3475is a metacharacter separating the two parts.
3476This ruleset can reject connections from various locations.
3477.sh 4 "check_mail"
3478.pp
3479The
3480.i check_mail
3481ruleset is passed the user name parameter of the
3482.sm "SMTP MAIL"
3483command.
3484It can accept or reject the address.
3485.sh 4 "check_rcpt"
3486.pp
3487The
3488.i check_rcpt
3489ruleset is passed the user name parameter of the
3490.sm "SMTP RCPT"
3491command.
3492It can accept or reject the address.
3493.sh 4 "check_compat"
3494.pp
3495The
3496.i check_compat
3497ruleset is passed
3498.(b
3499sender-address $| recipient-address
3500.)b
3501where
3502.b $|
3503is a metacharacter separating the addresses.
3504It can accept or reject mail transfer between these two addresses
3505much like the
3506.i checkcompat()
3507function.
3508.sh 3 "IPC mailers"
3509.pp
3510Some special processing occurs
3511if the ruleset zero resolves to an IPC mailer
3512(that is, a mailer that has
3513.q [IPC]
3514listed as the Path in the
3515.b M
3516configuration line.
3517The host name passed after
3518.q $@
3519has MX expansion performed;
3520this looks the name up in DNS to find alternate delivery sites.
3521.pp
3522The host name can also be provided as a dotted quad in square brackets;
3523for example:
3524.(b
3525[128.32.149.78]
3526.)b
3527This causes direct conversion of the numeric value
3528to an IP host address.
3529.pp
3530The host name passed in after the
3531.q $@
3532may also be a colon-separated list of hosts.
3533Each is separately MX expanded and the results are concatenated
3534to make (essentially) one long MX list.
3535The intent here is to create
3536.q fake
3537MX records that are not published in DNS
3538for private internal networks.
3539.pp
3540As a final special case, the host name can be passed in
3541as a text string
3542in square brackets:
3543.(b
3544[ucbvax.berkeley.edu]
3545.)b
3546This form avoids the MX mapping.
3547.b N.B.:
3548.i
3549This is intended only for situations where you have a network firewall
3550or other host that will do special processing for all your mail,
3551so that your MX record points to a gateway machine;
3552this machine could then do direct delivery to machines
3553within your local domain.
3554Use of this feature directly violates RFC 1123 section 5.3.5:
3555it should not be used lightly.
3556.r
3557.sh 2 "D \*- Define Macro"
3558.pp
3559Macros are named with a single character
3560or with a word in {braces}.
3561Single character names may be selected from the entire ASCII set,
3562but user-defined macros
3563should be selected from the set of upper case letters only.
3564Lower case letters
3565and special symbols
3566are used internally.
3567Long names beginning with a lower case letter or a punctuation character
3568are reserved for use by sendmail,
3569so user-defined long macro names should begin with an upper case letter.
3570.pp
3571The syntax for macro definitions is:
3572.(b F
3573.b D \c
3574.i x\|val
3575.)b
3576where
3577.i x
3578is the name of the macro
3579(which may be a single character
3580or a word in braces)
3581and
3582.i val
3583is the value it should have.
3584There should be no spaces given
3585that do not actually belong in the macro value.
3586.pp
3587Macros are interpolated
3588using the construct
3589.b $ \c
3590.i x ,
3591where
3592.i x
3593is the name of the macro to be interpolated.
3594This interpolation is done when the configuration file is read,
3595except in
3596.b M
3597lines.
3598The special construct
3599.b $& \c
3600.i x
3601can be used in
3602.b R
3603lines to get deferred interpolation.
3604.pp
3605Conditionals can be specified using the syntax:
3606.(b
3607$?x text1 $| text2 $.
3608.)b
3609This interpolates
3610.i text1
3611if the macro
3612.b $x
3613is set,
3614and
3615.i text2
3616otherwise.
3617The
3618.q else
3619(\c
3620.b $| )
3621clause may be omitted.
3622.pp
3623Lower case macro names are reserved to have
3624special semantics,
3625used to pass information in or out of
3626.i sendmail ,
3627and special characters are reserved to
3628provide conditionals, etc.
3629Upper case names
3630(that is,
3631.b $A
3632through
3633.b $Z )
3634are specifically reserved for configuration file authors.
3635.pp
3636The following macros are defined and/or used internally by
3637.i sendmail
3638for interpolation into argv's for mailers
3639or for other contexts.
3640The ones marked \(dg are information passed into sendmail\**,
3641.(f
3642\**As of version 8.6,
3643all of these macros have reasonable defaults.
3644Previous versions required that they be defined.
3645.)f
3646the ones marked \(dd are information passed both in and out of sendmail,
3647and the unmarked macros are passed out of sendmail
3648but are not otherwise used internally.
3649These macros are:
3650.nr ii 5n
3651.ip $a
3652The origination date in RFC 822 format.
3653This is extracted from the Date: line.
3654.ip $b
3655The current date in RFC 822 format.
3656.ip $c
3657The hop count.
3658This is a count of the number of Received: lines
3659plus the value of the
3660.b \-h
3661command line flag.
3662.ip $d
3663The current date in UNIX (ctime) format.
3664.ip $e\(dg
3665(Obsolete; use SmtpGreetingMessage option instead.)
3666The SMTP entry message.
3667This is printed out when SMTP starts up.
3668The first word must be the
3669.b $j
3670macro as specified by RFC821.
3671Defaults to
3672.q "$j Sendmail $v ready at $b" .
3673Commonly redefined to include the configuration version number, e.g.,
3674.q "$j Sendmail $v/$Z ready at $b"
3675.ip $f
3676The envelope sender (from) address.
3677.ip $g
3678The sender address relative to the recipient.
3679For example, if
3680.b $f
3681is
3682.q foo ,
3683.b $g
3684will be
3685.q host!foo ,
3686.q foo@host.domain ,
3687or whatever is appropriate for the receiving mailer.
3688.ip $h
3689The recipient host.
3690This is set in ruleset 0 from the $@ field of a parsed address.
3691.ip $i
3692The queue id,
3693e.g.,
3694.q HAA12345 .
3695.ip $j\(dd
3696The \*(lqofficial\*(rq domain name for this site.
3697This is fully qualified if the full qualification can be found.
3698It
3699.i must
3700be redefined to be the fully qualified domain name
3701if your system is not configured so that information can find
3702it automatically.
3703.ip $k
3704The UUCP node name (from the uname system call).
3705.ip $l\(dg
3706(Obsolete; use UnixFromLine option instead.)
3707The format of the UNIX from line.
3708Unless you have changed the UNIX mailbox format,
3709you should not change the default,
3710which is
3711.q "From $g $d" .
3712.ip $m
3713The domain part of the \fIgethostname\fP return value.
3714Under normal circumstances,
3715.b $j
3716is equivalent to
3717.b $w.$m .
3718.ip $n\(dg
3719The name of the daemon (for error messages).
3720Defaults to
3721.q MAILER-DAEMON .
3722.ip $o\(dg
3723(Obsolete: use OperatorChars option instead.)
3724The set of \*(lqoperators\*(rq in addresses.
3725A list of characters
3726which will be considered tokens
3727and which will separate tokens
3728when doing parsing.
3729For example, if
3730.q @
3731were in the
3732.b $o
3733macro, then the input
3734.q a@b
3735would be scanned as three tokens:
3736.q a,
3737.q @,
3738and
3739.q b.
3740Defaults to
3741.q ".:@[]" ,
3742which is the minimum set necessary to do RFC 822 parsing;
3743a richer set of operators is
3744.q ".:%@!/[]" ,
3745which adds support for UUCP, the %-hack, and X.400 addresses.
3746.ip $p
3747Sendmail's process id.
3748.ip $q\(dg
3749Default format of sender address.
3750The
3751.b $q
3752macro specifies how an address should appear in a message
3753when it is defaulted.
3754Defaults to
3755.q "<$g>" .
3756It is commonly redefined to be
3757.q "$?x$x <$g>$|$g$."
3758or
3759.q "$g$?x ($x)$." ,
3760corresponding to the following two formats:
3761.(b
3762Eric Allman <eric@CS.Berkeley.EDU>
3763eric@CS.Berkeley.EDU (Eric Allman)
3764.)b
3765.i Sendmail
3766properly quotes names that have special characters
3767if the first form is used.
3768.ip $r
3769Protocol used to receive the message.
3770Set from the
3771.b \-p
3772command line flag or by the SMTP server code.
3773.ip $s
3774Sender's host name.
3775Set from the
3776.b \-p
3777command line flag or by the SMTP server code.
3778.ip $t
3779A numeric representation of the current time.
3780.ip $u
3781The recipient user.
3782.ip $v
3783The version number of the
3784.i sendmail
3785binary.
3786.ip $w\(dd
3787The hostname of this site.
3788This is the root name of this host (but see below for caveats).
3789.ip $x
3790The full name of the sender.
3791.ip $z
3792The home directory of the recipient.
3793.ip $_
3794The validated sender address.
3795.ip ${bodytype}
3796The message body type
3797(7BIT or 8BITMIME),
3798as determined from the envelope.
3799.ip ${client_addr}
3800The IP address of the SMTP client.
3801Defined in the SMTP server only.
3802.ip ${client_name}
3803The host name of the SMTP client.
3804This may be the client's bracketed IP address
3805in the form [ nnn.nnn.nnn.nnn ] if the client's
3806IP address is not resolvable.
3807Defined in the SMTP server only.
3808.ip ${client_port}
3809The port number of the SMTP client.
3810Defined in the SMTP server only.
3811.ip ${envid}
3812The envelope id passed to sendmail as part of the envelope.
3813.ip ${opMode}
3814The current operation mode (from the
3815.b \-b
3816flag).
3817.ip ${deliveryMode}
3818The current delivery mode
3819(from the
3820.b DeliveryMode
3821option).
3822.pp
3823There are three types of dates that can be used.
3824The
3825.b $a
3826and
3827.b $b
3828macros are in RFC 822 format;
3829.b $a
3830is the time as extracted from the
3831.q Date:
3832line of the message
3833(if there was one),
3834and
3835.b $b
3836is the current date and time
3837(used for postmarks).
3838If no
3839.q Date:
3840line is found in the incoming message,
3841.b $a
3842is set to the current time also.
3843The
3844.b $d
3845macro is equivalent to the
3846.b $b
3847macro in UNIX
3848(ctime)
3849format.
3850.pp
3851The macros
3852.b $w ,
3853.b $j ,
3854and
3855.b $m
3856are set to the identity of this host.
3857.i Sendmail
3858tries to find the fully qualified name of the host
3859if at all possible;
3860it does this by calling
3861.i gethostname (2)
3862to get the current hostname
3863and then passing that to
3864.i gethostbyname (3)
3865which is supposed to return the canonical version of that host name.\**
3866.(f
3867\**For example, on some systems
3868.i gethostname
3869might return
3870.q foo
3871which would be mapped to
3872.q foo.bar.com
3873by
3874.i gethostbyname .
3875.)f
3876Assuming this is successful,
3877.b $j
3878is set to the fully qualified name
3879and
3880.b $m
3881is set to the domain part of the name
3882(everything after the first dot).
3883The
3884.b $w
3885macro is set to the first word
3886(everything before the first dot)
3887if you have a level 5 or higher configuration file;
3888otherwise, it is set to the same value as
3889.b $j .
3890If the canonification is not successful,
3891it is imperative that the config file set
3892.b $j
3893to the fully qualified domain name\**.
3894.(f
3895\**Older versions of sendmail didn't pre-define
3896.b $j
3897at all, so up until 8.6,
3898config files
3899.i always
3900had to define
3901.b $j .
3902.)f
3903.pp
3904The
3905.b $f
3906macro is the id of the sender
3907as originally determined;
3908when mailing to a specific host
3909the
3910.b $g
3911macro is set to the address of the sender
3912.ul
3913relative to the recipient.
3914For example,
3915if I send to
3916.q bollard@matisse.CS.Berkeley.EDU
3917from the machine
3918.q vangogh.CS.Berkeley.EDU
3919the
3920.b $f
3921macro will be
3922.q eric
3923and the
3924.b $g
3925macro will be
3926.q eric@vangogh.CS.Berkeley.EDU.
3927.pp
3928The
3929.b $x
3930macro is set to the full name of the sender.
3931This can be determined in several ways.
3932It can be passed as flag to
3933.i sendmail .
3934It can be defined in the
3935.sm NAME
3936environment variable.
3937The third choice is the value of the
3938.q Full-Name:
3939line in the header if it exists,
3940and the fourth choice is the comment field
3941of a
3942.q From:
3943line.
3944If all of these fail,
3945and if the message is being originated locally,
3946the full name is looked up in the
3947.i /etc/passwd
3948file.
3949.pp
3950When sending,
3951the
3952.b $h ,
3953.b $u ,
3954and
3955.b $z
3956macros get set to the host, user, and home directory
3957(if local)
3958of the recipient.
3959The first two are set from the
3960.b $@
3961and
3962.b $:
3963part of the rewriting rules, respectively.
3964.pp
3965The
3966.b $p
3967and
3968.b $t
3969macros are used to create unique strings
3970(e.g., for the
3971.q Message-Id:
3972field).
3973The
3974.b $i
3975macro is set to the queue id on this host;
3976if put into the timestamp line
3977it can be extremely useful for tracking messages.
3978The
3979.b $v
3980macro is set to be the version number of
3981.i sendmail ;
3982this is normally put in timestamps
3983and has been proven extremely useful for debugging.
3984.pp
3985The
3986.b $c
3987field is set to the
3988.q "hop count,"
3989i.e., the number of times this message has been processed.
3990This can be determined
3991by the
3992.b \-h
3993flag on the command line
3994or by counting the timestamps in the message.
3995.pp
3996The
3997.b $r
3998and
3999.b $s
4000fields are set to the protocol used to communicate with
4001.i sendmail
4002and the sending hostname.
4003They can be set together using the
4004.b \-p
4005command line flag or separately using the
4006.b \-M
4007or
4008.b \-oM
4009flags.
4010.pp
4011The
4012.b $_
4013is set to a validated sender host name.
4014If the sender is running an RFC 1413 compliant IDENT server
4015and the receiver has the IDENT protocol turned on,
4016it will include the user name on that host.
4017.pp
4018The
4019.b ${client_name} ,
4020.b ${client_addr} ,
4021and
4022.b ${client_port}
4023macros
4024are set to the name, address, and port number of the SMTP client
4025who is invoking
4026.i sendmail
4027as a server.
4028These can be used in the
4029.i check_*
4030rulesets (using the
4031.b $&
4032deferred evaluation form, of course!).
4033.sh 2 "C and F \*- Define Classes"
4034.pp
4035Classes of phrases may be defined
4036to match on the left hand side of rewriting rules,
4037where a
4038.q phrase
4039is a sequence of characters that does not contain space characters.
4040For example
4041a class of all local names for this site
4042might be created
4043so that attempts to send to oneself
4044can be eliminated.
4045These can either be defined directly in the configuration file
4046or read in from another file.
4047Classes are named as a single letter or a word in {braces}.
4048Class names beginning with lower case letters
4049and special characters are reserved for system use.
4050Classes defined in config files may be given names
4051from the set of upper case letters for short names
4052or beginning with an upper case letter for long names.
4053.pp
4054The syntax is:
4055.(b F
4056.b C \c
4057.i c\|phrase1
4058.i phrase2...
4059.br
4060.b F \c
4061.i c\|file
4062.)b
4063The first form defines the class
4064.i c
4065to match any of the named words.
4066It is permissible to split them among multiple lines;
4067for example, the two forms:
4068.(b
4069CHmonet ucbmonet
4070.)b
4071and
4072.(b
4073CHmonet
4074CHucbmonet
4075.)b
4076are equivalent.
4077The ``F'' form
4078reads the elements of the class
4079.i c
4080from the named
4081.i file .
4082.pp
4083Elements of classes can be accessed in rules using
4084.b $=
4085or
4086.b $~ .
4087The
4088.b $~
4089(match entries not in class)
4090only matches a single word;
4091multi-word entries in the class are ignored in this context.
4092.pp
4093Some classes have internal meaning to
4094.i sendmail :
4095.nr ii 0.5i
4096.\".ip $=b
4097.\"A set of Content-Types that will not have the newline character
4098.\"translated to CR-LF before encoding into base64 MIME.
4099.\"The class can have major times
4100.\"(e.g.,
4101.\".q image )
4102.\"or full types
4103.\"(such as
4104.\".q application/octet-stream ).
4105.\"The class is initialized with
4106.\".q application/octet-stream ,
4107.\".q image ,
4108.\".q audio ,
4109.\"and
4110.\".q video .
4111.ip $=e
4112contains the Content-Transfer-Encodings that can be 8\(->7 bit encoded.
4113It is predefined to contain
4114.q 7bit ,
4115.q 8bit ,
4116and
4117.q binary .
4118.ip $=k
4119set to be the same as
4120.b $k ,
4121that is, the UUCP node name.
4122.ip $=m
4123set to the set of domains by which this host is known,
4124initially just
4125.b $m .
4126.ip $=n
4127can be set to the set of MIME body types
4128that can never be eight to seven bit encoded.
4129It defaults to
4130.q multipart/signed .
4131Message types
4132.q message/*
4133and
4134.q multipart/*
4135are never encoded directly.
4136Multipart messages are always handled recursively.
4137The handling of message/* messages
4138are controlled by class
4139.b $=s .
4140.ip $=q
4141A set of Content-Types that will never be encoded as base64
4142(if they have to be encoded, they will be encoded as quoted-printable).
4143It can have primary types
4144(e.g.,
4145.q text )
4146or full types
4147(such as
4148.q text/plain ).
4149The class is initialized to have
4150.q text/plain
4151only.
4152.ip $=s
4153contains the set of subtypes of message that can be treated recursively.
4154By default it contains only
4155.q rfc822 .
4156Other
4157.q message/*
4158types cannot be 8\(->7 bit encoded.
4159If a message containing eight bit data is sent to a seven bit host,
4160and that message cannot be encoded into seven bits,
4161it will be stripped to 7 bits.
4162.ip $=t
4163set to the set of trusted users by the
4164.b T
4165configuration line.
4166If you want to read trusted users from a file, use
4167.b Ft \c
4168.i /file/name .
4169.ip $=w
4170set to be the set of all names
4171this host is known by.
4172This can be used to match local hostnames.
4173.pp
4174.i Sendmail
4175can be compiled to allow a
4176.i scanf (3)
4177string on the
4178.b F
4179line.
4180This lets you do simplistic parsing of text files.
4181For example, to read all the user names in your system
4182.i /etc/passwd
4183file into a class, use
4184.(b
4185FL/etc/passwd %[^:]
4186.)b
4187which reads every line up to the first colon.
4188.sh 2 "M \*- Define Mailer"
4189.pp
4190Programs and interfaces to mailers
4191are defined in this line.
4192The format is:
4193.(b F
4194.b M \c
4195.i name ,
4196{\c
4197.i field =\c
4198.i value \|}*
4199.)b
4200where
4201.i name
4202is the name of the mailer
4203(used internally only)
4204and the
4205.q field=name
4206pairs define attributes of the mailer.
4207Fields are:
4208.(b
4209.ta 1i
4210Path The pathname of the mailer
4211Flags Special flags for this mailer
4212Sender Rewriting set(s) for sender addresses
4213Recipient Rewriting set(s) for recipient addresses
4214Argv An argument vector to pass to this mailer
4215Eol The end-of-line string for this mailer
4216Maxsize The maximum message length to this mailer
4217Linelimit The maximum line length in the message body
4218Directory The working directory for the mailer
4219Userid The default user and group id to run as
4220Nice The nice(2) increment for the mailer
4221Charset The default character set for 8-bit characters
4222Type The MTS type information (used for error messages)
4223.)b
4224Only the first character of the field name is checked.
4225.pp
4226The following flags may be set in the mailer description.
4227Any other flags may be used freely
4228to conditionally assign headers to messages
4229destined for particular mailers.
4230Flags marked with \(dg
4231are not interpreted by the
4232.i sendmail
4233binary;
4234these are the conventionally used to correlate to the flags portion
4235of the
4236.b H
4237line.
4238Flags marked with \(dd
4239apply to the mailers for the sender address
4240rather than the usual recipient mailers.
4241.nr ii 4n
4242.ip a
4243Run Extended SMTP (ESMTP) protocol (defined in RFCs 1869, 1652, and 1870).
4244This flag defaults on if the SMTP greeting message includes the word
4245.q ESMTP .
4246.ip A
4247Look up the user part of the address in the alias database.
4248Normally this is only set for local mailers.
4249.ip b
4250Force a blank line on the end of a message.
4251This is intended to work around some stupid versions of
4252/bin/mail
4253that require a blank line, but do not provide it themselves.
4254It would not normally be used on network mail.
4255.ip c
4256Do not include comments in addresses.
4257This should only be used if you have to work around
4258a remote mailer that gets confused by comments.
4259This strips addresses of the form
4260.q "Phrase <address>"
4261or
4262.q "address (Comment)"
4263down to just
4264.q address .
4265.ip C\(dd
4266If mail is
4267.i received
4268from a mailer with this flag set,
4269any addresses in the header that do not have an at sign
4270(\c
4271.q @ )
4272after being rewritten by ruleset three
4273will have the
4274.q @domain
4275clause from the sender envelope address
4276tacked on.
4277This allows mail with headers of the form:
4278.(b
4279From: usera@hosta
4280To: userb@hostb, userc
4281.)b
4282to be rewritten as:
4283.(b
4284From: usera@hosta
4285To: userb@hostb, userc@hosta
4286.)b
4287automatically.
4288However, it doesn't really work reliably.
4289.ip d
4290Do not include angle brackets around route-address syntax addresses.
4291This is useful on mailers that are going to pass addresses to a shell
4292that might interpret angle brackets as I/O redirection.
4293.ip D\(dg
4294This mailer wants a
4295.q Date:
4296header line.
4297.ip e
4298This mailer is expensive to connect to,
4299so try to avoid connecting normally;
4300any necessary connection will occur during a queue run.
4301.ip E
4302Escape lines beginning with
4303.q From\0
4304in the message with a `>' sign.
4305.ip f
4306The mailer wants a
4307.b \-f
4308.i from
4309flag,
4310but only if this is a network forward operation
4311(i.e.,
4312the mailer will give an error
4313if the executing user
4314does not have special permissions).
4315.ip F\(dg
4316This mailer wants a
4317.q From:
4318header line.
4319.ip g
4320Normally,
4321.i sendmail
4322sends internally generated email (e.g., error messages)
4323using the null return address
4324as required by RFC 1123.
4325However, some mailers don't accept a null return address.
4326If necessary,
4327you can set the
4328.b g
4329flag to prevent
4330.i sendmail
4331from obeying the standards;
4332error messages will be sent as from the MAILER-DAEMON
4333(actually, the value of the
4334.b $n
4335macro).
4336.ip h
4337Upper case should be preserved in host names
4338for this mailer.
4339.ip i
4340Do User Database rewriting on envelope sender address.
4341.ip I
4342This mailer will be speaking SMTP
4343to another
4344.i sendmail
4345\*-
4346as such it can use special protocol features.
4347This option is not required
4348(i.e.,
4349if this option is omitted the transmission will still operate successfully,
4350although perhaps not as efficiently as possible).
4351.ip j
4352Do User Database rewriting on recipients as well as senders.
4353.ip k
4354Normally when
4355.i sendmail
4356connects to a host via SMTP,
4357it checks to make sure that this isn't accidently the same host name
4358as might happen if
4359.i sendmail
4360is misconfigured or if a long-haul network interface is set in loopback mode.
4361This flag disables the loopback check.
4362It should only be used under very unusual circumstances.
4363.ip K
4364Currently unimplemented.
4365Reserved for chunking.
4366.ip l
4367This mailer is local
4368(i.e.,
4369final delivery will be performed).
4370.ip L
4371Limit the line lengths as specified in RFC821.
4372This deprecated option should be replaced by the
4373.b L=
4374mail declaration.
4375For historic reasons, the
4376.b L
4377flag also sets the
4378.b 7
4379flag.
4380.ip m
4381This mailer can send to multiple users
4382on the same host
4383in one transaction.
4384When a
4385.b $u
4386macro occurs in the
4387.i argv
4388part of the mailer definition,
4389that field will be repeated as necessary
4390for all qualifying users.
4391.ip M\(dg
4392This mailer wants a
4393.q Message-Id:
4394header line.
4395.ip n
4396Do not insert a UNIX-style
4397.q From
4398line on the front of the message.
4399.ip o
4400Always run as the owner of the recipient mailbox.
4401Normally
4402.i sendmail
4403runs as the sender for locally generated mail
4404or as
4405.q daemon
4406(actually, the user specified in the
4407.b u
4408option)
4409when delivering network mail.
4410The normal behaviour is required by most local mailers,
4411which will not allow the envelope sender address
4412to be set unless the mailer is running as daemon.
4413This flag is ignored if the
4414.b S
4415flag is set.
4416.ip p
4417Use the route-addr style reverse-path in the SMTP
4418.q "MAIL FROM:"
4419command
4420rather than just the return address;
4421although this is required in RFC821 section 3.1,
4422many hosts do not process reverse-paths properly.
4423Reverse-paths are officially discouraged by RFC 1123.
4424.ip P\(dg
4425This mailer wants a
4426.q Return-Path:
4427line.
4428.ip q
4429When an address that resolves to this mailer is verified
4430(SMTP VRFY command),
4431generate 250 responses instead of 252 responses.
4432This will imply that the address is local.
4433.ip r
4434Same as
4435.b f ,
4436but sends a
4437.b \-r
4438flag.
4439.ip R
4440Open SMTP connections from a
4441.q secure
4442port.
4443Secure ports aren't
4444(secure, that is)
4445except on UNIX machines,
4446so it is unclear that this adds anything.
4447.ip s
4448Strip quote characters (" and \e) off of the address
4449before calling the mailer.
4450.ip S
4451Don't reset the userid
4452before calling the mailer.
4453This would be used in a secure environment
4454where
4455.i sendmail
4456ran as root.
4457This could be used to avoid forged addresses.
4458If the
4459.b U=
4460field is also specified,
4461this flag causes the user id to always be set to that user and group
4462(instead of leaving it as root).
4463.ip u
4464Upper case should be preserved in user names
4465for this mailer.
4466.ip U
4467This mailer wants UUCP-style
4468.q From
4469lines with the ugly
4470.q "remote from <host>"
4471on the end.
4472.ip w
4473The user must have a valid account on this machine,
4474i.e.,
4475getpwnam
4476must succeed.
4477If not,
4478the mail is bounced.
4479This is required to get
4480.q \&.forward
4481capability.
4482.ip x\(dg
4483This mailer wants a
4484.q Full-Name:
4485header line.
4486.ip X
4487This mailer want to use the hidden dot algorithm
4488as specified in RFC821;
4489basically,
4490any line beginning with a dot
4491will have an extra dot prepended
4492(to be stripped at the other end).
4493This insures that lines in the message containing a dot
4494will not terminate the message prematurely.
4495.ip z
4496Run Local Mail Transfer Protocol (LMTP)
4497between
4498.i sendmail
4499and the local mailer.
4500This is a variant on SMTP
4501defined in RFC 2033
4502that is specifically designed for delivery to a local mailbox.
4503.ip 0
4504Don't look up MX records for hosts sent via SMTP.
4505.ip 3
4506Extend the list of characters converted to =XX notation
4507when converting to Quoted-Printable
4508to include those that don't map cleanly between ASCII and EBCDIC.
4509Useful if you have IBM mainframes on site.
4510.ip 5
4511If no aliases are found for this address,
4512pass the address through ruleset 5 for possible alternate resolution.
4513This is intended to forward the mail to an alternate delivery spot.
4514.ip 7
4515Strip all output to seven bits.
4516This is the default if the
4517.b L
4518flag is set.
4519Note that clearing this option is not
4520sufficient to get full eight bit data passed through
4521.i sendmail .
4522If the
4523.b 7
4524option is set, this is essentially always set,
4525since the eighth bit was stripped on input.
4526Note that this option will only impact messages
4527that didn't have 8\(->7 bit MIME conversions performed.
4528.ip 8
4529If set,
4530it is acceptable to send eight bit data to this mailer;
4531the usual attempt to do 8\(->7 bit MIME conversions will be bypassed.
4532.ip 9
4533If set,
4534do
4535.i limited
45367\(->8 bit MIME conversions.
4537These conversions are limited to text/plain data.
4538.ip :
4539Check addresses to see if they begin
4540.q :include: ;
4541if they do, convert them to the
4542.q *include*
4543mailer.
4544.ip |
4545Check addresses to see if they begin with a `|';
4546if they do, convert them to the
4547.q prog
4548mailer.
4549.ip /
4550Check addresses to see if they begin with a `/';
4551if they do, convert them to the
4552.q *file*
4553mailer.
4554.ip @
4555Look up addresses in the user database.
4556.pp
4557Configuration files prior to level 6
4558assume the `A', `w', `5', `:', `|', `/', and `@' options
4559on the mailer named
4560.q local .
4561.pp
4562The mailer with the special name
4563.q error
4564can be used to generate a user error.
4565The (optional) host field is an exit status to be returned,
4566and the user field is a message to be printed.
4567The exit status may be numeric or one of the values
4568USAGE, NOUSER, NOHOST, UNAVAILABLE, SOFTWARE, TEMPFAIL, PROTOCOL, or CONFIG
4569to return the corresponding EX_ exit code,
4570or an enhanced error code as described in RFC 1893,
4571.ul
4572Enhanced Mail System Status Codes.
4573For example, the entry:
4574.(b
4575$#error $@ NOHOST $: Host unknown in this domain
4576.)b
4577on the RHS of a rule
4578will cause the specified error to be generated
4579and the
4580.q "Host unknown"
4581exit status to be returned
4582if the LHS matches.
4583This mailer is only functional in rulesets 0, 5,
4584or one of the check_* rulesets.
4585.pp
4586The mailer with the special name
4587.q discard
4588causes any mail sent to it to be discarded
4589but otherwise treated as though it were successfully delivered.
4590.pp
4591The mailer named
4592.q local
4593.i must
4594be defined in every configuration file.
4595This is used to deliver local mail,
4596and is treated specially in several ways.
4597Additionally, three other mailers named
4598.q prog ,
4599.q *file* ,
4600and
4601.q *include*
4602may be defined to tune the delivery of messages to programs,
4603files,
4604and :include: lists respectively.
4605They default to:
4606.(b
4607Mprog, P=/bin/sh, F=lsoDq9, T=DNS/RFC822/X-Unix, A=sh \-c $u
4608M*file*, P=[FILE], F=lsDFMPEouq9, T=DNS/RFC822/X-Unix, A=FILE $u
4609M*include*, P=/dev/null, F=su, A=INCLUDE $u
4610.)b
4611.pp
4612The Sender and Recipient rewriting sets
4613may either be a simple ruleset id
4614or may be two ids separated by a slash;
4615if so, the first rewriting set is applied to envelope
4616addresses
4617and the second is applied to headers.
4618Setting any value zero disables corresponding mailer-specific rewriting.
4619.pp
4620The Directory
4621is actually a colon-separated path of directories to try.
4622For example, the definition
4623.q D=$z:/
4624first tries to execute in the recipient's home directory;
4625if that is not available,
4626it tries to execute in the root of the filesystem.
4627This is intended to be used only on the
4628.q prog
4629mailer,
4630since some shells (such as
4631.i csh )
4632refuse to execute if they cannot read the home directory.
4633Since the queue directory is not normally readable by unprivileged users
4634.i csh
4635scripts as recipients can fail.
4636.pp
4637The Userid
4638specifies the default user and group id to run as,
4639overriding the
4640.b DefaultUser
4641option (q.v.).
4642If the
4643.b S
4644mailer flag is also specified,
4645this is the user and group to run as in all circumstances.
4646This may be given as
4647.i user:group
4648to set both the user and group id;
4649either may be an integer or a symbolic name to be looked up
4650in the
4651.i passwd
4652and
4653.i group
4654files respectively.
4655If only a symbolic user name is specified,
4656the group id in the
4657.i passwd
4658file for that user is used as the group id.
4659.pp
4660The Charset field
4661is used when converting a message to MIME;
4662this is the character set used in the
4663Content-Type: header.
4664If this is not set, the
4665.b DefaultCharset
4666option is used,
4667and if that is not set, the value
4668.q unknown-8bit
4669is used.
4670.b WARNING:
4671this field applies to the sender's mailer,
4672not the recipient's mailer.
4673For example, if the envelope sender address
4674lists an address on the local network
4675and the recipient is on an external network,
4676the character set will be set from the Charset= field
4677for the local network mailer,
4678not that of the external network mailer.
4679.pp
4680The Type= field
4681sets the type information
4682used in MIME error messages
4683as defined by
4684RFC 1894.
4685It is actually three values separated by slashes:
4686the MTA-type (that is, the description of how hosts are named),
4687the address type (the description of e-mail addresses),
4688and the diagnostic type (the description of error diagnostic codes).
4689Each of these must be a registered value
4690or begin with
4691.q X\- .
4692The default is
4693.q dns/rfc822/smtp .
4694.sh 2 "H \*- Define Header"
4695.pp
4696The format of the header lines that
4697.i sendmail
4698inserts into the message
4699are defined by the
4700.b H
4701line.
4702The syntax of this line is:
4703.(b F
4704.b H [\c
4705.b ? \c
4706.i mflags \c
4707.b ? ]\c
4708.i hname \c
4709.b :
4710.i htemplate
4711.)b
4712Continuation lines in this spec
4713are reflected directly into the outgoing message.
4714The
4715.i htemplate
4716is macro-expanded before insertion into the message.
4717If the
4718.i mflags
4719(surrounded by question marks)
4720are specified,
4721at least one of the specified flags
4722must be stated in the mailer definition
4723for this header to be automatically output.
4724If one of these headers is in the input
4725it is reflected to the output
4726regardless of these flags.
4727.pp
4728Some headers have special semantics
4729that will be described later.
4730.pp
4731A secondary syntax allows validation of headers as they are being read.
4732To enable validation, use:
4733.(b
4734.b H \c
4735.i Header \c
4736.b ": $>" \c
4737.i Ruleset
4738.)b
4739The indicated
4740.i Ruleset
4741is called for the specified
4742.i Header ,
4743and can return
4744.b $#error
4745to reject the message or
4746.b $#discard
4747to discard the message
4748(as with the other
4749.b check_ *
4750rulesets).
4751The header is treated as a structured field,
4752that is,
4753comments (in parentheses) are deleted before processing.
4754.pp
4755For example, the configuration lines:
4756.(b
4757HMessage-Id: $>CheckMessageId
4758
4759SCheckMessageId
4760R< $+ @ $+ > $@ OK
4761R$* $#error $: Illegal Message-Id header
4762.)b
4763would refuse any message that had a Message-Id: header of any of the
4764following forms:
4765.(b
4766Message-Id: <>
4767Message-Id: some text
4768Message-Id: <legal text@domain> extra crud
4769.)b
4770.sh 2 "O \*- Set Option"
4771.pp
4772There are a number of
4773global
4774options that
4775can be set from a configuration file.
4776Options are represented by full words;
4777some are also representable as single characters
4778for back compatibility.
4779The syntax of this line is:
4780.(b F
4781.b O \0
4782.i option \c
4783.b = \c
4784.i value
4785.)b
4786This sets option
4787.i option
4788to be
4789.i value .
4790Note that there
4791.i must
4792be a space between the letter `O' and the name of the option.
4793An older version is:
4794.(b F
4795.b O \c
4796.i o\|value
4797.)b
4798where the option
4799.i o
4800is a single character.
4801Depending on the option,
4802.i value
4803may be a string, an integer,
4804a boolean
4805(with legal values
4806.q t ,
4807.q T ,
4808.q f ,
4809or
4810.q F ;
4811the default is TRUE),
4812or
4813a time interval.
4814.pp
4815The options supported (with the old, one character names in brackets) are:
4816.nr ii 1i
4817.ip "AliasFile=\fIspec, spec, ...\fP"
4818[A]
4819Specify possible alias file(s).
4820Each
4821.i spec
4822should be in the format
4823``\c
4824.i class \c
4825.b :
4826.i file ''
4827where
4828.i class \c
4829.b :
4830is optional and defaults to ``implicit''.
4831Depending on how
4832.i sendmail
4833is compiled, valid classes are
4834.q implicit
4835(search through a compiled-in list of alias file types,
4836for back compatibility),
4837.q hash
4838(if
4839.sm NEWDB
4840is specified),
4841.q dbm
4842(if
4843.sm NDBM
4844is specified),
4845.q stab
4846(internal symbol table \*- not normally used
4847unless you have no other database lookup),
4848or
4849.q nis
4850(if
4851.sm NIS
4852is specified).
4853If a list of
4854.i spec s
4855are provided,
4856.i sendmail
4857searches them in order.
4858.ip AliasWait=\fItimeout\fP
4859[a]
4860If set,
4861wait up to
4862.i timeout
4863(units default to minutes)
4864for an
4865.q @:@
4866entry to exist in the alias database
4867before starting up.
4868If it does not appear in the
4869.i timeout
4870interval
4871rebuild the database
4872(if the
4873.b AutoRebuildAliases
4874option is also set)
4875or issue a warning.
4876.ip AllowBogusHELO
4877[no short name]
4878If set, allow HELO SMTP commands that don't include a host name.
4879Setting this violates RFC 1123 section 5.2.5,
4880but is necessary to interoperate with several SMTP clients.
4881If there is a value, it is still checked for legitimacy.
4882.ip AutoRebuildAliases
4883[D]
4884If set,
4885rebuild the alias database if necessary and possible.
4886If this option is not set,
4887.i sendmail
4888will never rebuild the alias database
4889unless explicitly requested
4890using
4891.b \-bi .
4892Not recommended \(em can cause thrashing.
4893.ip BlankSub=\fIc\fP
4894[B]
4895Set the blank substitution character to
4896.i c .
4897Unquoted spaces in addresses are replaced by this character.
4898Defaults to space (i.e., no change is made).
4899.ip CheckAliases
4900[n]
4901Validate the RHS of aliases when rebuilding the alias database.
4902.ip CheckpointInterval=\fIN\fP
4903[C]
4904Checkpoints the queue every
4905.i N
4906(default 10)
4907addresses sent.
4908If your system crashes during delivery to a large list,
4909this prevents retransmission to any but the last
4910.I N
4911recipients.
4912.ip ClassFactor=\fIfact\fP
4913[z]
4914The indicated
4915.i fact or
4916is multiplied by the message class
4917(determined by the Precedence: field in the user header
4918and the
4919.b P
4920lines in the configuration file)
4921and subtracted from the priority.
4922Thus, messages with a higher Priority: will be favored.
4923Defaults to 1800.
4924.ip ColonOkInAddr
4925[no short name]
4926If set, colons are acceptable in e-mail addresses
4927(e.g.,
4928.q host:user ).
4929If not set, colons indicate the beginning of a RFC 822 group construct
4930(\c
4931.q "groupname: member1, member2, ... memberN;" ).
4932Doubled colons are always acceptable
4933(\c
4934.q nodename::user )
4935and proper route-addr nesting is understood
4936(\c
4937.q <@relay:user@host> ).
4938Furthermore, this option defaults on if the configuration version level
4939is less than 6 (for back compatibility).
4940However, it must be off for full compatibility with RFC 822.
4941.ip ConnectionCacheSize=\fIN\fP
4942[k]
4943The maximum number of open connections that will be cached at a time.
4944The default is one.
4945This delays closing the current connection until
4946either this invocation of
4947.i sendmail
4948needs to connect to another host
4949or it terminates.
4950Setting it to zero defaults to the old behavior,
4951that is, connections are closed immediately.
4952Since this consumes file descriptors,
4953the connection cache should be kept small:
49544 is probably a practical maximum.
4955.ip ConnectionCacheTimeout=\fItimeout\fP
4956[K]
4957The maximum amount of time a cached connection will be permitted to idle
4958without activity.
4959If this time is exceeded,
4960the connection is immediately closed.
4961This value should be small (on the order of ten minutes).
4962Before
4963.i sendmail
4964uses a cached connection,
4965it always sends a RSET command
4966to check the connection;
4967if this fails, it reopens the connection.
4968This keeps your end from failing if the other end times out.
4969The point of this option is to be a good network neighbor
4970and avoid using up excessive resources
4971on the other end.
4972The default is five minutes.
4973.ip ConnectionRateThrottle=\fIN\fP
4974[no short name]
4975If set to a positive value,
4976allow no more than
4977.i N
4978incoming daemon connections in a one second period.
4979This is intended to flatten out peaks
4980and allow the load average checking to cut in.
4981Defaults to zero (no limits).
4982.ip DaemonPortOptions=\fIoptions\fP
4983[O]
4984Set server SMTP options.
4985The options are
4986.i key=value
4987pairs.
4988Known keys are:
4989.(b
4990.ta 1i
4991Port Name/number of listening port (defaults to "smtp")
4992Addr Address mask (defaults INADDR_ANY)
4993Family Address family (defaults to INET)
4994Listen Size of listen queue (defaults to 10)
4995SndBufSize Size of TCP send buffer
4996RcvBufSize Size of TCP receive buffer
4997.)b
4998The
4999.i Addr ess
5000mask may be a numeric address in dot notation
5001or a network name.
5002.ip DefaultCharSet=\fIcharset\fP
5003[no short name]
5004When a message that has 8-bit characters but is not in MIME format
5005is converted to MIME
5006(see the EightBitMode option)
5007a character set must be included in the Content-Type: header.
5008This character set is normally set from the Charset= field
5009of the mailer descriptor.
5010If that is not set, the value of this option is used.
5011If this option is not set, the value
5012.q unknown-8bit
5013is used.
5014.ip DefaultUser=\fIuser:group\fP
5015[u]
5016Set the default userid for mailers to
5017.i user:group .
5018If
5019.i group
5020is omitted and
5021.i user
5022is a user name
5023(as opposed to a numeric user id)
5024the default group listed in the /etc/passwd file for that user is used
5025as the default group.
5026Both
5027.i user
5028and
5029.i group
5030may be numeric.
5031Mailers without the
5032.i S
5033flag in the mailer definition
5034will run as this user.
5035Defaults to 1:1.
5036The value can also be given as a symbolic user name.\**
5037.(f
5038\**The old
5039.b g
5040option has been combined into the
5041.b DefaultUser
5042option.
5043.)f
5044.ip DeliveryMode=\fIx\fP
5045[d]
5046Deliver in mode
5047.i x .
5048Legal modes are:
5049.(b
5050.ta 4n
5051i Deliver interactively (synchronously)
5052b Deliver in background (asynchronously)
5053q Just queue the message (deliver during queue run)
5054d Defer delivery and all map lookups (deliver during queue run)
5055.)b
5056Defaults to ``b'' if no option is specified,
5057``i'' if it is specified but given no argument
5058(i.e., ``Od'' is equivalent to ``Odi'').
5059The
5060.b \-v
5061command line flag sets this to
5062.b i .
5063.ip DialDelay=\fIsleeptime\fP
5064[no short name]
5065Dial-on-demand network connections can see timeouts
5066if a connection is opened before the call is set up.
5067If this is set to an interval and a connection times out
5068on the first connection being attempted
5069.i sendmail
5070will sleep for this amount of time and try again.
5071This should give your system time to establish the connection
5072to your service provider.
5073Units default to seconds, so
5074.q DialDelay=5
5075uses a five second delay.
5076Defaults to zero
5077(no retry).
5078.ip DontBlameSendmail=\fIoption,option,...\fP
5079[no short name]
5080In order to avoid possible cracking attempts
5081caused by world- and group-writable files and directories,
5082.i sendmail
5083does paranoid checking when opening most of its support files.
5084If for some reason you absolutely must run with,
5085for example,
5086a group-writable
5087.i /etc
5088directory,
5089then you will have to turn off this checking
5090(at the cost of making your system more vulnerable to attack).
5091The arguments are individual options that turn off checking:
5092.(b
5093Safe
5094AssumeSafeChown
5095ClassFileInUnsafeDirPath
5096ErrorHeaderInUnsafeDirPath
5097FileDeliveryToHardLink
5098FileDeliveryToSymLink
5099ForwardFileInUnsafeDirPath
5100ForwardFileInUnsafeDirPathSafe
5101ForwardFileIngroupWritableDirPath
5102GroupWritableAliasFile
5103GroupWritableDirPathSafe
5104GroupWritableForwardFileSafe
5105GroupWritableIncludeFileSafe
5106HelpFileinUnsafeDirPath
5107IncludeFileInUnsafeDirPath
5108IncludeFileInUnsafeDirPathSafe
5109IncludeFileIngroupWritableDirPath
5110LinkedAliasFileInWritableDir
5111LinkedClassFileInWritableDir
5112LinkedForwardFileInWritableDir
5113LinkedIncludeFileInWritableDir
5114LinkedMapInWritableDir
5115LinkedServiceSwitchFileInWritableDir
5116MapInUnsafeDirPath
5117RunProgramInUnsafeDirPath
5118RunWritableProgram
5119WorldWritableAliasFile
5120WriteMapToHardLink
5121WriteMapToSymLink
5122WriteStatsToHardLink
5123WriteStatsToSymLink
5124.)b
5125.b Safe
5126is the default.
5127The details of these flags are described above.
5128.\"XXX should have more here!!! XXX
5129.b "Use of this option is not recommended."
5130.ip DontExpandCnames
5131[no short name]
5132The standards say that all host addresses used in a mail message
5133must be fully canonical.
5134For example, if your host is named
5135.q Cruft.Foo.ORG
5136and also has an alias of
5137.q FTP.Foo.ORG ,
5138the former name must be used at all times.
5139This is enforced during host name canonification
5140($[ ... $] lookups).
5141If this option is set, the protocols are ignored and the
5142.q wrong
5143thing is done.
5144However, the IETF is moving toward changing this standard,
5145so the behaviour may become acceptable.
5146Please note that hosts downstream may still rewrite the address
5147to be the true canonical name however.
5148.ip DontInitGroups
5149[no short name]
5150If set,
5151.i sendmail
5152will avoid using the initgroups(3) call.
5153If you are running NIS,
5154this causes a sequential scan of the groups.byname map,
5155which can cause your NIS server to be badly overloaded in a large domain.
5156The cost of this is that the only group found for users
5157will be their primary group (the one in the password file),
5158which will make file access permissions somewhat more restrictive.
5159Has no effect on systems that don't have group lists.
5160.ip DontProbeInterfaces
5161[no short name]
5162.i Sendmail
5163normally finds the names of all interfaces active on your machine
5164when it starts up
5165and adds their name to the
5166.b $=w
5167class of known host aliases.
5168If you have a large number of virtual interfaces
5169or if your DNS inverse lookups are slow
5170this can be time consuming.
5171This option turns off that probing.
5172However, you will need to be certain to include all variant names
5173in the
5174.b $=w
5175class by some other mechanism.
5176.ip DontPruneRoutes
5177[R]
5178Normally,
5179.i sendmail
5180tries to eliminate any unnecessary explicit routes
5181when sending an error message
5182(as discussed in RFC 1123 \(sc 5.2.6).
5183For example,
5184when sending an error message to
5185.(b
5186<@known1,@known2,@known3:user@unknown>
5187.)b
5188.i sendmail
5189will strip off the
5190.q @known1,@known2
5191in order to make the route as direct as possible.
5192However, if the
5193.b R
5194option is set, this will be disabled,
5195and the mail will be sent to the first address in the route,
5196even if later addresses are known.
5197This may be useful if you are caught behind a firewall.
5198.ip DoubleBounceAddress=\fIerror-address\fP
5199[no short name]
5200If an error occurs when sending an error message,
5201send the error report
5202(termed a
5203.q "double bounce"
5204because it is an error
5205.q bounce
5206that occurs when trying to send another error
5207.q bounce )
5208to the indicated address.
5209If not set, defaults to
5210.q postmaster .
5211.ip EightBitMode=\fIaction\fP
5212[8]
5213Set handling of eight-bit data.
5214There are two kinds of eight-bit data:
5215that declared as such using the
5216.b BODY=8BITMIME
5217ESMTP declaration or the
5218.b \-B8BITMIME
5219command line flag,
5220and undeclared 8-bit data, that is,
5221input that just happens to be eight bits.
5222There are three basic operations that can happen:
5223undeclared 8-bit data can be automatically converted to 8BITMIME,
5224undeclared 8-bit data can be passed as-is without conversion to MIME
5225(``just send 8''),
5226and declared 8-bit data can be converted to 7-bits
5227for transmission to a non-8BITMIME mailer.
5228The possible
5229.i action s
5230are:
5231.(b
5232.\" r Reject undeclared 8-bit data;
5233.\" don't convert 8BITMIME\(->7BIT (``reject'')
5234 s Reject undeclared 8-bit data (``strict'')
5235.\" do convert 8BITMIME\(->7BIT (``strict'')
5236.\" c Convert undeclared 8-bit data to MIME;
5237.\" don't convert 8BITMIME\(->7BIT (``convert'')
5238 m Convert undeclared 8-bit data to MIME (``mime'')
5239.\" do convert 8BITMIME\(->7BIT (``mime'')
5240.\" j Pass undeclared 8-bit data;
5241.\" don't convert 8BITMIME\(->7BIT (``just send 8'')
5242 p Pass undeclared 8-bit data (``pass'')
5243.\" do convert 8BITMIME\(->7BIT (``pass'')
5244.\" a Adaptive algorithm: see below
5245.)b
5246.\"The adaptive algorithm is to accept 8-bit data,
5247.\"converting it to 8BITMIME only if the receiver understands that,
5248.\"otherwise just passing it as undeclared 8-bit data;
5249.\"8BITMIME\(->7BIT conversions are done.
5250In all cases properly declared 8BITMIME data will be converted to 7BIT
5251as needed.
5252.ip ErrorHeader=\fIfile-or-message\fP
5253[E]
5254Prepend error messages with the indicated message.
5255If it begins with a slash,
5256it is assumed to be the pathname of a file
5257containing a message (this is the recommended setting).
5258Otherwise, it is a literal message.
5259The error file might contain the name, email address, and/or phone number
5260of a local postmaster who could provide assistance
5261in to end users.
5262If the option is missing or null,
5263or if it names a file which does not exist or which is not readable,
5264no message is printed.
5265.ip ErrorMode=\fIx\fP
5266[e]
5267Dispose of errors using mode
5268.i x .
5269The values for
5270.i x
5271are:
5272.(b
5273p Print error messages (default)
5274q No messages, just give exit status
5275m Mail back errors
5276w Write back errors (mail if user not logged in)
5277e Mail back errors and give zero exit stat always
5278.)b
5279.ip FallbackMXhost=\fIfallbackhost\fP
5280[V]
5281If specified, the
5282.i fallbackhost
5283acts like a very low priority MX
5284on every host.
5285This is intended to be used by sites with poor network connectivity.
5286.ip ForkEachJob
5287[Y]
5288If set,
5289deliver each job that is run from the queue in a separate process.
5290Use this option if you are short of memory,
5291since the default tends to consume considerable amounts of memory
5292while the queue is being processed.
5293.ip ForwardPath=\fIpath\fP
5294[J]
5295Set the path for searching for users' .forward files.
5296The default is
5297.q $z/.forward .
5298Some sites that use the automounter may prefer to change this to
5299.q /var/forward/$u
5300to search a file with the same name as the user in a system directory.
5301It can also be set to a sequence of paths separated by colons;
5302.i sendmail
5303stops at the first file it can successfully and safely open.
5304For example,
5305.q /var/forward/$u:$z/.forward
5306will search first in /var/forward/\c
5307.i username
5308and then in
5309.i ~username /.forward
5310(but only if the first file does not exist).
5311.ip HelpFile=\fIfile\fP
5312[H]
5313Specify the help file
5314for SMTP.
5315.ip HoldExpensive
5316[c]
5317If an outgoing mailer is marked as being expensive,
5318don't connect immediately.
5319This requires that queueing be compiled in,
5320since it will depend on a queue run process to
5321actually send the mail.
5322.ip HostsFile=\fIpath\fP
5323[no short name]
5324The path to the hosts database,
5325normally
5326.q /etc/hosts .
5327This option is only consulted when sendmail
5328is canonifying addresses,
5329and then only when
5330.q files
5331is in the
5332.q hosts
5333service switch entry.
5334In particular, this file is
5335.i never
5336used when looking up host addresses;
5337that is under the control of the system
5338.i gethostbyname (3)
5339routine.
5340.ip HostStatusDirectory=\fIpath\fP
5341[no short name]
5342The location of the long term host status information.
5343When set,
5344information about the status of hosts
5345(e.g., host down or not accepting connections)
5346will be shared between all
5347.i sendmail
5348processes;
5349normally, this information is only held within a single queue run.
5350This option requires a connection cache of at least 1 to function.
5351If the option begins with a leading `/',
5352it is an absolute pathname;
5353otherwise,
5354it is relative to the mail queue directory.
5355A suggested value for sites desiring persistent host status is
5356.q \&.hoststat
5357(i.e., a subdirectory of the queue directory).
5358.ip IgnoreDots
5359[i]
5360Ignore dots in incoming messages.
5361This is always disabled (that is, dots are always accepted)
5362when reading SMTP mail.
5363.ip LogLevel=\fIn\fP
5364[L]
5365Set the log level to
5366.i n .
5367Defaults to 9.
5368.ip M\fIx\|value\fP
5369[no long version]
5370Set the macro
5371.i x
5372to
5373.i value .
5374This is intended only for use from the command line.
5375The
5376.b \-M
5377flag is preferred.
5378.ip MatchGECOS
5379[G]
5380Allow fuzzy matching on the GECOS field.
5381If this flag is set,
5382and the usual user name lookups fail
5383(that is, there is no alias with this name and a
5384.i getpwnam
5385fails),
5386sequentially search the password file
5387for a matching entry in the GECOS field.
5388This also requires that MATCHGECOS
5389be turned on during compilation.
5390This option is not recommended.
5391.ip MaxDaemonChildren=\fIN\fP
5392[no short name]
5393If set,
5394.i sendmail
5395will refuse connections when it has more than
5396.i N
5397children processing incoming mail.
5398This does not limit the number of outgoing connections.
5399If not set, there is no limit to the number of children --
5400that is, the system load averaging controls this.
5401.ip MaxHopCount=\fIN\fP
5402[h]
5403The maximum hop count.
5404Messages that have been processed more than
5405.i N
5406times are assumed to be in a loop and are rejected.
5407Defaults to 25.
5408.ip MaxHostStatAge=\fIage\fP
5409[no short name]
5410Not yet implemented.
5411This option specifies how long host status information will be retained.
5412For example, if a host is found to be down,
5413connections to that host will not be retried for this interval.
5414The units default to minutes.
5415.ip MaxMessageSize=\fIN\fP
5416[no short name]
5417Specify the maximum message size
5418to be advertised in the ESMTP EHLO response.
5419Messages larger than this will be rejected.
5420.ip MaxQueueRunSize=\fIN\fP
5421[no short name]
5422The maximum number of jobs that will be processed
5423in a single queue run.
5424If not set, there is no limit on the size.
5425If you have very large queues or a very short queue run interval
5426this could be unstable.
5427However, since the first
5428.i N
5429jobs in queue directory order are run (rather than the
5430.i N
5431highest priority jobs)
5432this should be set as high as possible to avoid
5433.q losing
5434jobs that happen to fall late in the queue directory.
5435.ip MaxRecipientsPerMessage=\fIN\fP
5436[no short name]
5437The maximum number of recipients that will be accepted per message
5438in an SMTP transaction.
5439Note: setting this too low can interfere with sending mail from
5440MUAs that use SMTP for initial submission.
5441If not set, there is no limit on the number of recipients per envelope.
5442.ip MeToo
5443[m]
5444Send to me too,
5445even if I am in an alias expansion.
5446.ip MinFreeBlocks=\fIN\fP
5447[b]
5448Insist on at least
5449.i N
5450blocks free on the filesystem that holds the queue files
5451before accepting email via SMTP.
5452If there is insufficient space
5453.i sendmail
5454gives a 452 response
5455to the MAIL command.
5456This invites the sender to try again later.
5457.ip MinQueueAge=\fPage\fP
5458[no short name]
5459Don't process any queued jobs
5460that have been in the queue less than the indicated time interval.
5461This is intended to allow you to get responsiveness
5462by processing the queue fairly frequently
5463without thrashing your system by trying jobs too often.
5464The default units are minutes.
5465.ip MustQuoteChars=\fIs\fP
5466[no short name]
5467Sets the list of characters that must be quoted if used in a full name
5468that is in the phrase part of a ``phrase <address>'' syntax.
5469The default is ``\'.''.
5470The characters ``@,;:\e()[]'' are always added to this list.
5471.ip NoRecipientAction
5472[no short name]
5473The action to take when you receive a message that has no valid
5474recipient headers (To:, Cc:, Bcc:, or Apparently-To: \(em
5475the last included for back compatibility with old
5476.i sendmail s).
5477It can be
5478.b None
5479to pass the message on unmodified,
5480which violates the protocol,
5481.b Add-To
5482to add a To: header with any recipients it can find in the envelope
5483(which might expose Bcc: recipients),
5484.b Add-Apparently-To
5485to add an Apparently-To: header
5486(this is only for back-compatibility
5487and is officially deprecated),
5488.b Add-To-Undisclosed
5489to add a header
5490.q "To: undisclosed-recipients:;"
5491to make the header legal without disclosing anything,
5492or
5493.b Add-Bcc
5494to add an empty Bcc: header.
5495.ip OldStyleHeaders
5496[o]
5497Assume that the headers may be in old format,
5498i.e.,
5499spaces delimit names.
5500This actually turns on
5501an adaptive algorithm:
5502if any recipient address contains a comma, parenthesis,
5503or angle bracket,
5504it will be assumed that commas already exist.
5505If this flag is not on,
5506only commas delimit names.
5507Headers are always output with commas between the names.
5508Defaults to off.
5509.ip OperatorChars=\fIcharlist\fP
5510[$o macro]
5511The list of characters that are considered to be
5512.q operators ,
5513that is, characters that delimit tokens.
5514All operator characters are tokens by themselves;
5515sequences of non-operator characters are also tokens.
5516White space characters separate tokens
5517but are not tokens themselves \(em for example,
5518.q AAA.BBB
5519has three tokens, but
5520.q "AAA BBB"
5521has two.
5522If not set, OperatorChars defaults to
5523.q \&.\|:\|@\|[\|] ;
5524additionally, the characters
5525.q (\|)\|<\|>\|,\|;
5526are always operators.
5527.ip PostmasterCopy=\fIpostmaster\fP
5528[P]
5529If set,
5530copies of error messages will be sent to the named
5531.i postmaster .
5532Only the header of the failed message is sent.
5533Since most errors are user problems,
5534this is probably not a good idea on large sites,
5535and arguably contains all sorts of privacy violations,
5536but it seems to be popular with certain operating systems vendors.
5537Defaults to no postmaster copies.
5538.ip PrivacyOptions=\fI\|opt,opt,...\fP
5539[p]
5540Set the privacy
5541.i opt ions.
5542``Privacy'' is really a misnomer;
5543many of these are just a way of insisting on stricter adherence
5544to the SMTP protocol.
5545The
5546.i opt ions
5547can be selected from:
5548.(b
5549.ta \w'needvrfyhelo'u+3n
5550public Allow open access
5551needmailhelo Insist on HELO or EHLO command before MAIL
5552needexpnhelo Insist on HELO or EHLO command before EXPN
5553noexpn Disallow EXPN entirely
5554needvrfyhelo Insist on HELO or EHLO command before VRFY
5555novrfy Disallow VRFY entirely
5556noetrn Disallow ETRN entirely
5557noverb Disallow VERB entirely
5558restrictmailq Restrict mailq command
5559restrictqrun Restrict \-q command line flag
5560noreceipts Don't return success DSNs\**
5561goaway Disallow essentially all SMTP status queries
5562authwarnings Put X-Authentication-Warning: headers in messages
5563.)b
5564.(f
5565\**N.B.:
5566the
5567.b noreceipts
5568flag causes
5569.i sendmail
5570to violate RFC 1891,
5571which requires that return receipts be provided
5572if Delivery Status Notifications are supported.
5573.)f
5574The
5575.q goaway
5576pseudo-flag sets all flags except
5577.q restrictmailq
5578and
5579.q restrictqrun .
5580If mailq is restricted,
5581only people in the same group as the queue directory
5582can print the queue.
5583If queue runs are restricted,
5584only root and the owner of the queue directory
5585can run the queue.
5586Authentication Warnings add warnings about various conditions
5587that may indicate attempts to spoof the mail system,
5588such as using an non-standard queue directory.
5589.ip QueueDirectory=\fIdir\fP
5590[Q]
5591Use the named
5592.i dir
5593as the queue directory.
5594.ip QueueFactor=\fIfactor\fP
5595[q]
5596Use
5597.i factor
5598as the multiplier in the map function
5599to decide when to just queue up jobs rather than run them.
5600This value is divided by the difference between the current load average
5601and the load average limit
5602(\c
5603.b QueueLA
5604option)
5605to determine the maximum message priority
5606that will be sent.
5607Defaults to 600000.
5608.ip QueueLA=\fILA\fP
5609[x]
5610When the system load average exceeds
5611.i LA ,
5612just queue messages
5613(i.e., don't try to send them).
5614Defaults to 8.
5615.ip QueueSortOrder=\fIalgorithm\fP
5616[no short name]
5617Sets the
5618.i algorithm
5619used for sorting the queue.
5620Only the first character of the value is used.
5621Legal values are
5622.q host
5623(to order by the name of the first host name of the first recipient),
5624.q time
5625(to order by the submission time),
5626and
5627.q priority
5628(to order by message priority).
5629Host ordering makes better use of the connection cache,
5630but may tend to process low priority messages
5631that go to a single host
5632over high priority messages that go to several hosts;
5633it probably shouldn't be used on slow network links.
5634Time ordering is almost always a bad idea,
5635since it allows large, bulk mail to go out
5636before smaller, personal mail,
5637but may have applicability on some hosts with very fast connections.
5638Priority ordering is the default.
5639.ip QueueTimeout=\fItimeout\fP
5640[T]
5641A synonym for
5642.q Timeout.queuereturn .
5643Use that form instead of the
5644.q QueueTimeout
5645form.
5646.ip ResolverOptions=\fIoptions\fP
5647[I]
5648Set resolver options.
5649Values can be set using
5650.b + \c
5651.i flag
5652and cleared using
5653.b \- \c
5654.i flag ;
5655the
5656.i flag s
5657can be
5658.q debug ,
5659.q aaonly ,
5660.q usevc ,
5661.q primary ,
5662.q igntc ,
5663.q recurse ,
5664.q defnames ,
5665.q stayopen ,
5666or
5667.q dnsrch .
5668The string
5669.q HasWildcardMX
5670(without a
5671.b +
5672or
5673.b \- )
5674can be specified to turn off matching against MX records
5675when doing name canonifications.
5676.b N.B.
5677Prior to 8.7,
5678this option indicated that the name server be responding
5679in order to accept addresses.
5680This has been replaced by checking to see
5681if the
5682.q dns
5683method is listed in the service switch entry for the
5684.q hosts
5685service.
5686.ip RunAsUser=\fIuser\fP
5687[no short name]
5688The
5689.i user
5690parameter may be a user name
5691(looked up in
5692.i /etc/passwd )
5693or a numeric user id;
5694either form can have
5695.q ":group"
5696attached
5697(where group can be numeric or symbolic).
5698If set to a non-zero (non-root) value,
5699.i sendmail
5700will change to this user id shortly after startup\**.
5701.(f
5702\**When running as a daemon,
5703it changes to this user after accepting a connection
5704but before reading any
5705.sm SMTP
5706commands.
5707.)f
5708This avoids a certain class of security problems.
5709However, this means that all
5710.q \&.forward
5711and
5712.q :include:
5713files must be readable by the indicated
5714.i user ,
5715and on systems that don't support the saved uid bit properly,
5716all files to be written must be writable by
5717.i user
5718and all programs will be executed by
5719.i user .
5720It is also incompatible with the
5721.b SafeFileEnvironment
5722option.
5723In other words, it may not actually add much to security on an average system,
5724and may in fact detract from security
5725(because other file permissions must be loosened).
5726However, it should be useful on firewalls and other
5727places where users don't have accounts and the aliases file is
5728well constrained.
5729.ip RecipientFactor=\fIfact\fP
5730[y]
5731The indicated
5732.i fact or
5733is added to the priority (thus
5734.i lowering
5735the priority of the job)
5736for each recipient,
5737i.e., this value penalizes jobs with large numbers of recipients.
5738Defaults to 30000.
5739.ip RefuseLA=\fILA\fP
5740[X]
5741When the system load average exceeds
5742.i LA ,
5743refuse incoming SMTP connections.
5744Defaults to 12.
5745.ip RetryFactor=\fIfact\fP
5746[Z]
5747The
5748.i fact or
5749is added to the priority
5750every time a job is processed.
5751Thus,
5752each time a job is processed,
5753its priority will be decreased by the indicated value.
5754In most environments this should be positive,
5755since hosts that are down are all too often down for a long time.
5756Defaults to 90000.
5757.ip SafeFileEnvironment=\fIdir\fP
5758[no short name]
5759If this option is set,
5760.i sendmail
5761will do a
5762.i chroot (2)
5763call into the indicated
5764.i dir ectory
5765before doing any file writes.
5766If the file name specified by the user begins with
5767.i dir ,
5768that partial path name will be stripped off before writing,
5769so (for example)
5770if the SafeFileEnvironment variable is set to
5771.q /safe
5772then aliases of
5773.q /safe/logs/file
5774and
5775.q /logs/file
5776actually indicate the same file.
5777Additionally, if this option is set,
5778.i sendmail
5779refuses to deliver to symbolic links.
5780.ip SaveFromLine
5781[f]
5782Save
5783Unix-style
5784.q From
5785lines at the front of headers.
5786Normally they are assumed redundant
5787and discarded.
5788.ip SendMIMEErrors
5789[j]
5790If set, send error messages in MIME format
5791(see RFC2045 and RFC1344 for details).
5792If disabled,
5793.i sendmail
5794will not return the DSN keyword in response to an EHLO
5795and will not do Delivery Status Notification processing as described in
5796RFC1891.
5797.ip ServiceSwitchFile=\fIfilename\fP
5798[no short name]
5799If your host operating system has a service switch abstraction
5800(e.g., /etc/nsswitch.conf on Solaris
5801or /etc/svc.conf on Ultrix and DEC OSF/1)
5802that service will be consulted and this option is ignored.
5803Otherwise, this is the name of a file
5804that provides the list of methods used to implement particular services.
5805The syntax is a series of lines,
5806each of which is a sequence of words.
5807The first word is the service name,
5808and following words are service types.
5809The services that
5810.i sendmail
5811consults directly are
5812.q aliases
5813and
5814.q hosts.
5815Service types can be
5816.q dns ,
5817.q nis ,
5818.q nisplus ,
5819or
5820.q files
5821(with the caveat that the appropriate support
5822must be compiled in
5823before the service can be referenced).
5824If ServiceSwitchFile is not specified, it defaults to /etc/service.switch.
5825If that file does not exist, the default switch is:
5826.(b
5827aliases files
5828hosts dns nis files
5829.)b
5830The default file is
5831.q /etc/service.switch .
5832.ip SevenBitInput
5833[7]
5834Strip input to seven bits for compatibility with old systems.
5835This shouldn't be necessary.
5836.ip SingleLineFromHeader
5837[no short name]
5838If set, From: lines that have embedded newlines are unwrapped
5839onto one line.
5840This is to get around a botch in Lotus Notes
5841that apparently cannot understand legally wrapped RFC822 headers.
5842.ip SingleThreadDelivery
5843[no short name]
5844If set, a client machine will never try to open two SMTP connections
5845to a single server machine at the same time,
5846even in different processes.
5847That is, if another
5848.i sendmail
5849is already talking to some host a new
5850.i sendmail
5851will not open another connection.
5852This property is of mixed value;
5853although this reduces the load on the other machine,
5854it can cause mail to be delayed
5855(for example, if one
5856.i sendmail
5857is delivering a huge message, other
5858.i sendmail s
5859won't be able to send even small messages).
5860Also, it requires another file descriptor
5861(for the lock file)
5862per connection, so you may have to reduce the
5863.b ConnectionCacheSize
5864option to avoid running out of per-process file descriptors.
5865Requires the
5866.b HostStatusDirectory
5867option.
5868.ip SmtpGreetingMessage=\fImessage\fP
5869[$e macro]
5870The message printed when the SMTP server starts up.
5871Defaults to
5872.q "$j Sendmail $v ready at $b".
5873.ip StatusFile=\fIfile\fP
5874[S]
5875Log summary statistics in the named
5876.i file .
5877If not set,
5878no summary statistics are saved.
5879This file does not grow in size.
5880It can be printed using the
5881.i mailstats (8)
5882program.
5883.ip SuperSafe
5884[s]
5885Be super-safe when running things,
5886i.e.,
5887always instantiate the queue file,
5888even if you are going to attempt immediate delivery.
5889.i Sendmail
5890always instantiates the queue file
5891before returning control to the client
5892under any circumstances.
5893This should really
5894.i always
5895be set.
5896.ip TempFileMode=\fImode\fP
5897[F]
5898The file mode for queue files.
5899It is interpreted in octal by default.
5900Defaults to 0600.
5901.ip Timeout.\fItype\fP=\|\fItimeout\fP
5902[r; subsumes old T option as well]
5903Set timeout values.
5904The actual timeout is indicated by the
5905.i type .
5906The recognized timeouts and their default values, and their
5907minimum values specified in RFC 1123 section 5.3.2 are:
5908.(b
5909.ta \w'datafinal'u+3n
5910initial wait for initial greeting message [5m, 5m]
5911helo reply to HELO or EHLO command [5m, none]
5912mail reply to MAIL command [10m, 5m]
5913rcpt reply to RCPT command [1h, 5m]
5914datainit reply to DATA command [5m, 2m]
5915datablock data block read [1h, 3m]
5916datafinal reply to final ``.'' in data [1h, 10m]
5917rset reply to RSET command [5m, none]
5918quit reply to QUIT command [2m, none]
5919misc reply to NOOP and VERB commands [2m, none]
5920ident IDENT protocol timeout [30s, none]
5921fileopen\(dg timeout on opening .forward and :include: files [60s, none]
5922command\(dg command read [1h, 5m]
5923queuereturn\(dg how long until a message is returned [5d, 5d]
5924queuewarn\(dg how long until a warning is sent [none, none]
5925hoststatus\(dg how long until host status is ``stale'' [30m, none]
5926.)b
5927All but those marked with a dagger (\(dg)
5928apply to client SMTP.
5929If the message is submitted using the
5930.sm NOTIFY
5931.sm SMTP
5932extension,
5933warning messages will only be sent if
5934.sm NOTIFY=DELAY
5935is specified.
5936The queuereturn and queuewarn timeouts
5937can be further qualified with a tag based on the Precedence: field
5938in the message;
5939they must be one of
5940.q urgent
5941(indicating a positive non-zero precedence)
5942.q normal
5943(indicating a zero precedence), or
5944.q non-urgent
5945(indicating negative precedences).
5946For example, setting
5947.q Timeout.queuewarn.urgent=1h
5948sets the warning timeout for urgent messages only
5949to one hour.
5950The default if no precedence is indicated
5951is to set the timeout for all precedences.
5952.ip TimeZoneSpec=\fItzinfo\fP
5953[t]
5954Set the local time zone info to
5955.i tzinfo
5956\*- for example,
5957.q PST8PDT .
5958Actually, if this is not set,
5959the TZ environment variable is cleared (so the system default is used);
5960if set but null, the user's TZ variable is used,
5961and if set and non-null the TZ variable is set to this value.
5962.ip TryNullMXList
5963[w]
5964If this system is the
5965.q best
5966(that is, lowest preference)
5967MX for a given host,
5968its configuration rules should normally detect this situation
5969and treat that condition specially
5970by forwarding the mail to a UUCP feed,
5971treating it as local,
5972or whatever.
5973However, in some cases (such as Internet firewalls)
5974you may want to try to connect directly to that host
5975as though it had no MX records at all.
5976Setting this option causes
5977.i sendmail
5978to try this.
5979The downside is that errors in your configuration
5980are likely to be diagnosed as
5981.q "host unknown"
5982or
5983.q "message timed out"
5984instead of something more meaningful.
5985This option is disrecommended.
5986.ip UnixFromLine=\fIfromline\fP
5987[$l macro]
5988Defines the format used when
5989.i sendmail
5990must add a UNIX-style From_ line
5991(that is, a line beginning
5992.q From<space>user ).
5993Defaults to
5994.q "From $g $d" .
5995Don't change this unless your system uses a different UNIX mailbox format
5996(very unlikely).
5997.ip UnsafeGroupWrites
5998[no short name]
5999If set,
6000:include: and .forward files that are group writable are considered
6001.q unsafe ,
6002that is,
6003they cannot reference programs or write directly to files.
6004World writable :include: and .forward files
6005are always unsafe..
6006.ip UseErrorsTo
6007[l]
6008If there is an
6009.q Errors-To:
6010header, send error messages to the addresses listed there.
6011They normally go to the envelope sender.
6012Use of this option causes
6013.i sendmail
6014to violate RFC 1123.
6015This option is disrecommended and deprecated.
6016.ip UserDatabaseSpec=\fIudbspec\fP
6017[U]
6018The user database specification.
6019.ip UserSubmission
6020[no short name]
6021This is an initial submission directly from a Mail User Agent.
6022This can be set in the configuration file if you have
6023MUAs that don't pass the
6024.b \-U
6025flag or use the
6026XUSR
6027ESMTP extension,
6028but some relayed mail may get inappropriately rewritten if you do.
6029.ip Verbose
6030[v]
6031Run in verbose mode.
6032If this is set,
6033.i sendmail
6034adjusts options
6035.b HoldExpensive
6036(old
6037.b c )
6038and
6039.b DeliveryMode
6040(old
6041.b d )
6042so that all mail is delivered completely
6043in a single job
6044so that you can see the entire delivery process.
6045Option
6046.b Verbose
6047should
6048.i never
6049be set in the configuration file;
6050it is intended for command line use only.
6051.lp
6052All options can be specified on the command line using the
6053\-O or \-o flag,
6054but most will cause
6055.i sendmail
6056to relinquish its setuid permissions.
6057The options that will not cause this are
6058MinFreeBlocks [b],
6059DeliveryMode [d],
6060ErrorMode [e],
6061IgnoreDots [i],
6062LogLevel [L],
6063MeToo [m],
6064OldStyleHeaders [o],
6065PrivacyOptions [p],
6066Timeouts [r],
6067SuperSafe [s],
6068Verbose [v],
6069CheckpointInterval [C],
6070and
6071SevenBitInput [7].
6072Also, M (define macro) when defining the r or s macros
6073is also considered
6074.q safe .
6075.sh 2 "P \*- Precedence Definitions"
6076.pp
6077Values for the
6078.q "Precedence:"
6079field may be defined using the
6080.b P
6081control line.
6082The syntax of this field is:
6083.(b
6084\fBP\fP\fIname\fP\fB=\fP\fInum\fP
6085.)b
6086When the
6087.i name
6088is found in a
6089.q Precedence:
6090field,
6091the message class is set to
6092.i num .
6093Higher numbers mean higher precedence.
6094Numbers less than zero
6095have the special property
6096that if an error occurs during processing
6097the body of the message will not be returned;
6098this is expected to be used for
6099.q "bulk"
6100mail such as through mailing lists.
6101The default precedence is zero.
6102For example,
6103our list of precedences is:
6104.(b
6105Pfirst-class=0
6106Pspecial-delivery=100
6107Plist=\-30
6108Pbulk=\-60
6109Pjunk=\-100
6110.)b
6111People writing mailing list exploders
6112are encouraged to use
6113.q "Precedence: list" .
6114Older versions of
6115.i sendmail
6116(which discarded all error returns for negative precedences)
6117didn't recognize this name, giving it a default precedence of zero.
6118This allows list maintainers to see error returns
6119on both old and new versions of
6120.i sendmail .
6121.sh 2 "V \*- Configuration Version Level"
6122.pp
6123To provide compatibility with old configuration files,
6124the
6125.b V
6126line has been added to define some very basic semantics
6127of the configuration file.
6128These are not intended to be long term supports;
6129rather, they describe compatibility features
6130which will probably be removed in future releases.
6131.pp
6132.b N.B.:
6133these version
6134.i levels
6135have nothing
6136to do with the version
6137.i number
6138on the files.
6139For example,
6140as of this writing
6141version 8 config files
6142(specifically, 8.9)
6143used version level 8 configurations.
6144.pp
6145.q Old
6146configuration files are defined as version level one.
6147Version level two files make the following changes:
6148.np
6149Host name canonification ($[ ... $])
6150appends a dot if the name is recognized;
6151this gives the config file a way of finding out if anything matched.
6152(Actually, this just initializes the
6153.q host
6154map with the
6155.q \-a.
6156flag \*- you can reset it to anything you prefer
6157by declaring the map explicitly.)
6158.np
6159Default host name extension is consistent throughout processing;
6160version level one configurations turned off domain extension
6161(that is, adding the local domain name)
6162during certain points in processing.
6163Version level two configurations are expected to include a trailing dot
6164to indicate that the name is already canonical.
6165.np
6166Local names that are not aliases
6167are passed through a new distinguished ruleset five;
6168this can be used to append a local relay.
6169This behaviour can be prevented by resolving the local name
6170with an initial `@'.
6171That is, something that resolves to a local mailer and a user name of
6172.q vikki
6173will be passed through ruleset five,
6174but a user name of
6175.q @vikki
6176will have the `@' stripped,
6177will not be passed through ruleset five,
6178but will otherwise be treated the same as the prior example.
6179The expectation is that this might be used to implement a policy
6180where mail sent to
6181.q vikki
6182was handled by a central hub,
6183but mail sent to
6184.q vikki@localhost
6185was delivered directly.
6186.pp
6187Version level three files
6188allow # initiated comments on all lines.
6189Exceptions are backslash escaped # marks
6190and the $# syntax.
6191.pp
6192Version level four configurations
6193are completely equivalent to level three
6194for historical reasons.
6195.pp
6196Version level five configuration files
6197change the default definition of
6198.b $w
6199to be just the first component of the hostname.
6200.pp
6201Version level six configuration files
6202change many of the local processing options
6203(such as aliasing and matching the beginning of the address for
6204`|' characters)
6205to be mailer flags;
6206this allows fine-grained control over the special local processing.
6207Level six configuration files may also use long option names.
6208The
6209.b ColonOkInAddr
6210option (to allow colons in the local-part of addresses)
6211defaults
6212.b on
6213for lower numbered configuration files;
6214the configuration file requires some additional intelligence
6215to properly handle the RFC 822 group construct.
6216.pp
6217Version level seven configuration files
6218used new option names to replace old macros
6219(\c
6220.b $e
6221became
6222.b SmtpGreeetingMessage ,
6223.b $l
6224became
6225.b UnixFromLine ,
6226and
6227.b $o
6228became
6229.b OperatorChars .
6230Also, prior to version seven,
6231the
6232.b F=q
6233flag (use 250 instead of 252 return value for
6234.sm "SMTP VRFY"
6235commands)
6236was assumed.
6237.pp
6238Version level eight configuration files allow
6239.b $#
6240on the left hand side of ruleset lines.
6241.pp
6242The
6243.b V
6244line may have an optional
6245.b / \c
6246.i vendor
6247to indicate that this configuration file uses modifications
6248specific to a particular vendor\**.
6249.(f
6250\**And of course, vendors are encouraged to add themselves
6251to the list of recognized vendors by editing the routine
6252.i setvendor
6253in
6254.i conf.c .
6255Please send e-mail to sendmail@Sendmail.ORG
6256to register your vendor dialect.
6257.)f
6258You may use
6259.q /Berkeley
6260to emphasize that this configuration file
6261uses the Berkeley dialect of
6262.i sendmail .
6263.sh 2 "K \*- Key File Declaration"
6264.pp
6265Special maps can be defined using the line:
6266.(b
6267Kmapname mapclass arguments
6268.)b
6269The
6270.i mapname
6271is the handle by which this map is referenced in the rewriting rules.
6272The
6273.i mapclass
6274is the name of a type of map;
6275these are compiled in to
6276.i sendmail .
6277The
6278.i arguments
6279are interpreted depending on the class;
6280typically,
6281there would be a single argument naming the file containing the map.
6282.pp
6283Maps are referenced using the syntax:
6284.(b
6285$( \fImap\fP \fIkey\fP $@ \fIarguments\fP $: \fIdefault\fP $)
6286.)b
6287where either or both of the
6288.i arguments
6289or
6290.i default
6291portion may be omitted.
6292The
6293.i "$@ arguments"
6294may appear more than once.
6295The indicated
6296.i key
6297and
6298.i arguments
6299are passed to the appropriate mapping function.
6300If it returns a value, it replaces the input.
6301If it does not return a value and the
6302.i default
6303is specified, the
6304.i default
6305replaces the input.
6306Otherwise, the input is unchanged.
6307.pp
6308The
6309.i arguments
6310are passed to the map for arbitrary use.
6311Most map classes can interpolate these arguments
6312into their values using the syntax
6313.q %\fIn\fP
6314(where
6315.i n
6316is a digit)
6317to indicate the corresponding
6318.i argument .
6319Argument
6320.q %0
6321indicates the database key.
6322For example, the rule
6323.(b
6324.ta 1.5i
6325R$\- ! $+ $: $(uucp $1 $@ $2 $: %1 @ %0 . UUCP $)
6326.)b
6327Looks up the UUCP name in a (user defined) UUCP map;
6328if not found it turns it into
6329.q \&.UUCP
6330form.
6331The database might contain records like:
6332.(b
6333decvax %1@%0.DEC.COM
6334research %1@%0.ATT.COM
6335.)b
6336Note that
6337.i default
6338clauses never do this mapping.
6339.pp
6340The built in map with both name and class
6341.q host
6342is the host name canonicalization lookup.
6343Thus,
6344the syntax:
6345.(b
6346$(host \fIhostname\fP$)
6347.)b
6348is equivalent to:
6349.(b
6350$[\fIhostname\fP$]
6351.)b
6352.pp
6353There are many defined classes.
6354.ip dbm
6355Database lookups using the ndbm(3) library.
6356.i Sendmail
6357must be compiled with
6358.b NDBM
6359defined.
6360.ip btree
6361Database lookups using the btree interface to the Berkeley DB
6362library.
6363.i Sendmail
6364must be compiled with
6365.b NEWDB
6366defined.
6367.ip hash
6368Database lookups using the hash interface to the Berkeley DB
6369library.
6370.i Sendmail
6371must be compiled with
6372.b NEWDB
6373defined.
6374.ip nis
6375NIS lookups.
6376.i Sendmail
6377must be compiled with
6378.b NIS
6379defined.
6380.ip nisplus
6381NIS+ lookups.
6382.i Sendmail
6383must be compiled with
6384.b NISPLUS
6385defined.
6386The argument is the name of the table to use for lookups,
6387and the
6388.b \-k
6389and
6390.b \-v
6391flags may be used to set the key and value columns respectively.
6392.ip hesiod
6393Hesiod lookups.
6394.i Sendmail
6395must be compiled with
6396.b HESIOD
6397defined.
6398.ip ldapx
6399LDAP X500 directory lookups.
6400.i Sendmail
6401must be compiled with
6402.b LDAPMAP
6403defined.
6404The map supports most of the standard arguments
6405and most of the command line arguments of the
6406.i ldapsearch
6407program.
6408.ip netinfo
6409NeXT NetInfo lookups.
6410.i Sendmail
6411must be compiled with
6412.b NETINFO
6413defined.
6414.ip text
6415Text file lookups.
6416The format of the text file is defined by the
6417.b \-k
6418(key field number),
6419.b \-v
6420(value field number),
6421and
6422.b \-z
6423(field delimiter)
6424flags.
6425.ip stab
6426Internal symbol table lookups.
6427Used internally for aliasing.
6428.ip implicit
6429Really should be called
6430.q alias
6431\(em this is used to get the default lookups
6432for alias files,
6433and is the default if no class is specified for alias files.
6434.ip user
6435Looks up users using
6436.i getpwnam (3).
6437The
6438.b \-v
6439flag can be used to specify the name of the field to return
6440(although this is normally used only to check the existence
6441of a user).
6442.ip host
6443Canonifies host domain names.
6444Given a host name it calls the name server
6445to find the canonical name for that host.
6446.ip bestmx
6447Returns the best MX record for a host name given as the key.
6448The current machine is always preferred \*-
6449that is, if the current machine is one of the hosts listed as a
6450lowest-preference MX record, then it will be guaranteed to be returned.
6451This can be used to find out if this machine is the target for an MX record,
6452and mail can be accepted on that basis.
6453If the
6454.b \-z
6455flag is given, then all MX names are returned,
6456separated by the given delimiter.
6457.ip sequence
6458The arguments on the `K' line are a list of maps;
6459the resulting map searches the argument maps in order
6460until it finds a match for the indicated key.
6461For example, if the key definition is:
6462.(b
6463Kmap1 ...
6464Kmap2 ...
6465Kseqmap sequence map1 map2
6466.)b
6467then a lookup against
6468.q seqmap
6469first does a lookup in map1.
6470If that is found, it returns immediately.
6471Otherwise, the same key is used for map2.
6472.ip switch
6473Much like the
6474.q sequence
6475map except that the order of maps is determined by the service switch.
6476The argument is the name of the service to be looked up;
6477the values from the service switch are appended to the map name
6478to create new map names.
6479For example, consider the key definition:
6480.(b
6481Kali switch aliases
6482.)b
6483together with the service switch entry:
6484.(b
6485aliases nis files
6486.)b
6487This causes a query against the map
6488.q ali
6489to search maps named
6490.q ali.nis
6491and
6492.q ali.files
6493in that order.
6494.ip dequote
6495Strip double quotes (") from a name.
6496It does not strip backslashes,
6497and will not strip quotes if the resulting string
6498would contain unscannable syntax
6499(that is, basic errors like unbalanced angle brackets;
6500more sophisticated errors such as unknown hosts are not checked).
6501The intent is for use when trying to accept mail from systems such as
6502DECnet
6503that routinely quote odd syntax such as
6504.(b
6505"49ers::ubell"
6506.)b
6507A typical usage is probably something like:
6508.(b
6509Kdequote dequote
6510
6511\&...
6512
6513R$\- $: $(dequote $1 $)
6514R$\- $+ $: $>3 $1 $2
6515.)b
6516Care must be taken to prevent unexpected results;
6517for example,
6518.(b
6519"|someprogram < input > output"
6520.)b
6521will have quotes stripped,
6522but the result is probably not what you had in mind.
6523Fortunately these cases are rare.
6524.ip regex
6525The map definition on the
6526.b K
6527line contains a regular expression.
6528Any key input is compared to that expression using the
6529POSIX regular expressions routines regcomp(), regerr(), and regexec().
6530Refer to the documentation for those routines for more information
6531about the regular expression matching.
6532No rewriting of the key is done if the
6533.b \-m
6534flag is used. Without it, the key is discarded or if
6535.b \-s
6536if used, it is substituted by the substring matches, delimited by
6537.b $|
6538or the string specified with the the
6539.b \-d
6540flag. The flags available for the map are
6541.(b
6542-n not
6543-f case sensitive
6544-b basic regular expressions
6545 (default is extended)
6546-s substring match
6547-d set the delimiter used for -s
6548-a append string to key
6549-m match only, do not
6550 replace/discard value
6551.)b
6552The
6553.b \-s
6554flag can include an optional parameter which can be used
6555to select the substrings in the result of the lookup. For example,
6556.(b
6557-s1,3,4
6558.)b
6559.ip program
6560The arguments on the
6561.b K
6562line are the pathname to a program and any initial parameters to be passed.
6563When the map is called,
6564the key is added to the initial parameters
6565and the program is invoked
6566as the default user/group id.
6567The first line of standard output is returned as the value of the lookup.
6568This has many potential security problems,
6569and has terrible performance;
6570it should be used only when absolutely necessary.
6571.pp
6572Most of these accept as arguments the same optional flags
6573and a filename
6574(or a mapname for NIS;
6575the filename is the root of the database path,
6576so that
6577.q .db
6578or some other extension appropriate for the database type
6579will be added to get the actual database name).
6580Known flags are:
6581.ip "\-o"
6582Indicates that this map is optional \*- that is,
6583if it cannot be opened,
6584no error is produced,
6585and
6586.i sendmail
6587will behave as if the map existed but was empty.
6588.ip "\-N, \-O"
6589If neither
6590.b \-N
6591or
6592.b \-O
6593are specified,
6594.i sendmail
6595uses an adaptive algorithm to decide whether or not to look for null bytes
6596on the end of keys.
6597It starts by trying both;
6598if it finds any key with a null byte it never tries again without a null byte
6599and vice versa.
6600If
6601.b \-N
6602is specified it never tries without a null byte and
6603if
6604.b \-O
6605is specified it never tries with a null byte.
6606Setting one of
6607these can speed matches but are never necessary.
6608If both
6609.b \-N
6610and
6611.b \-O
6612are specified,
6613.i sendmail
6614will never try any matches at all \(em
6615that is, everything will appear to fail.
6616.ip "\-a\fIx\fP"
6617Append the string
6618.i x
6619on successful matches.
6620For example, the default
6621.i host
6622map appends a dot on successful matches.
6623.ip "\-T\fIx\fP"
6624Append the string
6625.i x
6626on temporary failures.
6627For example,
6628.i x
6629would be appended if a DNS lookup returned
6630.q "server failed"
6631or an NIS lookup could not locate a server.
6632See also the
6633.b \-t
6634flag.
6635.ip "\-f"
6636Do not fold upper to lower case before looking up the key.
6637.ip "\-m"
6638Match only (without replacing the value).
6639If you only care about the existence of a key and not the value
6640(as you might when searching the NIS map
6641.q hosts.byname
6642for example),
6643this flag prevents the map from substituting the value.
6644However,
6645The \-a argument is still appended on a match,
6646and the default is still taken if the match fails.
6647.ip "\-k\fIkeycol\fP"
6648The key column name (for NIS+) or number
6649(for text lookups).
6650For LDAP maps this is a filter string
6651passed to printf with a %s where the string to be
6652.q "mapped"
6653is inserted.
6654.ip "\-v\fIvalcol\fP"
6655The value column name (for NIS+) or number
6656(for text lookups).
6657For LDAP maps this is the name of the
6658attribute to be returned.
6659.ip "\-z\fIdelim\fP"
6660The column delimiter (for text lookups).
6661It can be a single character or one of the special strings
6662.q \|\en
6663or
6664.q \|\et
6665to indicate newline or tab respectively.
6666If omitted entirely,
6667the column separator is any sequence of whitespace.
6668.ip "\-t"
6669Normally, when a map attempts to do a lookup
6670and the server fails
6671(e.g.,
6672.i sendmail
6673couldn't contact any name server;
6674this is
6675.i not
6676the same as an entry not being found in the map),
6677the message being processed is queued for future processing.
6678The
6679.b \-t
6680flag turns off this behaviour,
6681letting the temporary failure (server down)
6682act as though it were a permanent failure (entry not found).
6683It is particularly useful for DNS lookups,
6684where someone else's misconfigured name server can cause problems
6685on your machine.
6686However, care must be taken to ensure that you don't bounce mail
6687that would be resolved correctly if you tried again.
6688A common strategy is to forward such mail
6689to another, possibly better connected, mail server.
6690.ip "\-s\fIspacesub\fP
6691For the dequote map only,
6692the character to use to replace space characters
6693after a successful dequote.
6694.ip "\-q"
6695Don't dequote the key before lookup.
6696.ip "\-A"
6697When rebuilding an alias file,
6698the
6699.b \-A
6700flag causes duplicate entries in the text version
6701to be merged.
6702For example, two entries:
6703.(b
6704list: user1, user2
6705list: user3
6706.)b
6707would be treated as though it were the single entry
6708.(b
6709list: user1, user2, user3
6710.)b
6711in the presence of the
6712.b \-A
6713flag.
6714.pp
6715The
6716.i dbm
6717map appends the strings
6718.q \&.pag
6719and
6720.q \&.dir
6721to the given filename;
6722the
6723.i hash
6724and
6725.i btree
6726maps append
6727.q \&.db .
6728For example, the map specification
6729.(b
6730Kuucp dbm \-o \-N /usr/lib/uucpmap
6731.)b
6732specifies an optional map named
6733.q uucp
6734of class
6735.q dbm ;
6736it always has null bytes at the end of every string,
6737and the data is located in
6738/usr/lib/uucpmap.{dir,pag}.
6739.pp
6740The program
6741.i makemap (8)
6742can be used to build any of the three database-oriented maps.
6743It takes the following flags:
6744.ip \-f
6745Do not fold upper to lower case in the map.
6746.ip \-N
6747Include null bytes in keys.
6748.ip \-o
6749Append to an existing (old) file.
6750.ip \-r
6751Allow replacement of existing keys;
6752normally, re-inserting an existing key is an error.
6753.ip \-v
6754Print what is happening.
6755.lp
6756The
6757.i sendmail
6758daemon does not have to be restarted to read the new maps
6759as long as you change them in place;
6760file locking is used so that the maps won't be read
6761while they are being updated.\**
6762.(f
6763\**That is, don't create new maps and then use
6764.i mv (1)
6765to move them into place.
6766Since the maps are already open
6767the new maps will never be seen.
6768.)f
6769.pp
6770New classes can be added in the routine
6771.b setupmaps
6772in file
6773.b conf.c .
6774.sh 2 "The User Database"
6775.pp
6776If you have a version of
6777.i sendmail
6778with the user database package
6779compiled in,
6780the handling of sender and recipient addresses
6781is modified.
6782.pp
6783The location of this database is controlled with the
6784.b UserDatabaseSpec
6785option.
6786.sh 3 "Structure of the user database"
6787.pp
6788The database is a sorted (BTree-based) structure.
6789User records are stored with the key:
6790.(b
6791\fIuser-name\fP\fB:\fP\fIfield-name\fP
6792.)b
6793The sorted database format ensures that user records are clustered together.
6794Meta-information is always stored with a leading colon.
6795.pp
6796Field names define both the syntax and semantics of the value.
6797Defined fields include:
6798.nr ii 1i
6799.ip maildrop
6800The delivery address for this user.
6801There may be multiple values of this record.
6802In particular,
6803mailing lists will have one
6804.i maildrop
6805record for each user on the list.
6806.ip "mailname"
6807The outgoing mailname for this user.
6808For each outgoing name,
6809there should be an appropriate
6810.i maildrop
6811record for that name to allow return mail.
6812See also
6813.i :default:mailname .
6814.ip mailsender
6815Changes any mail sent to this address to have the indicated envelope sender.
6816This is intended for mailing lists,
6817and will normally be the name of an appropriate -request address.
6818It is very similar to the owner-\c
6819.i list
6820syntax in the alias file.
6821.ip fullname
6822The full name of the user.
6823.ip office-address
6824The office address for this user.
6825.ip office-phone
6826The office phone number for this user.
6827.ip office-fax
6828The office FAX number for this user.
6829.ip home-address
6830The home address for this user.
6831.ip home-phone
6832The home phone number for this user.
6833.ip home-fax
6834The home FAX number for this user.
6835.ip project
6836A (short) description of the project this person is affiliated with.
6837In the University this is often just the name of their graduate advisor.
6838.ip plan
6839A pointer to a file from which plan information can be gathered.
6840.pp
6841As of this writing,
6842only a few of these fields are actually being used by
6843.i sendmail :
6844.i maildrop
6845and
6846.i mailname .
6847A
6848.i finger
6849program that uses the other fields is planned.
6850.sh 3 "User database semantics"
6851.pp
6852When the rewriting rules submit an address to the local mailer,
6853the user name is passed through the alias file.
6854If no alias is found (or if the alias points back to the same address),
6855the name (with
6856.q :maildrop
6857appended)
6858is then used as a key in the user database.
6859If no match occurs (or if the maildrop points at the same address),
6860forwarding is tried.
6861.pp
6862If the first token of the user name returned by ruleset 0
6863is an
6864.q @
6865sign, the user database lookup is skipped.
6866The intent is that the user database will act as a set of defaults
6867for a cluster (in our case, the Computer Science Division);
6868mail sent to a specific machine should ignore these defaults.
6869.pp
6870When mail is sent,
6871the name of the sending user is looked up in the database.
6872If that user has a
6873.q mailname
6874record,
6875the value of that record is used as their outgoing name.
6876For example, I might have a record:
6877.(b
6878eric:mailname Eric.Allman@CS.Berkeley.EDU
6879.)b
6880This would cause my outgoing mail to be sent as Eric.Allman.
6881.pp
6882If a
6883.q maildrop
6884is found for the user,
6885but no corresponding
6886.q mailname
6887record exists,
6888the record
6889.q :default:mailname
6890is consulted.
6891If present, this is the name of a host to override the local host.
6892For example, in our case we would set it to
6893.q CS.Berkeley.EDU .
6894The effect is that anyone known in the database
6895gets their outgoing mail stamped as
6896.q user@CS.Berkeley.EDU ,
6897but people not listed in the database use the local hostname.
6898.sh 3 "Creating the database\**"
6899.(f
6900\**These instructions are known to be incomplete.
6901A future version of the user database is planned
6902including things such as finger service \*- and good documentation.
6903.)f
6904.pp
6905The user database is built from a text file
6906using the
6907.i makemap
6908utility
6909(in the distribution in the makemap subdirectory).
6910The text file is a series of lines corresponding to userdb records;
6911each line has a key and a value separated by white space.
6912The key is always in the format described above \*-
6913for example:
6914.(b
6915eric:maildrop
6916.)b
6917This file is normally installed in a system directory;
6918for example, it might be called
6919.i /etc/userdb .
6920To make the database version of the map, run the program:
6921.(b
6922makemap btree /etc/userdb.db < /etc/userdb
6923.)b
6924Then create a config file that uses this.
6925For example, using the V8 M4 configuration, include the
6926following line in your .mc file:
6927.(b
6928define(\`confUSERDB_SPEC\', /etc/userdb.db)
6929.)b
6930.sh 1 "OTHER CONFIGURATION"
6931.pp
6932There are some configuration changes that can be made by
6933recompiling
6934.i sendmail .
6935This section describes what changes can be made
6936and what has to be modified to make them.
6937In most cases this should be unnecessary
6938unless you are porting
6939.i sendmail
6940to a new environment.
6941.sh 2 "Parameters in BuildTools/OS/$oscf"
6942.pp
6943These parameters are intended to describe the compilation environment,
6944not site policy,
6945and should normally be defined in the operating system
6946configuration file.
6947.b "This section needs a complete rewrite."
6948.ip NDBM
6949If set,
6950the new version of the DBM library
6951that allows multiple databases will be used.
6952If neither NDBM nor NEWDB are set,
6953a much less efficient method of alias lookup is used.
6954.ip NEWDB
6955If set, use the new database package from Berkeley (from 4.4BSD).
6956This package is substantially faster than DBM or NDBM.
6957If NEWDB and NDBM are both set,
6958.i sendmail
6959will read DBM files,
6960but will create and use NEWDB files.
6961.ip NIS
6962Include support for NIS.
6963If set together with
6964.i both
6965NEWDB and NDBM,
6966.i sendmail
6967will create both DBM and NEWDB files if and only if
6968an alias file includes the substring
6969.q /yp/
6970in the name.
6971This is intended for compatibility with Sun Microsystems'
6972.i mkalias
6973program used on YP masters.
6974.ip NISPLUS
6975Compile in support for NIS+.
6976.ip NETINFO
6977Compile in support for NetInfo (NeXT stations).
6978.ip LDAPMAP
6979Compile in support for LDAP X500 queries.
6980Requires libldap and liblber
6981from the Umich LDAP 3.2 or 3.3 release.
6982.ip HESIOD
6983Compile in support for Hesiod.
6984.ip _PATH_SENDMAILCF
6985The pathname of the sendmail.cf file.
6986.ip _PATH_SENDMAILPID
6987The pathname of the sendmail.pid file.
6988.pp
6989There are also several compilation flags to indicate the environment
6990such as
6991.q _AIX3
6992and
6993.q _SCO_unix_ .
6994See the src/README
6995file for the latest scoop on these flags.
6996.sh 2 "Parameters in src/conf.h"
6997.pp
6998Parameters and compilation options
6999are defined in conf.h.
7000Most of these need not normally be tweaked;
7001common parameters are all in sendmail.cf.
7002However, the sizes of certain primitive vectors, etc.,
7003are included in this file.
7004The numbers following the parameters
7005are their default value.
7006.pp
7007This document is not the best source of information
7008for compilation flags in conf.h \(em
7009see src/README or src/conf.h itself.
7010.nr ii 1.2i
7011.ip "MAXLINE [2048]"
7012The maximum line length of any input line.
7013If message lines exceed this length
7014they will still be processed correctly;
7015however, header lines,
7016configuration file lines,
7017alias lines,
7018etc.,
7019must fit within this limit.
7020.ip "MAXNAME [256]"
7021The maximum length of any name,
7022such as a host or a user name.
7023.ip "MAXPV [40]"
7024The maximum number of parameters to any mailer.
7025This limits the number of recipients that may be passed in one transaction.
7026It can be set to any arbitrary number above about 10,
7027since
7028.i sendmail
7029will break up a delivery into smaller batches as needed.
7030A higher number may reduce load on your system, however.
7031.ip "MAXATOM [100]"
7032The maximum number of atoms
7033(tokens)
7034in a single address.
7035For example,
7036the address
7037.q "eric@CS.Berkeley.EDU"
7038is seven atoms.
7039.ip "MAXMAILERS [25]"
7040The maximum number of mailers that may be defined
7041in the configuration file.
7042.ip "MAXRWSETS [200]"
7043The maximum number of rewriting sets
7044that may be defined.
7045The first half of these are reserved for numeric specification
7046(e.g., ``S92''),
7047while the upper half are reserved for auto-numbering
7048(e.g., ``Sfoo'').
7049Thus, with a value of 200 an attempt to use ``S99'' will succeed,
7050but ``S100'' will fail.
7051.ip "MAXPRIORITIES [25]"
7052The maximum number of values for the
7053.q Precedence:
7054field that may be defined
7055(using the
7056.b P
7057line in sendmail.cf).
7058.ip "MAXUSERENVIRON [100]"
7059The maximum number of items in the user environment
7060that will be passed to subordinate mailers.
7061.ip "MAXMXHOSTS [100]"
7062The maximum number of MX records we will accept for any single host.
7063.ip "MAXALIASDB [12]"
7064The maximum number of alias databases that can be open at any time.
7065Note that there may also be an open file limit.
7066.ip "MAXMAPSTACK [12]"
7067The maximum number of maps that may be "stacked" in a
7068.b sequence
7069class map.
7070.ip "MAXMIMEARGS [20]"
7071The maximum number of arguments in a MIME Content-Type: header;
7072additional arguments will be ignored.
7073.ip "MAXMIMENESTING [20]"
7074The maximum depth to which MIME messages may be nested
7075(that is, nested Message or Multipart documents;
7076this does not limit the number of components in a single Multipart document).
7077.lp
7078A number of other compilation options exist.
7079These specify whether or not specific code should be compiled in.
7080Ones marked with \(dg
7081are 0/1 valued.
7082.nr ii 1.2i
7083.ip NETINET\(dg
7084If set,
7085support for Internet protocol networking is compiled in.
7086Previous versions of
7087.i sendmail
7088referred to this as
7089.sm DAEMON ;
7090this old usage is now incorrect.
7091Defaults on;
7092turn it off in the Makefile
7093if your system doesn't support the Internet protocols.
7094.ip NETISO\(dg
7095If set,
7096support for ISO protocol networking is compiled in
7097(it may be appropriate to #define this in the Makefile instead of conf.h).
7098.ip LOG
7099If set,
7100the
7101.i syslog
7102routine in use at some sites is used.
7103This makes an informational log record
7104for each message processed,
7105and makes a higher priority log record
7106for internal system errors.
7107.b "STRONGLY RECOMMENDED"
7108\(em if you want no logging, turn it off in the configuration file.
7109.ip MATCHGECOS\(dg
7110Compile in the code to do ``fuzzy matching'' on the GECOS field
7111in /etc/passwd.
7112This also requires that the
7113.b MatchGECOS
7114option be turned on.
7115.ip NAMED_BIND\(dg
7116Compile in code to use the
7117Berkeley Internet Name Domain (BIND) server
7118to resolve TCP/IP host names.
7119.ip NOTUNIX
7120If you are using a non-UNIX mail format,
7121you can set this flag to turn off special processing
7122of UNIX-style
7123.q "From "
7124lines.
7125.ip QUEUE\(dg
7126This flag should be set to compile in the queueing code.
7127If this is not set,
7128mailers must accept the mail immediately
7129or it will be returned to the sender.
7130.ip SMTP\(dg
7131If set,
7132the code to handle user and server SMTP will be compiled in.
7133This is only necessary if your machine has some mailer
7134that speaks SMTP
7135(this means most machines everywhere).
7136.ip USERDB\(dg
7137Include the
7138.b experimental
7139Berkeley user information database package.
7140This adds a new level of local name expansion
7141between aliasing and forwarding.
7142It also uses the NEWDB package.
7143This may change in future releases.
7144.lp
7145The following options are normally turned on
7146in per-operating-system clauses in conf.h.
7147.ip IDENTPROTO\(dg
7148Compile in the IDENT protocol as defined in RFC 1413.
7149This defaults on for all systems except Ultrix,
7150which apparently has the interesting
7151.q feature
7152that when it receives a
7153.q "host unreachable"
7154message it closes all open connections to that host.
7155Since some firewall gateways send this error code
7156when you access an unauthorized port (such as 113, used by IDENT),
7157Ultrix cannot receive email from such hosts.
7158.ip SYSTEM5
7159Set all of the compilation parameters appropriate for System V.
7160.ip HASFLOCK\(dg
7161Use Berkeley-style
7162.b flock
7163instead of System V
7164.b lockf
7165to do file locking.
7166Due to the highly unusual semantics of locks
7167across forks in
7168.b lockf ,
7169this should always be used if at all possible.
7170.ip HASINITGROUPS
7171Set this if your system has the
7172.i initgroups()
7173call
7174(if you have multiple group support).
7175This is the default if SYSTEM5 is
7176.i not
7177defined or if you are on HPUX.
7178.ip HASUNAME
7179Set this if you have the
7180.i uname (2)
7181system call (or corresponding library routine).
7182Set by default if
7183SYSTEM5
7184is set.
7185.ip HASGETDTABLESIZE
7186Set this if you have the
7187.i getdtablesize (2)
7188system call.
7189.ip HASWAITPID
7190Set this if you have the
7191.i haswaitpid (2)
7192system call.
7193.ip SFS_TYPE
7194The mechanism that can be used to get file system capacity information.
7195The values can be one of
7196SFS_USTAT (use the ustat(2) syscall),
7197SFS_4ARGS (use the four argument statfs(2) syscall),
7198SFS_VFS (use the two argument statfs(2) syscall including <sys/vfs.h>),
7199SFS_MOUNT (use the two argument statfs(2) syscall including <sys/mount.h>),
7200SFS_STATFS (use the two argument statfs(2) syscall including <sys/statfs.h>),
7201SFS_STATVFS (use the two argument statfs(2) syscall including <sys/statvfs.h>),
7202or
7203SFS_NONE (no way to get this information).
7204.ip LA_TYPE
7205The load average type.
7206Details are described below.
7207.lp
7208The are several built-in ways of computing the load average.
7209.i Sendmail
7210tries to auto-configure them based on imperfect guesses;
7211you can select one using the
7212.i cc
7213option
7214.b \-DLA_TYPE= \c
7215.i type ,
7216where
7217.i type
7218is:
7219.ip LA_INT
7220The kernel stores the load average in the kernel as an array of long integers.
7221The actual values are scaled by a factor FSCALE
7222(default 256).
7223.ip LA_SHORT
7224The kernel stores the load average in the kernel as an array of short integers.
7225The actual values are scaled by a factor FSCALE
7226(default 256).
7227.ip LA_FLOAT
7228The kernel stores the load average in the kernel as an array of
7229double precision floats.
7230.ip LA_MACH
7231Use MACH-style load averages.
7232.ip LA_SUBR
7233Call the
7234.i getloadavg
7235routine to get the load average as an array of doubles.
7236.ip LA_ZERO
7237Always return zero as the load average.
7238This is the fallback case.
7239.lp
7240If type
7241.sm LA_INT ,
7242.sm LA_SHORT ,
7243or
7244.sm LA_FLOAT
7245is specified,
7246you may also need to specify
7247.sm _PATH_UNIX
7248(the path to your system binary)
7249and
7250.sm LA_AVENRUN
7251(the name of the variable containing the load average in the kernel;
7252usually
7253.q _avenrun
7254or
7255.q avenrun ).
7256.sh 2 "Configuration in src/conf.c"
7257.pp
7258The following changes can be made in conf.c.
7259.sh 3 "Built-in Header Semantics"
7260.pp
7261Not all header semantics are defined in the configuration file.
7262Header lines that should only be included by certain mailers
7263(as well as other more obscure semantics)
7264must be specified in the
7265.i HdrInfo
7266table in
7267.i conf.c .
7268This table contains the header name
7269(which should be in all lower case)
7270and a set of header control flags (described below),
7271The flags are:
7272.ip H_ACHECK
7273Normally when the check is made to see if a header line is compatible
7274with a mailer,
7275.i sendmail
7276will not delete an existing line.
7277If this flag is set,
7278.i sendmail
7279will delete
7280even existing header lines.
7281That is,
7282if this bit is set and the mailer does not have flag bits set
7283that intersect with the required mailer flags
7284in the header definition in
7285sendmail.cf,
7286the header line is
7287.i always
7288deleted.
7289.ip H_EOH
7290If this header field is set,
7291treat it like a blank line,
7292i.e.,
7293it will signal the end of the header
7294and the beginning of the message text.
7295.ip H_FORCE
7296Add this header entry
7297even if one existed in the message before.
7298If a header entry does not have this bit set,
7299.i sendmail
7300will not add another header line if a header line
7301of this name already existed.
7302This would normally be used to stamp the message
7303by everyone who handled it.
7304.ip H_TRACE
7305If set,
7306this is a timestamp
7307(trace)
7308field.
7309If the number of trace fields in a message
7310exceeds a preset amount
7311the message is returned
7312on the assumption that it has an aliasing loop.
7313.ip H_RCPT
7314If set,
7315this field contains recipient addresses.
7316This is used by the
7317.b \-t
7318flag to determine who to send to
7319when it is collecting recipients from the message.
7320.ip H_FROM
7321This flag indicates that this field
7322specifies a sender.
7323The order of these fields in the
7324.i HdrInfo
7325table specifies
7326.i sendmail 's
7327preference
7328for which field to return error messages to.
7329.ip H_ERRORSTO
7330Addresses in this header should receive error messages.
7331.ip H_CTE
7332This header is a Content-Transfer-Encoding header.
7333.ip H_CTYPE
7334This header is a Content-Type header.
7335.ip H_STRIPVAL
7336Strip the value from the header (for Bcc:).
7337.nr ii 5n
7338.lp
7339Let's look at a sample
7340.i HdrInfo
7341specification:
7342.(b
7343.ta 4n +\w'"content-transfer-encoding", 'u
7344struct hdrinfo HdrInfo[] =
7345\&{
7346 /* originator fields, most to least significant */
7347 "resent-sender", H_FROM,
7348 "resent-from", H_FROM,
7349 "sender", H_FROM,
7350 "from", H_FROM,
7351 "full-name", H_ACHECK,
7352 "errors-to", H_FROM\^|\^H_ERRORSTO,
7353 /* destination fields */
7354 "to", H_RCPT,
7355 "resent-to", H_RCPT,
7356 "cc", H_RCPT,
7357 "bcc", H_RCPT\^|\^H_STRIPVAL,
7358 /* message identification and control */
7359 "message", H_EOH,
7360 "text", H_EOH,
7361 /* trace fields */
7362 "received", H_TRACE\^|\^H_FORCE,
7363 /* miscellaneous fields */
7364 "content-transfer-encoding", H_CTE,
7365 "content-type", H_CTYPE,
7366
7367 NULL, 0,
7368};
7369.)b
7370This structure indicates that the
7371.q To: ,
7372.q Resent-To: ,
7373and
7374.q Cc:
7375fields
7376all specify recipient addresses.
7377Any
7378.q Full-Name:
7379field will be deleted unless the required mailer flag
7380(indicated in the configuration file)
7381is specified.
7382The
7383.q Message:
7384and
7385.q Text:
7386fields will terminate the header;
7387these are used by random dissenters around the network world.
7388The
7389.q Received:
7390field will always be added,
7391and can be used to trace messages.
7392.pp
7393There are a number of important points here.
7394First,
7395header fields are not added automatically just because they are in the
7396.i HdrInfo
7397structure;
7398they must be specified in the configuration file
7399in order to be added to the message.
7400Any header fields mentioned in the configuration file but not
7401mentioned in the
7402.i HdrInfo
7403structure have default processing performed;
7404that is,
7405they are added unless they were in the message already.
7406Second,
7407the
7408.i HdrInfo
7409structure only specifies cliched processing;
7410certain headers are processed specially by ad hoc code
7411regardless of the status specified in
7412.i HdrInfo .
7413For example,
7414the
7415.q Sender:
7416and
7417.q From:
7418fields are always scanned on ARPANET mail
7419to determine the sender\**;
7420.(f
7421\**Actually, this is no longer true in SMTP;
7422this information is contained in the envelope.
7423The older ARPANET protocols did not completely distinguish
7424envelope from header.
7425.)f
7426this is used to perform the
7427.q "return to sender"
7428function.
7429The
7430.q "From:"
7431and
7432.q "Full-Name:"
7433fields are used to determine the full name of the sender
7434if possible;
7435this is stored in the macro
7436.b $x
7437and used in a number of ways.
7438.sh 3 "Restricting Use of Email"
7439.pp
7440If it is necessary to restrict mail through a relay,
7441the
7442.i checkcompat
7443routine can be modified.
7444This routine is called for every recipient address.
7445It returns an exit status
7446indicating the status of the message.
7447The status
7448.sm EX_OK
7449accepts the address,
7450.sm EX_TEMPFAIL
7451queues the message for a later try,
7452and other values
7453(commonly
7454.sm EX_UNAVAILABLE )
7455reject the message.
7456It is up to
7457.i checkcompat
7458to print an error message
7459(using
7460.i usrerr )
7461if the message is rejected.
7462For example,
7463.i checkcompat
7464could read:
7465.(b
7466.re
7467.sz -1
7468.ta 4n +4n +4n +4n +4n +4n +4n
7469int
7470checkcompat(to, e)
7471 register ADDRESS *to;
7472 register ENVELOPE *e;
7473\&{
7474 register STAB *s;
7475
7476 s = stab("private", ST_MAILER, ST_FIND);
7477 if (s != NULL && e\->e_from.q_mailer != LocalMailer &&
7478 to->q_mailer == s->s_mailer)
7479 {
7480 usrerr("No private net mail allowed through this machine");
7481 return (EX_UNAVAILABLE);
7482 }
7483 if (MsgSize > 50000 && bitnset(M_LOCALMAILER, to\->q_mailer))
7484 {
7485 usrerr("Message too large for non-local delivery");
7486 e\->e_flags |= EF_NORETURN;
7487 return (EX_UNAVAILABLE);
7488 }
7489 return (EX_OK);
7490}
7491.sz
7492.)b
7493This would reject messages greater than 50000 bytes
7494unless they were local.
7495The
7496.i EF_NORETURN
7497flag can be set in
7498.i e\(->e_flags
7499to suppress the return of the actual body
7500of the message in the error return.
7501The actual use of this routine is highly dependent on the
7502implementation,
7503and use should be limited.
7504.sh 3 "New Database Map Classes"
7505.pp
7506New key maps can be added by creating a class initialization function
7507and a lookup function.
7508These are then added to the routine
7509.i setupmaps.
7510.pp
7511The initialization function is called as
7512.(b
7513\fIxxx\fP_map_init(MAP *map, char *args)
7514.)b
7515The
7516.i map
7517is an internal data structure.
7518The
7519.i args
7520is a pointer to the portion of the configuration file line
7521following the map class name;
7522flags and filenames can be extracted from this line.
7523The initialization function must return
7524.sm TRUE
7525if it successfully opened the map,
7526.sm FALSE
7527otherwise.
7528.pp
7529The lookup function is called as
7530.(b
7531\fIxxx\fP_map_lookup(MAP *map, char buf[], char **av, int *statp)
7532.)b
7533The
7534.i map
7535defines the map internally.
7536The
7537.i buf
7538has the input key.
7539This may be (and often is) used destructively.
7540The
7541.i av
7542is a list of arguments passed in from the rewrite line.
7543The lookup function should return a pointer to the new value.
7544If the map lookup fails,
7545.i *statp
7546should be set to an exit status code;
7547in particular, it should be set to
7548.sm EX_TEMPFAIL
7549if recovery is to be attempted by the higher level code.
7550.sh 3 "Queueing Function"
7551.pp
7552The routine
7553.i shouldqueue
7554is called to decide if a message should be queued
7555or processed immediately.
7556Typically this compares the message priority to the current load average.
7557The default definition is:
7558.(b
7559bool
7560shouldqueue(pri, ctime)
7561 long pri;
7562 time_t ctime;
7563{
7564 if (CurrentLA < QueueLA)
7565 return (FALSE);
7566 return (pri > (QueueFactor / (CurrentLA \- QueueLA + 1)));
7567}
7568.)b
7569If the current load average
7570(global variable
7571.i CurrentLA ,
7572which is set before this function is called)
7573is less than the low threshold load average
7574(option
7575.b x ,
7576variable
7577.i QueueLA ),
7578.i shouldqueue
7579returns
7580.sm FALSE
7581immediately
7582(that is, it should
7583.i not
7584queue).
7585If the current load average exceeds the high threshold load average
7586(option
7587.b X ,
7588variable
7589.i RefuseLA ),
7590.i shouldqueue
7591returns
7592.sm TRUE
7593immediately.
7594Otherwise, it computes the function based on the message priority,
7595the queue factor
7596(option
7597.b q ,
7598global variable
7599.i QueueFactor ),
7600and the current and threshold load averages.
7601.pp
7602An implementation wishing to take the actual age of the message into account
7603can also use the
7604.i ctime
7605parameter,
7606which is the time that the message was first submitted to
7607.i sendmail .
7608Note that the
7609.i pri
7610parameter is already weighted
7611by the number of times the message has been tried
7612(although this tends to lower the priority of the message with time);
7613the expectation is that the
7614.i ctime
7615would be used as an
7616.q "escape clause"
7617to ensure that messages are eventually processed.
7618.sh 3 "Refusing Incoming SMTP Connections"
7619.pp
7620The function
7621.i refuseconnections
7622returns
7623.sm TRUE
7624if incoming SMTP connections should be refused.
7625The current implementation is based exclusively on the current load average
7626and the refuse load average option
7627(option
7628.b X ,
7629global variable
7630.i RefuseLA ):
7631.(b
7632bool
7633refuseconnections()
7634{
7635 return (CurrentLA >= RefuseLA);
7636}
7637.)b
7638A more clever implementation
7639could look at more system resources.
7640.sh 3 "Load Average Computation"
7641.pp
7642The routine
7643.i getla
7644returns the current load average (as a rounded integer).
7645The distribution includes several possible implementations.
7646If you are porting to a new environment
7647you may need to add some new tweaks.\**
7648.(f
7649\**If you do, please send updates to
7650sendmail@Sendmail.ORG.
7651.)f
7652.sh 2 "Configuration in src/daemon.c"
7653.pp
7654The file
7655.i src/daemon.c
7656contains a number of routines that are dependent
7657on the local networking environment.
7658The version supplied assumes you have BSD style sockets.
7659.pp
7660In previous releases,
7661we recommended that you modify the routine
7662.i maphostname
7663if you wanted to generalize
7664.b $[
7665\&...\&
7666.b $]
7667lookups.
7668We now recommend that you create a new keyed map instead.
7669.sh 1 "ACKNOWLEDGEMENTS"
7670.pp
7671I've worked on
7672.i sendmail
7673for many years,
7674and many employers have been remarkably patient
7675about letting me work on a large project
7676that was not part of my official job.
7677This includes time on the INGRES Project at
7678the University of California at Berkeley,
7679at Britton Lee,
7680and again on the Mammoth and Titan Projects at Berkeley.
7681.pp
7682Much of the second wave of improvements
7683resulting in version 8.1
7684should be credited to Bryan Costales of the
7685International Computer Science Institute.
7686As he passed me drafts of his book on
7687.i sendmail
7688I was inspired to start working on things again.
7689Bryan was also available to bounce ideas off of.
7690.pp
7691Gregory Neil Shapiro
7692of Worchester Polytechnic Institute
7693has become instrumental in all phases of
7694.i sendmail
7695support and development,
7696and was largely responsible for getting versions 8.8 and 8.9
7697out the door.
7698.pp
7699Many, many people contributed chunks of code and ideas to
7700.i sendmail .
7701It has proven to be a group network effort.
7702Version 8 in particular was a group project.
7703The following people made notable contributions:
7704.(l
7705John Beck, Hewlett-Packard & Sun Microsystems
7706Keith Bostic, CSRG, University of California, Berkeley
7707Andrew Cheng, Sun Microsystems
7708Michael J. Corrigan, University of California, San Diego
7709Bryan Costales, International Computer Science Institute & InfoBeat
7710Pa\*:r (Pell) Emanuelsson
7711Craig Everhart, Transarc Corporation
7712Per Hedeland, Ericsson
7713Tom Ivar Helbekkmo, Norwegian School of Economics
7714Kari Hurtta, Finnish Meteorological Institute
7715Allan E. Johannesen, WPI
7716Jonathan Kamens, OpenVision Technologies, Inc.
7717Takahiro Kanbe, Fuji Xerox Information Systems Co., Ltd.
7718Brian Kantor, University of California, San Diego
7719John Kennedy, Cal State University, Chico
7720Murray S. Kucherawy, HookUp Communication Corp.
7721Bruce Lilly, Sony U.S.
7722Karl London
7723Motonori Nakamura, Ritsumeikan University & Kyoto University
7724John Gardiner Myers, Carnegie Mellon University
7725Neil Rickert, Northern Illinois University
7726Gregory Neil Shapiro, WPI
7727Eric Schnoebelen, Convex Computer Corp.
7728Eric Wassenaar, National Institute for Nuclear and High Energy Physics, Amsterdam
7729Randall Winchester, University of Maryland
7730Christophe Wolfhugel, Pasteur Institute & Herve Schauer Consultants (Paris)
7731.)l
7732I apologize for anyone I have omitted, misspelled, misattributed, or
7733otherwise missed.
7734At this point, I suspect that at least a hundred people
7735have contributed code,
7736and many more have contributed ideas, comments, and encouragement.
7737I've tried to list them in the RELEASE_NOTES in the distribution directory.
7738I appreciate their contribution as well.
7739.pp
7740Special thanks are reserved for Michael Corrigan and Christophe Wolfhugel,
7741who besides being wonderful guinea pigs and contributors
7742have also consented to be added to the ``sendmail@Sendmail.ORG'' list
7743and, by answering the bulk of the questions sent to that list,
7744have freed me up to do other work.
7745.++ A
7746.+c "COMMAND LINE FLAGS"
7747.ba 0
7748.nr ii 1i
7749.pp
7750Arguments must be presented with flags before addresses.
7751The flags are:
7752.ip \-b\fIx\fP
7753Set operation mode to
7754.i x .
7755Operation modes are:
7756.(b
7757.ta 4n
7758m Deliver mail (default)
7759s Speak SMTP on input side
7760a\(dg ``Arpanet'' mode (get envelope sender information from header)
7761d Run as a daemon in background
7762D Run as a daemon in foreground
7763t Run in test mode
7764v Just verify addresses, don't collect or deliver
7765i Initialize the alias database
7766p Print the mail queue
7767.)b
7768.(f
7769\(dgDeprecated.
7770.)f
7771.ip \-B\fItype\fP
7772Indicate body type.
7773.ip \-C\fIfile\fP
7774Use a different configuration file.
7775.i Sendmail
7776runs as the invoking user (rather than root)
7777when this flag is specified.
7778.ip \-d\fIlevel\fP
7779Set debugging level.
7780.ip "\-f\ \fIaddr\fP"
7781The sender's machine address is
7782.i addr .
7783.ip \-F\ \fIname\fP
7784Sets the full name of this user to
7785.i name .
7786.ip "\-h\ \fIcnt\fP"
7787Sets the
7788.q "hop count"
7789to
7790.i cnt .
7791This represents the number of times this message has been processed
7792by
7793.i sendmail
7794(to the extent that it is supported by the underlying networks).
7795.i Cnt
7796is incremented during processing,
7797and if it reaches
7798MAXHOP
7799(currently 30)
7800.i sendmail
7801throws away the message with an error.
7802.ip \-n
7803Don't do aliasing or forwarding.
7804.ip "\-N \fInotifications\fP"
7805Tag all addresses being sent as wanting the indicated
7806.i notifications ,
7807which consists of the word
7808.q NEVER
7809or a comma-separated list of
7810.q SUCCESS ,
7811.q FAILURE ,
7812and
7813.q DELAY
7814for successful delivery,
7815failure,
7816and a message that is stuck in a queue somewhere.
7817The default is
7818.q FAILURE,DELAY .
7819.ip "\-r\ \fIaddr\fP"
7820An obsolete form of
7821.b \-f .
7822.ip \-o\fIx\|value\fP
7823Set option
7824.i x
7825to the specified
7826.i value .
7827These options are described in Section 5.6.
7828.ip \-O\fIoption\fP\fB=\fP\fIvalue\fP
7829Set
7830.i option
7831to the specified
7832.i value
7833(for long form option names).
7834These options are described in Section 5.6.
7835.ip \-M\fIx\|value
7836Set macro
7837.i x
7838to the specified
7839.i value .
7840.ip \-p\fIprotocol\fP
7841Set the sending protocol.
7842Programs are encouraged to set this.
7843The protocol field can be in the form
7844.i protocol \c
7845.b : \c
7846.i host
7847to set both the sending protocol and sending host.
7848For example,
7849.q \-pUUCP:uunet
7850sets the sending protocol to UUCP
7851and the sending host to uunet.
7852(Some existing programs use \-oM to set the r and s macros;
7853this is equivalent to using \-p.)
7854.ip \-q\fItime\fP
7855Try to process the queued up mail.
7856If the time is given,
7857a
7858.i sendmail
7859will run through the queue at the specified interval
7860to deliver queued mail;
7861otherwise, it only runs once.
7862.ip \-q\fIXstring\fP
7863Run the queue once,
7864limiting the jobs to those matching
7865.i Xstring .
7866The key letter
7867.i X
7868can be
7869.b I
7870to limit based on queue identifier,
7871.b R
7872to limit based on recipient,
7873or
7874.b S
7875to limit based on sender.
7876A particular queued job is accepted if one of the corresponding addresses
7877contains the indicated
7878.i string .
7879Multiple
7880.i \-q\fIX\fP
7881flags are permitted,
7882with items with the same key letter
7883.q or'ed
7884together, and items with different key letters
7885.q and'ed
7886together.
7887.ip "\-R ret"
7888What information you want returned if the message bounces;
7889.i ret
7890can be
7891.q HDRS
7892for headers only or
7893.q FULL
7894for headers plus body.
7895This is a request only;
7896the other end is not required to honor the parameter.
7897.ip \-t
7898Read the header for
7899.q To: ,
7900.q Cc: ,
7901and
7902.q Bcc:
7903lines, and send to everyone listed in those lists.
7904The
7905.q Bcc:
7906line will be deleted before sending.
7907Any addresses in the argument vector will be deleted
7908from the send list.
7909.ip "\-U"
7910Indicate that this is an initial User Agent submission.
7911In future releases, sendmail may complain about syntactically invalid messages
7912rather than fixing them when this flag is not set.
7913.ip "\-V envid"
7914The indicated
7915.i envid
7916is passed with the envelope of the message
7917and returned if the message bounces.
7918.ip "\-X \fIlogfile\fP"
7919Log all traffic in and out of
7920.i sendmail
7921in the indicated
7922.i logfile
7923for debugging mailer problems.
7924This produces a lot of data very quickly and should be used sparingly.
7925.pp
7926There are a number of options that may be specified as
7927primitive flags.
7928These are the e, i, m, and v options.
7929Also,
7930the f option
7931may be specified as the
7932.b \-s
7933flag.
7934.+c "QUEUE FILE FORMATS"
7935.pp
7936This appendix describes the format of the queue files.
7937These files live in the directory defined by the
7938.b Q
7939option in the
7940.i sendmail.cf
7941file, usually
7942.i /var/spool/mqueue
7943or
7944.i /usr/spool/mqueue .
7945.pp
7946All queue files have the name
7947\fIx\fP\|\fBf\fP\fIAAA99999\fP
7948where
7949.i AAA99999
7950is the
7951.i id
7952for this message
7953and the
7954.i x
7955is a type.
7956The first letter of the id encodes the hour of the day
7957that the message was received by the system
7958(with A being the hour between midnight and 1:00AM).
7959All files with the same id collectively define one message.
7960.pp
7961The types are:
7962.nr ii 0.5i
7963.ip d
7964The data file.
7965The message body (excluding the header) is kept in this file.
7966.ip q
7967The queue control file.
7968This file contains the information necessary to process the job.
7969.ip t
7970A temporary file.
7971These are an image of the
7972.b qf
7973file when it is being rebuilt.
7974It should be renamed to a
7975.b qf
7976file very quickly.
7977.ip x
7978A transcript file,
7979existing during the life of a session
7980showing everything that happens
7981during that session.
7982.pp
7983The
7984.b qf
7985file is structured as a series of lines
7986each beginning with a code letter.
7987The lines are as follows:
7988.ip V
7989The version number of the queue file format,
7990used to allow new
7991.i sendmail
7992binaries to read queue files created by older versions.
7993Defaults to version zero.
7994Must be the first line of the file if present.
7995.ip H
7996A header definition.
7997There may be any number of these lines.
7998The order is important:
7999they represent the order in the final message.
8000These use the same syntax
8001as header definitions in the configuration file.
8002.ip C
8003The controlling address.
8004The syntax is
8005.q localuser:aliasname .
8006Recipient addresses following this line
8007will be flagged so that deliveries will be run as the
8008.i localuser
8009(a user name from the /etc/passwd file);
8010.i aliasname
8011is the name of the alias that expanded to this address
8012(used for printing messages).
8013.ip Q
8014The ``original recipient'',
8015specified by the ORCPT= field in an ESMTP transaction.
8016Used exclusively for Delivery Status Notifications.
8017It applies only to the immediately following `R' line.
8018.ip R
8019A recipient address.
8020This will normally be completely aliased,
8021but is actually realiased when the job is processed.
8022There will be one line
8023for each recipient.
8024Version 1 qf files
8025also include a leading colon-terminated list of flags,
8026which can be
8027`S' to return a message on successful final delivery,
8028`F' to return a message on failure,
8029`D' to return a message if the message is delayed,
8030`B' to indicate that the body should be returned,
8031`N' to suppress returning the body,
8032and
8033`P' to declare this as a ``primary'' (command line or SMTP-session) address.
8034.ip S
8035The sender address.
8036There may only be one of these lines.
8037.ip T
8038The job creation time.
8039This is used to compute when to time out the job.
8040.ip P
8041The current message priority.
8042This is used to order the queue.
8043Higher numbers mean lower priorities.
8044The priority changes
8045as the message sits in the queue.
8046The initial priority depends on the message class
8047and the size of the message.
8048.ip M
8049A message.
8050This line is printed by the
8051.i mailq
8052command,
8053and is generally used to store status information.
8054It can contain any text.
8055.ip F
8056Flag bits, represented as one letter per flag.
8057Defined flag bits are
8058.b r
8059indicating that this is a response message
8060and
8061.b w
8062indicating that a warning message has been sent
8063announcing that the mail has been delayed.
8064.ip N
8065The total number of delivery attempts.
8066.ip K
8067The time (as seconds since January 1, 1970)
8068of the last delivery attempt.
8069.ip I
8070The i-number of the data file;
8071this can be used to recover your mail queue
8072after a disastrous disk crash.
8073.ip $
8074A macro definition.
8075The values of certain macros
8076(as of this writing, only
8077.b $r
8078and
8079.b $s )
8080are passed through to the queue run phase.
8081.ip B
8082The body type.
8083The remainder of the line is a text string defining the body type.
8084If this field is missing,
8085the body type is assumed to be
8086.q "undefined"
8087and no special processing is attempted.
8088Legal values are
8089.q 7BIT
8090and
8091.q 8BITMIME .
8092.ip O
8093The original MTS value (from the ESMTP transaction).
8094For Deliver Status Notifications only.
8095.ip Z
8096The original envelope id (from the ESMTP transaction).
8097For Deliver Status Notifications only.
8098.pp
8099As an example,
8100the following is a queue file sent to
8101.q eric@mammoth.Berkeley.EDU
8102and
8103.q bostic@okeeffe.CS.Berkeley.EDU \**:
8104.(f
8105\**This example is contrived and probably inaccurate for your environment.
8106Glance over it to get an idea;
8107nothing can replace looking at what your own system generates.
8108.)f
8109.(b
8110P835771
8111T404261372
8112Seric
8113Ceric:sendmail@vangogh.CS.Berkeley.EDU
8114Reric@mammoth.Berkeley.EDU
8115Rbostic@okeeffe.CS.Berkeley.EDU
8116H?P?Return-path: <owner-sendmail@vangogh.CS.Berkeley.EDU>
8117HReceived: by vangogh.CS.Berkeley.EDU (5.108/2.7) id AAA06703;
8118 Fri, 17 Jul 1992 00:28:55 -0700
8119HReceived: from mail.CS.Berkeley.EDU by vangogh.CS.Berkeley.EDU (5.108/2.7)
8120 id AAA06698; Fri, 17 Jul 1992 00:28:54 -0700
8121HReceived: from [128.32.31.21] by mail.CS.Berkeley.EDU (5.96/2.5)
8122 id AA22777; Fri, 17 Jul 1992 03:29:14 -0400
8123HReceived: by foo.bar.baz.de (5.57/Ultrix3.0-C)
8124 id AA22757; Fri, 17 Jul 1992 09:31:25 GMT
8125H?F?From: eric@foo.bar.baz.de (Eric Allman)
8126H?x?Full-name: Eric Allman
8127HMessage-id: <9207170931.AA22757@foo.bar.baz.de>
8128HTo: sendmail@vangogh.CS.Berkeley.EDU
8129HSubject: this is an example message
8130.)b
8131This shows
8132the person who sent the message,
8133the submission time
8134(in seconds since January 1, 1970),
8135the message priority,
8136the message class,
8137the recipients,
8138and the headers for the message.
8139.+c "SUMMARY OF SUPPORT FILES"
8140.pp
8141This is a summary of the support files
8142that
8143.i sendmail
8144creates or generates.
8145Many of these can be changed by editing the sendmail.cf file;
8146check there to find the actual pathnames.
8147.nr ii 1i
8148.ip "/usr/\*(SD/sendmail"
8149The binary of
8150.i sendmail .
8151.ip /usr/\*(SB/newaliases
8152A link to /usr/\*(SD/sendmail;
8153causes the alias database to be rebuilt.
8154Running this program is completely equivalent to giving
8155.i sendmail
8156the
8157.b \-bi
8158flag.
8159.ip /usr/\*(SB/mailq
8160Prints a listing of the mail queue.
8161This program is equivalent to using the
8162.b \-bp
8163flag to
8164.i sendmail .
8165.ip /etc/sendmail.cf
8166The configuration file,
8167in textual form.
8168.ip /usr/lib/sendmail.hf
8169The SMTP help file.
8170.ip /etc/sendmail.st
8171A statistics file; need not be present.
8172.ip /etc/sendmail.pid
8173Created in daemon mode;
8174it contains the process id of the current SMTP daemon.
8175If you use this in scripts;
8176use ``head \-1'' to get just the first line;
8177the second line contains the command line used to invoke the daemon,
8178and later versions of
8179.i sendmail
8180may add more information to subsequent lines.
8181.ip /etc/aliases
8182The textual version of the alias file.
8183.ip /etc/aliases.db
8184The alias file in
8185.i hash \|(3)
8186format.
8187.ip /etc/aliases.{pag,dir}
8188The alias file in
8189.i ndbm \|(3)
8190format.
8191.ip /var/spool/mqueue
8192The directory in which the mail queue
8193and temporary files reside.
8194.ip /var/spool/mqueue/qf*
8195Control (queue) files for messages.
8196.ip /var/spool/mqueue/df*
8197Data files.
8198.ip /var/spool/mqueue/tf*
8199Temporary versions of the qf files,
8200used during queue file rebuild.
8201.ip /var/spool/mqueue/xf*
8202A transcript of the current session.
8203.if o \
8204\{\
8205. bp
8206. rs
8207. sp |4i
8208. ce 2
8209This page intentionally left blank;
8210replace it with a blank sheet for double-sided output.
8211.\}
8212.\".ro
8213.\".ls 1
8214.\".tp
8215.\".sp 2i
8216.\".in 0
8217.\".ce 100
8218.\".sz 24
8219.\".b SENDMAIL
8220.\".sz 14
8221.\".sp
8222.\"INSTALLATION AND OPERATION GUIDE
8223.\".sp
8224.\".sz 10
8225.\"Eric Allman
8226.\".sp
|