1.if n .ls 2 2.he 'Sendmail Installation and Operation Guide''%' 3.fo 'Version 3.18'DRAFT'Last Mod 02/26/83' 4.nr si 3n 5.de $0 6.(x 7.in \\$3u*3n 8.ti -3n 9\\$2. \\$1 10.)x 11.. 12.de $C 13.(x 14.in 0 15\\$1 \\$2. \\$3 16.)x 17.. 18.+c 19.(l C 20.sz 16 21.b SENDMAIL 22.sz 12 23.sp 24.b "INSTALLATION AND OPERATION GUIDE" 25.sz 10 26.sp 27.r 28Eric Allman 29Britton-Lee, Inc. 30.sp 31Version 3.18 32.)l 33.sp 34.(l F 35.b NOTE: 36.i 37This is a working paper, not a specification. 38Details of operation of 39.r sendmail 40may change as necessary 41before final release. 42.)l 43.sp 2 44.pp 45.i Sendmail 46implements a general purpose internetwork mail routing facility 47under the UNIX* 48.(f 49*UNIX is a trademark of Bell Laboratories. 50.)f 51operating system. 52It is not tied to any one transport protocol \*- 53its function may be likened to a crossbar switch, 54relaying messages from one domain into another. 55In the process, 56it can do a limited amount of message header editing 57to put the message into a format that is appropriate 58for the receiving domain. 59All of this is done under the control of a configuration file. 60.pp 61Due to the requirements of flexibility 62for 63.i sendmail , 64the configuration file can seem somewhat unapproachable. 65However, there are only a few basic configurations 66for most sites, 67for which standard configuration files have been supplied. 68Most other configurations 69can be built by adjusting an existing configuration files 70incrementally. 71.pp 72Although 73.i sendmail 74is intended to run 75without the need for monitoring, 76it has a number of features 77that may be used to monitor or adjust the operation 78under unusual circumstances. 79These features are described. 80.pp 81Section one describes how to do a basic 82.i sendmail 83installation. 84Section two 85explains the day-to-day information you should know 86to maintain your mail system. 87If you have a relatively normal site, 88these two sections should contain sufficient information 89for you to install 90.i sendmail 91and keep it happy. 92Section three 93describes some parameters that may be safely tweaked. 94Section four 95has information regarding the command line arguments. 96Section five 97contains the nitty-gritty information about the configuration 98file. 99This section is for masochists 100and people who must write their own configuration file. 101The appendixes give a brief 102but detailed explanation of a number of features 103not described in the rest of the paper. 104.pp 105The references in this paper are actually found 106in the companion paper 107.ul 108Sendmail \- An Internetwork Mail Router. 109This other paper should be read before this manual 110to gain a basic understanding 111of how the pieces fit together. 112.sh 1 "BASIC INSTALLATION" 113.pp 114There are two basic steps to installing sendmail. 115The hard part is to build the configuration table. 116This is a file that sendmail reads when it starts up 117that describes the mailers it knows about, 118how to parse addresses, 119how to rewrite the message header, 120and the settings of various options. 121Although the configuration table is quite complex, 122a configuration can usually be built 123by adjusting an existing off-the-shelf configuration. 124The second part is actually doing the installation, 125i.e., creating the necessary files, etc. 126.pp 127The remainder of this section will describe the installation of sendmail 128assuming you can use one of the existing configurations 129and that the standard installation parameters are acceptable. 130All pathnames and examples 131are given from the root of the 132.i sendmail 133subtree. 134.sh 2 "Off-The-Shelf Configurations" 135.pp 136The configuration files 137are all in the subdirectory 138.i cf 139of the sendmail directory. 140The ones used at Berkeley are in 141.i m4 \|(1) 142format; 143files with names ending 144.q .m4 145are 146.i m4 147include files, 148while files with names ending 149.q .mc 150are the master files. 151Files with names ending 152.q .cf 153are the 154.i m4 155processed versions of the corresponding 156.q .mc 157file. 158.pp 159Two off the shelf configuration files are supplied 160to handle the basic cases: 161.i cf/arpaproto.cf 162for Arpanet (TCP) sites 163and 164.i cf/uucpproto.cf 165for UUCP sites. 166These are 167.i not 168in 169.i m4 170format. 171There are two parameters you will have to adjust 172in each of these files. 173The line beginning 174.q DH 175defines the canonical name of your host. 176The line beginning 177.q CH 178defines the names that your host might be known by; 179it should include the name listed in the 180.q DH 181line 182and any aliases that your host goes by. 183For example, a configuration might include the lines: 184.(b 185DHucsfcgl 186CHucsfcgl cgl 187.)b 188This would indicate that the 189.q standard 190name for the host is 191.q ucsfcgl 192and that it is known by the names 193.q ucsfcgl 194and 195.q cgl. 196.pp 197The changed file should be renamed; 198in the above example, 199the file might be renamed 200.i ucsfcgl.cf. 201This file 202is now ready for installation as 203.i /usr/lib/sendmail.cf . 204.sh 2 "Installation Using the Makefile" 205.pp 206A makefile exists in the root of the 207.i sendmail 208directory that will do all of these steps 209for a 4.2bsd system. 210It may have to be slightly tailored 211for use on other systems. 212.pp 213Before using this makefile, 214you should already have created your configuration file 215and left it in the file 216.q cf/\fIsystem\fP.cf 217where 218.i system 219is the name of your system 220(i.e., what is returned by 221.i hostname \|(1)). 222If you do not have 223.i hostname 224you can use the declaration 225.q HOST=\fIsystem\fP 226on the 227.i make \|(1) 228command line. 229.pp 230The basic installation procedure is to type: 231.(b 232make 233make install 234.)b 235in the root directory of the 236.i sendmail 237distribution. 238This will make all binaries 239and install them in the standard places. 240The second 241.i make 242command must be executed as the superuser (root). 243.sh 2 "Installation by Hand" 244.pp 245Along with building a configuration file, 246you will have to install the 247.i sendmail 248startup into your UNIX system. 249If you are doing this installation 250in conjunction with a regular Berkeley UNIX install, 251these steps will already be complete. 252Many of these steps will have to be executed as the superuser (root). 253.sh 3 "lib/libsys.a" 254.pp 255The library in lib/libsys.a 256contains some routines that should in some sense 257be part of the system library. 258These are the system logging routines 259and the new directory access routines 260(if required). 261If you are not running the new 4.2bsd directory code 262and do not have the compatibility routines installed in your system library, 263you should execute the commands: 264.(b 265cd lib 266make ndir 267.)b 268This will compile and install the 4.2 compatibility routines 269in the library. 270You should then type: 271.(b 272cd lib # if required 273make 274.)b 275This will recompile and fill the library. 276.sh 3 "/usr/lib/sendmail" 277.pp 278The binary for sendmail is located in /usr/lib. 279There is a version available in the source directory 280that is probably inadequate for your system. 281You should plan on recompiling and installing the entire system: 282.(b 283cd src 284rm \-f *.o 285make 286cp sendmail /usr/lib 287.)b 288.sh 3 "/usr/lib/sendmail.cf" 289.pp 290The configuration file 291that you created earlier 292should be installed in /usr/lib/sendmail.cf: 293.(b 294cp cf/\fIsystem\fP.cf /usr/lib/sendmail.cf 295.)b 296.sh 3 "/usr/ucb/newaliases" 297.pp 298If you are running delivermail, 299it is critical that the 300.i newaliases 301command be replaced. 302This can just be a link to 303.i sendmail : 304.(b 305rm \-f /usr/ucb/newaliases 306ln /usr/lib/sendmail /usr/ucb/newaliases 307.)b 308.sh 3 "/usr/lib/sendmail.cf" 309.pp 310The configuration file must be installed in /usr/lib. 311This is described above. 312.sh 3 "/usr/spool/mqueue" 313.pp 314The directory 315.i /usr/spool/mqueue 316should be created to hold the mail queue. 317This directory should be mode 777 318unless 319.i sendmail 320is run setuid, 321when 322.i mqueue 323should be owned by the sendmail owner 324and mode 755. 325.sh 3 "/usr/lib/aliases*" 326.pp 327The system aliases are held in three files. 328The file 329.q /usr/lib/aliases 330is the master copy. 331A sample is given in 332.q lib/aliases 333which includes some aliases which 334.i must 335be defined: 336.(b 337cp lib/aliases /usr/lib/aliases 338.)b 339You should extend this file with any aliases that are apropos to your system. 340.pp 341Normally 342.i sendmail 343looks at a version of these files maintained by the 344.i dbm \|(3) 345routines. 346These are stored in 347.q /usr/lib/aliases.dir 348and 349.q /usr/lib/aliases.pag. 350These can initially be created as empty files, 351but they will have to be initialized promptly. 352These should be mode 666 if you are running a reasonably relaxed system: 353.(b 354cp /dev/null /usr/lib/aliases.dir 355cp /dev/null /usr/lib/aliases.pag 356chmod 666 /usr/lib/aliases.* 357newaliases 358.)b 359.sh 3 "/usr/lib/sendmail.fc" 360.pp 361If you intend to install the frozen version of the configuration file 362(for quick startup) 363you should create the file /usr/lib/sendmail.fc 364and initialize it. 365This step may be safely skipped. 366.(b 367cp /dev/null /usr/lib/sendmail.fc 368/usr/lib/sendmail \-bz 369.)b 370.sh 3 "/etc/rc" 371.pp 372It will be necessary to start up the sendmail daemon when your system reboots. 373This daemon performs two functions: 374it listens on the SMTP socket for connections 375(to receive mail from a remote system) 376and it processes the queue periodically 377to insure that mail gets delivered when hosts come up. 378.pp 379Add the following lines to 380.q /etc/rc 381(or 382.q /etc/rc.local 383as appropriate) 384in the area where it is starting up the daemons: 385.(b 386if [ \-f /usr/lib/sendmail ]; then 387 (cd /usr/spool/mqueue; rm \-f lf*) 388 /usr/lib/sendmail \-bd \-q10m & 389 echo \-n ' sendmail' >/dev/console 390fi 391.)b 392The 393.q cd 394and 395.q rm 396commands insure that all lock files have been removed; 397extraneous lock files may be left around 398if the system goes down in the middle of processing a message. 399The line that actually invokes 400.i sendmail 401has two flags: 402.q \-bd 403causes it to listen on the SMTP port, 404and 405.q \-q10m 406causes it to run the queue every ten minutes. 407.pp 408If you are not running a version of UNIX 409that supports Berkeley TCP/IP, 410do not include the 411.b \-bd 412flag. 413.sh 3 "/usr/lib/sendmail.hf" 414.pp 415This is the help file used by the SMTP 416.b HELP 417command. 418It should be copied from 419.q lib/sendmail.hf : 420.(b 421cp lib/sendmail.hf /usr/lib 422.)b 423.sh 3 "/usr/lib/sendmail.st" 424.pp 425If you wish to collect statistics 426about your mail traffic, 427you should create the file 428.q /usr/lib/sendmail.st : 429.(b 430cp /dev/null /usr/lib/sendmail.st 431chmod 666 /usr/lib/sendmail.st 432.)b 433This file does not grow. 434It is printed with the program 435.q aux/mailstats. 436.sh 3 "/etc/syslog" 437.pp 438You may want to run the 439.i syslog 440program 441(to collect log information about sendmail). 442This program normally resides in 443.i /etc/syslog, 444with support files 445.i /etc/syslog.conf 446and 447.i /etc/syslog.pid . 448The program is located in the 449.i aux 450subdirectory of the 451.i sendmail 452distribution. 453The file 454.i /etc/syslog.conf 455describes the file(s) that sendmail will log in. 456For a complete description of syslog, 457see the manual page for 458.i syslog \|(8) 459(located in 460.i sendmail/doc 461on the distribution). 462.sh 3 "/usr/ucb/newaliases" 463.pp 464If 465.i sendmail 466is invoked as 467.q newaliases, 468it will simulate the 469.b \-bi 470flag 471(i.e., will rebuild the alias database; 472see below). 473This should be a link to /usr/lib/sendmail. 474.sh 3 "/usr/ucb/mailq" 475.pp 476If 477.i sendmail 478is invoked as 479.q mailq, 480it will simulate the 481.b \-bp 482flag 483(i.e., 484.i sendmail 485will print the contents of the mail queue; 486see below). 487This should be a link to /usr/lib/sendmail. 488.sh 1 "NORMAL OPERATIONS" 489.sh 2 "Quick Configuration Startup" 490.pp 491A fast version of the configuration file 492may be set up by using the 493.b \-bz 494flag: 495.(b 496/usr/lib/sendmail \-bz 497.)b 498This creates the file 499.i /usr/lib/sendmail.fc 500(\c 501.q "frozen configuration" ). 502This file is an image of 503.i sendmail 's 504data space after reading in the configuration file. 505If this file exists, 506it is used instead of 507.i /usr/lib/sendmail.cf 508.i sendmail.fc 509must be rebuilt manually every time 510.i sendmail.cf 511is changed. 512.pp 513The frozen configuration file will be ignored 514if a 515.b \-C 516flag is specified 517or if sendmail detects that it is out of date. 518However, the heuristics are not strong 519so this should not be trusted. 520.sh 2 "The System Log" 521.pp 522The system log is supported by the 523.i syslog \|(8) 524program. 525.sh 3 "Format" 526.pp 527Each line in the system log 528consists of a timestamp, 529the name of the machine that generated it 530(for logging from several machines 531over the ethernet), 532the word 533.q sendmail: , 534and a message. 535.sh 3 "Levels" 536.pp 537If you have 538.i syslog \|(8) 539or an equivalent installed, 540you will be able to do logging. 541There is a large amount of information that can be logged. 542The log is arranged as a succession of levels. 543At the lowest level 544only extremely strange situations are logged. 545At the highest level, 546even the most mundane and uninteresting events 547are recorded for posterity. 548As a convention, 549log levels under ten 550are considered 551.q useful; 552log levels above ten 553are usually for debugging purposes. 554.pp 555A complete description of the log levels 556is given in section 4.3. 557.sh 2 "The Mail Queue" 558.pp 559The mail queue should be processed transparently. 560However, you may find that manual intervention is sometimes necessary. 561For example, 562if a major host is down for a period of time 563the queue may become clogged. 564Although sendmail ought to recover gracefully when the host comes up, 565you may find performance unacceptably bad in the meantime. 566.sh 3 "Printing the queue" 567.pp 568The contents of the queue can be printed 569using the 570.i mailq 571command 572(or by specifying the 573.b \-bp 574flag to sendmail): 575.(b 576mailq 577.)b 578This will produce a listing of the queue id's, 579the size of the message, 580the date the message entered the queue, 581and the sender and recipients. 582.sh 3 "Format of queue files" 583.pp 584All queue files have the form 585\fIx\fP\|\fBf\fP\fIAA99999\fP 586where 587.i AA99999 588is the 589.i id 590for this file 591and the 592.i x 593is a type. 594The types are: 595.ip d 596The data file. 597The message body (excluding the header) is kept in this file. 598.ip l 599The lock file. 600If this file exists, 601the job is currently being processed, 602and a queue run will not process the file. 603For that reason, 604an extraneous 605.b lf 606file can cause a job to apparently disappear 607(it will not even time out!). 608.ip n 609This file is created when an id is being created. 610It is a separate file to insure that no mail can ever be destroyed 611due to a race condition. 612It should exist for no more than a few milliseconds 613at any given time. 614.ip q 615The queue control file. 616This file contains the information necessary to process the job. 617.ip t 618A temporary file. 619These are an image of the 620.b qf 621file when it is being rebuilt. 622It should be renamed to a 623.b qf 624file very quickly. 625.ip x 626A transcript file, 627existing during the life of a session 628showing everything that happens 629during that session. 630.pp 631The 632.b qf 633file is structured as a series of lines 634each beginning with a code letter. 635The lines are as follows: 636.ip D 637The name of the data file. 638There may only be one of these lines. 639.ip H 640A header definition. 641There may be any number of these lines. 642The order is important: 643they represent the order in the final message. 644These use the same syntax 645as header definitions in the configuration file. 646.ip R 647A recipient address. 648This will normally be completely aliased, 649but is actually realiased when the job is processed. 650There will be one line 651for each recipient. 652.ip S 653The sender address. 654There may only be one of these lines. 655.ip T 656The job creation time. 657This is used to compute when to time out the job. 658.ip P 659The current message priority. 660This is used to order the queue. 661Higher numbers mean lower priorities. 662The priority drops 663as the message sits in the queue. 664The initial priority depends on the message class 665and the size of the message. 666.ip M 667A message. 668This line is printed by the 669.i mailq 670command, 671and is generally used to store status information. 672It can contain any text. 673.pp 674As an example, 675the following is a queue file sent to 676.q mckusick@calder 677and 678.q wnj : 679.(b 680DdfA13557 681Seric 682T404261372 683P132 684Rmckusick@calder 685Rwnj 686H?D?date: 23-Oct-82 15:49:32-PDT (Sat) 687H?F?from: eric (Eric Allman) 688H?x?full-name: Eric Allman 689Hsubject: this is an example message 690Hmessage-id: <8209232249.13557@UCBARPA.BERKELEY.ARPA> 691Hreceived: by UCBARPA.BERKELEY.ARPA (3.227 [10/22/82]) 692 id A13557; 23-Oct-82 15:49:32-PDT (Sat) 693Hphone: (415) 548-3211 694HTo: mckusick@calder, wnj 695.)b 696This shows the name of the data file, 697the person who sent the message, 698the submission time 699(in seconds since January 1, 1970), 700the message priority, 701the message class, 702the recipients, 703and the headers for the message. 704.sh 3 "Forcing the queue" 705.pp 706.i Sendmail 707should run the queue automatically 708at intervals. 709The algorithm is to read and sort the queue, 710and then to attempt to process all jobs in order. 711When it attempts to run the job, 712.i sendmail 713first checks to see if the job is locked. 714If so, it ignores the job. 715.pp 716There is no attempt to insure that only one queue processor 717exists at any time, 718since there is no guarantee that a job cannot take forever 719to process. 720Due to the locking algorithm, 721it is impossible for one job to freeze the queue. 722However, 723an uncooperative recipient host 724or a program recipient 725that never returns 726can accumulate many processes in your system. 727Unfortunately, 728there is no way to resolve this 729without violating the protocol. 730.pp 731In some cases, 732you may find that a major host going down 733for a couple of days 734may create a prohibitively large queue. 735This will result in 736.i sendmail 737spending an inordinate amount of time 738sorting the queue. 739This situation can be fixed by moving the queue to a temporary place 740and creating a new queue. 741The old queue can be run later when the offending host returns to service. 742.pp 743To do this, 744it is acceptable to move the entire queue directory: 745.(b 746cd /usr/spool 747mv mqueue omqueue; mkdir mqueue; chmod 777 mqueue 748.)b 749You should then kill the existing daemon 750(since it will still be processing in the old queue directory) 751and create a new daemon. 752.pp 753To run the old mail queue, 754run the following command: 755.(b 756/usr/lib/sendmail \-oQ/usr/spool/omqueue \-q 757.)b 758The 759.b \-oQ 760flag specifies an alternate queue directory 761and the 762.b \-q 763flag says to just run every job in the queue. 764If you have a tendency toward voyeurism, 765you can use the 766.b \-v 767flag to watch what is going on. 768.pp 769When the queue is finally emptied, 770you can remove the directory: 771.(b 772rmdir /usr/spool/omqueue 773.)b 774.sh 2 "The Alias Database" 775.pp 776The alias database exists in two forms. 777One is a text form, 778maintained in the file 779.i /usr/lib/aliases. 780The aliases are of the form 781.(b 782name: name1, name2, ... 783.)b 784Only local names may be aliased; 785e.g., 786.(b 787eric@mit-xx: eric@berkeley 788.)b 789will not have the desired effect. 790Aliases may be continued by starting any continuation lines 791with a space or a tab. 792Blank lines and lines beginning with a sharp sign 793(\c 794.q # ) 795are comments. 796.pp 797The second form is processed by the 798.i dbm \|(3) 799library. 800This form is in the files 801.i /usr/lib/aliases.dir 802and 803.i /usr/lib/aliases.pag. 804This is the form that 805.i sendmail 806actually uses to resolve aliases. 807This technique is used to improve performance. 808.sh 3 "Rebuilding the alias database" 809.pp 810The DBM version of the database 811may be rebuilt explicitly by executing the command 812.(b 813newaliases 814.)b 815This is equivalent to giving 816.i sendmail 817the 818.b \-bi 819flag: 820.(b 821/usr/lib/sendmail \-bi 822.)b 823.pp 824If the 825.q D 826option is specified in the configuration, 827.i sendmail 828will rebuild the alias database automatically 829if possible 830when it is out of date. 831The conditions under which it will do this are: 832.np 833The DBM version of the database is mode 666. -or- 834.np 835.i Sendmail 836is running setuid to root. 837.lp 838Auto-rebuild can be dangerous 839on heavily loaded machines 840with large alias files; 841if it might take more than five minutes 842to rebuild the database, 843there is a chance that several processes will start the rebuild process 844simultaneously. 845.sh 3 "Potential problems" 846.pp 847There are a number of problems that can occur 848with the alias database. 849They all result from a 850.i sendmail 851process accessing the DBM version 852while it is only partially built. 853This can happen under two circumstances: 854One process accesses the database 855while another process is rebuilding it, 856or the process rebuilding the database dies 857(due to being killed or a system crash) 858before completing the rebuild. 859.pp 860Sendmail has two techniques to try to relieve these problems. 861First, it ignores interrupts while rebuilding the database; 862this avoids the problem of someone aborting the process 863leaving a partially rebuilt database. 864Second, 865at the end of the rebuild 866it adds an alias of the form 867.(b 868@: @ 869.)b 870(which is not normally legal). 871Before sendmail will access the database, 872it checks to insure that this entry exists\**. 873.(f 874\**The 875.q a 876option is required in the configuration 877for this action to occur. 878This should normally be specified 879unless you are running 880.i delivermail 881in parallel with 882.i sendmail. 883.)f 884It will wait up to five minutes 885for this entry to appear, 886at which point it will force a rebuild itself\**. 887.(f 888\**Note: 889the 890.q D 891option must be specified in the configuration file 892for this operation to occur. 893.)f 894.sh 3 "List owners" 895.pp 896If an error occurs on sending to a certain address, 897say 898.q \fIx\fP , 899.i sendmail 900will look for an alias 901of the form 902.q owner-\fIx\fP 903to receive the errors. 904This is typically useful 905for a mailing list 906where the submitter of the list 907has no control over the maintanence of the list itself; 908in this case the list maintainer would be the owner of the list. 909For example: 910.(b 911unix-wizards: eric@ucbarpa, wnj@monet, nosuchuser, 912 sam@matisse 913owner-unix-wizards: eric@ucbarpa 914.)b 915would cause 916.q eric@ucbarpa 917to get the error that will occur 918when someone sends to 919unix-wizards 920due to the inclusion of 921.q nosuchuser 922on the list. 923.sh 2 "Per-User Forwarding (.forward Files)" 924.pp 925As an alternative to the alias database, 926any user may put a file with the name 927.q .forward 928in his or her home directory. 929If this file exists, 930.i sendmail 931redirects mail for that user 932to the list of addresses listed in the .forward file. 933For example, if the home directory for user 934.q mckusick 935has a .forward file with contents: 936.(b 937mckusick@ernie 938kirk@calder 939.)b 940then any mail arriving for 941.q mckusick 942will be redirected to the specified accounts. 943.sh 2 "Special Header Lines" 944.pp 945Several header lines have special interpretations 946defined by the configuration file. 947Others have interpretations built into 948.i sendmail 949that cannot be changed without changing the code. 950These builtins are described here. 951.sh 3 "Return-receipt-to" 952.pp 953If this header is sent, 954a message will be sent to any specified addresses 955when the final delivery is complete. 956This is determined by the 957.b l 958flag in the mailer descriptor. 959.sh 3 "Errors-to" 960.pp 961If errors occur anywhere during processing, 962this header will cause error messages to go to 963the listed addresses 964rather than to the sender. 965This is intended for mailing lists. 966.sh 3 "Apparently-To: 967.pp 968If a message comes in with no recipients listed in the message 969(in a To:, Cc:, or Bcc: line) 970then 971.i sendmail 972will add an 973.q "Apparently-To:" 974header line for any recipients it is aware of. 975This is not put in as a standard recipient line 976to warn any recipients that the list is not complete. 977.pp 978At least one recipient line is required under RFC 822. 979.sh 1 "ARGUMENTS" 980.pp 981The complete list of arguments to 982.i sendmail 983is described in detail in Appendix A. 984Some important arguments are described here. 985.sh 2 "Queue Interval" 986.pp 987The amount of time between forking a process 988to run through the queue 989is defined by the 990.b \-q 991flag. 992If you run in mode 993.b f 994or 995.b a 996this can be relatively large, 997since it will only be relevant 998when a host that was down comes back up. 999If you run in 1000.b q 1001mode 1002it should be relatively short, 1003since it defines the maximum amount of time that a message 1004may sit in the queue. 1005.sh 2 "Daemon Mode" 1006.pp 1007If you allow incoming mail over an IPC connection, 1008you should have a daemon running. 1009This should be set by your 1010.i /etc/rc 1011file using the 1012.b \-bd 1013flag. 1014The 1015.b \-bd 1016flag and the 1017.b \-q 1018flag may be combined in one call: 1019.(b 1020/usr/lib/sendmail \-bd \-q10m 1021.)b 1022.sh 2 "Forcing the Queue" 1023.pp 1024In some cases you may find that the queue has gotten clogged for some reason. 1025You can force a queue run 1026using the 1027.b \-q 1028flag (with no value). 1029It is frequently entertaining to use the 1030.b \-v 1031flag (verbose) 1032when this is done to watch what happens: 1033.(b 1034/usr/lib/sendmail \-q \-v 1035.)b 1036.sh 2 "Debugging" 1037.pp 1038There are a fairly large number of debug flags 1039built into 1040.i sendmail . 1041Each debug flag has a number and a level, 1042where higher levels means to print out more information. 1043The convention is that levels greater than nine are 1044.q absurd, 1045i.e., 1046they print out so much information that you wouldn't normally 1047want to see them except for debugging that particular piece of code. 1048Debug flags are set using the 1049.b \-d 1050option; 1051the syntax is: 1052.(b 1053.ta \w'debug-option 'u 1054debug-flag: \fB\-d\fP debug-list 1055debug-list: debug-option [ , debug-option ] 1056debug-option: debug-range [ . debug-level ] 1057debug-range: integer | integer \- integer 1058debug-level: integer 1059.)b 1060where spaces are for reading ease only. 1061For example, 1062.(b 1063\-d12 Set flag 12 to level 1 1064\-d12.3 Set flag 12 to level 3 1065\-d3-17 Set flags 3 through 17 to level 1 1066\-d3-17.4 Set flags 3 through 17 to level 4 1067.)b 1068For a complete list of the available debug flags 1069you will have to look at the code 1070(they are too dynamic to keep this documentation up to date). 1071.sh 2 "Trying a Different Configuration File" 1072.pp 1073An alternative configuration file 1074can be specified using the 1075.b \-C 1076flag; for example, 1077.(b 1078/usr/lib/sendmail \-Ctest.cf 1079.)b 1080uses the configuration file 1081.i test.cf 1082instead of the default 1083.i /usr/lib/sendmail.cf. 1084If the 1085.b \-C 1086flag has no value 1087it defaults to 1088.i sendmail.cf 1089in the current directory. 1090.sh 2 "Changing the Values of Options" 1091.pp 1092Options can be overridden using the 1093.b \-o 1094flag. 1095For example, 1096.(b 1097/usr/lib/sendmail \-oT2m 1098.)b 1099sets the 1100.b T 1101(timeout) option to two minutes 1102for this run only. 1103.sh 1 "TUNING" 1104.pp 1105There are a number of configuration parameters 1106you may want to change, 1107depending on the requirements of your site. 1108Most of these are set 1109using an option in the configuration file. 1110For example, 1111the line 1112.q OT3d 1113sets option 1114.q T 1115to the value 1116.q 3d 1117(three days). 1118.sh 2 "Timeouts" 1119.pp 1120All time intervals are set 1121using a scaled syntax. 1122For example, 1123.q 10m 1124represents ten minutes, whereas 1125.q 2h30m 1126represents two and a half hours. 1127The full set of scales is: 1128.(b 1129.ta 4n 1130s seconds 1131m minutes 1132h hours 1133d days 1134w weeks 1135.)b 1136.sh 3 "Queue interval" 1137.pp 1138The argument to the 1139.b \-q 1140flag 1141specifies how often a subdaemon will run the queue. 1142This is typically set to between five minutes 1143and one half hour. 1144.sh 3 "Read timeouts" 1145.pp 1146It is possible to time out when reading the standard input 1147or when reading from a remote SMTP server. 1148Technically, 1149this is not acceptable within the published protocols. 1150However, 1151it might be appropriate to set it to something large 1152in certain environments 1153(such as an hour). 1154This will reduce the chance of large numbers of idle daemons 1155piling up on your system. 1156This timeout is set using the 1157.b r 1158option in the configuration file. 1159.sh 3 "Message timeouts" 1160.pp 1161After sitting in the queue for a few days, 1162a message will time out. 1163This is to insure that at least the sender is aware 1164of the inability to send a message. 1165The timeout is typically set to three days. 1166This timeout is set using the 1167.b T 1168option in the configuration file. 1169.pp 1170The time of submission is set in the queue, 1171rather than the amount of time left until timeout. 1172As a result, you can flush messages that have been hanging 1173for a short period 1174by running the queue 1175with a short message timeout. 1176For example, 1177.(b 1178/usr/lib/sendmail \-oT1d \-q 1179.)b 1180will run the queue 1181and flush anything that is one day old. 1182.sh 2 "Delivery Mode" 1183.pp 1184There are a number of delivery modes that 1185.i sendmail 1186can operate in, 1187set by the 1188.q d 1189configuration option. 1190These modes 1191specify how quickly mail will be delivered. 1192Legal modes are: 1193.(b 1194.ta 4n 1195i deliver interactively (synchronously) 1196b deliver in background (asynchronously) 1197q queue only (don't deliver) 1198.)b 1199There are tradeoffs. 1200Mode 1201.q i 1202passes the maximum amount of information to the sender, 1203but is hardly ever necessary. 1204Mode 1205.q q 1206puts the minimum load on your machine, 1207but means that delivery may be delayed for up to the queue interval. 1208Mode 1209.q b 1210is probably a good compromise. 1211However, this mode can cause large numbers of processes 1212if you have a mailer that takes a long time to deliver a message. 1213.sh 2 "Log Level" 1214.pp 1215The level of logging can be set for sendmail. 1216The default using a standard configuration table is level 9. 1217The levels are as follows: 1218.ip 0 1219No logging. 1220.ip 1 1221Major problems only. 1222.ip 2 1223Message collections and failed deliveries. 1224.ip 3 1225Successful deliveries. 1226.ip 4 1227Messages being defered 1228(due to a host being down, etc.). 1229.ip 5 1230Normal message queueups. 1231.ip 6 1232Unusual but benign incidents, 1233e.g., 1234trying to process a locked queue file. 1235.ip 9 1236Log internal queue id to external message id mappings. 1237This can be useful for tracing a message 1238as it travels between several hosts. 1239.ip 12 1240Several messages that are basically only of interest 1241when debugging. 1242.ip 16 1243Verbose information regarding the queue. 1244.sh 2 "File Modes" 1245.pp 1246There are a number of files 1247that may have a number of modes. 1248The modes depend on what functionality you want 1249and the level of security you require. 1250.sh 3 "To suid or not to suid?" 1251.pp 1252.i Sendmail 1253can safely be made 1254setuid to root. 1255At the point where it is about to 1256.i exec \|(2) 1257a mailer, 1258it checks to see if the userid is zero; 1259if so, 1260it resets the userid and groupid to a default 1261(set by the 1262.b u 1263and 1264.b g 1265options). 1266(This can be overridden 1267by setting the 1268.b S 1269flag to the mailer 1270for mailers that are trusted 1271and must be called as root.) 1272However, 1273this will cause mail processing 1274to be accounted 1275(using 1276.i sa \|(8)) 1277to root 1278rather than to the user sending the mail. 1279.sh 3 "Temporary file modes" 1280.pp 1281The mode of all temporary files that 1282.i sendmail 1283creates is determined by the 1284.q F 1285option. 1286Reasonable values for this option are 12870600 1288and 12890644. 1290If the more permissive mode is selected, 1291it will not be necessary to run 1292.i sendmail 1293as root at all 1294(even when running the queue). 1295.sh 3 "Should my alias database be writable?" 1296.pp 1297At Berkeley 1298we have the alias database 1299(/usr/lib/aliases*) 1300mode 666. 1301There are some dangers inherent in this approach: 1302any user can add him-/her-self 1303to any list, 1304or can 1305.q steal 1306any other user's mail. 1307However, 1308we have found users to be basically trustworthy, 1309and the cost of having a read-only database 1310greater than the expense of finding and eradicating 1311the rare nasty person. 1312.pp 1313The database that 1314.i sendmail 1315actually used 1316is represented by the two files 1317.i aliases.dir 1318and 1319.i aliases.pag 1320(both in /usr/lib). 1321The mode on these files should match the mode 1322on /usr/lib/aliases. 1323If 1324.i aliases 1325is writable 1326and the 1327DBM 1328files 1329(\c 1330.i aliases.dir 1331and 1332.i aliases.pag ) 1333are not, 1334users will be unable to reflect their desired changes 1335through to the actual database. 1336However, 1337if 1338.i aliases 1339is read-only 1340and the DBM files are writable, 1341a slightly sophisticated user 1342can arrange to steal mail anyway. 1343.pp 1344If your DBM files are not writable by the world 1345or you do not have auto-rebuild enabled 1346(with the 1347.q D 1348option), 1349then you must be careful to reconstruct the alias database 1350each time you change the text version: 1351.(b 1352newaliases 1353.)b 1354If this step is ignored or forgotten 1355any intended changes will also be ignored or forgotten. 1356.sh 1 "THE WHOLE SCOOP ON THE CONFIGURATION FILE" 1357.pp 1358This section describes the configuration file 1359in detail, 1360including hints on how to write one of your own 1361if you have to. 1362.pp 1363There is one point that should be made clear immediately: 1364the syntax of the configuration file 1365is designed to be reasonably easy to parse, 1366since this is done every time 1367.i sendmail 1368starts up, 1369rather than easy for a human to read or write. 1370On the 1371.q "future project" 1372list is a 1373configuration-file compiler. 1374.pp 1375An overview of the configuration file 1376is given first, 1377followed by details of the semantics. 1378.sh 2 "The Syntax" 1379.pp 1380The configuration file is organized as a series of lines, 1381each of which begins with a single character 1382defining the semantics for the rest of the line. 1383Lines beginning with a space or a tab 1384are continuation lines 1385(although the semantics are not well defined in many places). 1386Blank lines and lines beginning with a sharp symbol 1387(`#') 1388are comments. 1389.sh 3 "R and S \*- rewriting rules" 1390.pp 1391The core of address parsing 1392are the rewriting rules. 1393These are an ordered production system. 1394.i Sendmail 1395scans through the set of rewriting rules 1396looking for a match on the left hand side 1397(LHS) 1398of the rule. 1399When a rule matches, 1400the address is replaced by the right hand side 1401(RHS) 1402of the rule. 1403.pp 1404There are several sets of rewriting rules. 1405Some of the rewriting sets are used internally 1406and must have specific semantics. 1407Other rewriting sets 1408do not have specifically assigned semantics, 1409and may be referenced by the mailer definitions 1410or by other rewriting sets. 1411.pp 1412The syntax of these two commands are: 1413.(b F 1414.b S \c 1415.i n 1416.)b 1417Sets the current ruleset being collected to 1418.i n . 1419If you begin a ruleset more than once 1420it deletes the old definition. 1421.(b F 1422.b R \c 1423.i lhs 1424.i rhs 1425.i comments 1426.)b 1427The 1428fields must be separated 1429by at least one tab character; 1430there may be embedded spaces 1431in the fields. 1432The 1433.i lhs 1434is a pattern that is applied to the input. 1435If it matches, 1436the input is rewritten to the 1437.i rhs . 1438The 1439.i comments 1440are ignored. 1441.sh 3 "D \*- define macro" 1442.pp 1443Macros are named with a single character. 1444These may be selected from the entire ASCII set, 1445but user-defined macros 1446should be selected from the set of upper case letters only. 1447Lower case letters 1448and special symbols 1449are used internally. 1450.pp 1451The syntax for macro definitions is: 1452.(b F 1453.b D \c 1454.i x\|val 1455.)b 1456where 1457.i x 1458is the name of the macro 1459and 1460.i val 1461is the value it should have. 1462Macros can be interpolated in most places using the escape sequence 1463.b $ \c 1464.i x . 1465.sh 3 "C and F \*- define classes" 1466.pp 1467Classes of words may be defined 1468to match on the left hand side of rewriting rules. 1469For example 1470a class of all local names for this site 1471might be created 1472so that attempts to send to oneself 1473can be eliminated. 1474These can either be defined directly in the configuration file 1475or read in from another file. 1476Classes may be given names 1477from the set of upper case letters. 1478Lower case letters and special characters 1479are reserved for system use. 1480.pp 1481The syntax is: 1482.(b F 1483.b C \c 1484.i c\|word1 1485.i word2... 1486.br 1487.b F \c 1488.i c\|file 1489[ 1490.i format 1491] 1492.)b 1493The first form defines the class 1494.i c 1495to match any of the named words. 1496It is permissible to split them among multiple lines; 1497for example, the two forms: 1498.(b 1499CHmonet ucbmonet 1500.)b 1501and 1502.(b 1503CHmonet 1504CHucbmonet 1505.)b 1506are equivalent. 1507The second form 1508reads the elements of the class 1509.i c 1510from the named 1511.i file ; 1512the 1513.i format 1514is a 1515.i scanf \|(3) 1516pattern 1517that should produce a single string. 1518.sh 3 "M \*- define mailer" 1519.pp 1520Programs and interfaces to mailers 1521are defined in this line. 1522The format is: 1523.(b F 1524.b M \c 1525.i name , 1526{\c 1527.i field =\c 1528.i value \|}* 1529.)b 1530where 1531.i name 1532is the name of the mailer 1533(used internally only) 1534and the 1535.q field=name 1536pairs define attributes of the mailer. 1537Fields are: 1538.(b 1539.ta 1i 1540Path The pathname of the mailer 1541Flags Special flags for this mailer 1542Sender A rewriting set for sender addresses 1543Recipient A rewriting set for recipient addresses 1544Argv An argument vector to pass to this mailer 1545Eol The end-of-line string for this mailer 1546Maxsize The maximum message length to this mailer 1547.)b 1548Only the first character of the field name is checked. 1549.sh 3 "H \*- define header" 1550.pp 1551The format of the header lines that sendmail inserts into the message 1552are defined by the 1553.b H 1554line. 1555The syntax of this line is: 1556.(b F 1557.b H [\c 1558.b ? \c 1559.i mflags \c 1560.b ? ]\c 1561.i hname \c 1562.b : 1563.i htemplate 1564.)b 1565Continuation lines in this spec 1566are reflected directly into the outgoing message. 1567The 1568.i htemplate 1569is macro expanded before insertion into the message. 1570If the 1571.i mflags 1572(surrounded by question marks) 1573are specified, 1574at least one of the specified flags 1575must be stated in the mailer definition 1576for this header to be automatically output. 1577If one of these headers is in the input 1578it is reflected to the output 1579regardless of these flags. 1580.pp 1581Some headers have special semantics 1582that will be described below. 1583.sh 3 "O \*- set option" 1584.pp 1585There are a number of 1586.q random 1587options that 1588can be set from a configuration file. 1589Options are represented by single characters. 1590The syntax of this line is: 1591.(b F 1592.b O \c 1593.i o\|value 1594.)b 1595This sets option 1596.i o 1597to be 1598.i value . 1599Depending on the option, 1600.i value 1601may be a string, an integer, 1602a boolean 1603(with legal values 1604.q t , 1605.q T , 1606.q f , 1607or 1608.q F ; 1609the default is TRUE), 1610or 1611a time interval. 1612.sh 3 "T \*- define trusted users" 1613.pp 1614Trusted users 1615are those users who are permitted 1616to override the sender address 1617using the 1618.b \-f 1619flag. 1620These typically are 1621.q root, 1622.q uucp, 1623and 1624.q network, 1625but on some users it may be convenient 1626to extend this list to include other users, 1627perhaps to support 1628a separate 1629UUCP 1630login for each host. 1631The syntax of this line is: 1632.(b F 1633.b T \c 1634.i user1 1635.i user2 ... 1636.)b 1637There may be more than one of these lines. 1638.sh 3 "P \*- precedence definitions" 1639.pp 1640Values for the 1641.q "Precedence:" 1642field may be defined using the 1643.b P 1644control line. 1645The syntax of this field is: 1646.(b 1647\fBP\fP\fIname\fP\fB=\fP\fInum\fP 1648.)b 1649When the 1650.i name 1651is found in a 1652.q Precedence: 1653field, 1654the message class is set to 1655.i num . 1656Higher numbers mean higher precedence. 1657Numbers less than zero 1658have the special property 1659that error messages will not be returned. 1660The default precedence is zero. 1661For example, 1662our list of precedences is: 1663.(b 1664Pfirst-class=0 1665Pspecial-delivery=100 1666Pjunk=\-100 1667.)b 1668.sh 2 "The Semantics" 1669.pp 1670This section describes the semantics of the configuration file. 1671.sh 3 "Special macros, conditionals" 1672.pp 1673Macros are interpolated 1674using the construct 1675.b $ \c 1676.i x , 1677where 1678.i x 1679is the name of the macro to be interpolated. 1680In particular, 1681lower case letters are reserved to have 1682special semantics, 1683used to pass information in or out of sendmail, 1684and some special characters are reserved to 1685provide conditionals, etc. 1686.pp 1687The following macros 1688.i must 1689be defined to transmit information into 1690.i sendmail: 1691.(b 1692.ta 4n 1693e The SMTP entry message 1694j The \*(lqofficial\*(rq domain name for this site 1695l The format of the UNIX from line 1696n The name of the daemon (for error messages) 1697o The set of "operators" in addresses 1698q default format of sender address 1699.)b 1700The 1701.b $e 1702macro is printed out when SMTP starts up. 1703The first word must be the 1704.b $j 1705macro. 1706The 1707.b $j 1708macro 1709should be in RFC821 format. 1710The 1711.b $l 1712and 1713.b $n 1714macros can be considered constants 1715except under terribly unusual circumstances. 1716The 1717.b $o 1718macro consists of a list of characters 1719which will be considered tokens 1720and which will separate tokens 1721when doing parsing. 1722For example, if 1723.q r 1724were in the 1725.b $o 1726macro, then the input 1727.q address 1728would be scanned as three tokens: 1729.q add, 1730.q r, 1731and 1732.q ess. 1733Finally, the 1734.b $q 1735macro specifies how an address should appear in a message 1736when it is defaulted. 1737For example, on our system these definitions are: 1738.(b 1739De$j Sendmail $v ready at $b 1740DnMAILER-DAEMON 1741DlFrom $g $d 1742Do.:%@!^=/ 1743Dq$g$?x ($x)$. 1744Dj$H.$D 1745.)b 1746An acceptable alternative for the 1747.b $q 1748macro is 1749.q "$?x$x $.<$g>" . 1750These correspond to the following two formats: 1751.(b 1752eric@Berkeley (Eric Allman) 1753Eric Allman <eric@Berkeley> 1754.)b 1755.pp 1756Some macros are defined by 1757.i sendmail 1758for interpolation into argv's for mailers 1759or for other contexts. 1760These macros are: 1761.(b 1762a The origination date in Arpanet format 1763b The current date in Arpanet format 1764c The hop count 1765d The date in UNIX (ctime) format 1766f The sender (from) address 1767g The sender address relative to the recipient 1768h The recipient host 1769i The queue id 1770p Sendmail's pid 1771r Protocol used 1772s Sender's host name 1773t A numeric representation of the current time 1774u The recipient user 1775v The version number of sendmail 1776w The hostname of this site 1777x The full name of the sender 1778y The id of the sender's tty 1779z The home directory of the recipient 1780.)b 1781.pp 1782There are three types of dates that can be used. 1783The 1784.b $a 1785and 1786.b $b 1787macros are in Arpanet format; 1788.b $a 1789is the time as extracted from the 1790.q Date: 1791line of the message 1792(if there was one), 1793and 1794.b $b 1795is the current date and time 1796(used for postmarks). 1797If no 1798.q Date: 1799line is found in the incoming message, 1800.b $a 1801is set to the current time also. 1802The 1803.b $d 1804macro is equivalent to the 1805.b $a 1806macro in UNIX 1807(ctime) 1808format. 1809.pp 1810The 1811.b $f 1812macro is the id of the sender 1813as originally determined; 1814when mailing to a specific host 1815the 1816.b $g 1817macro is set to the address of the sender 1818.ul 1819relative to the recipient. 1820For example, 1821if I send to 1822.q bollard@matisse 1823from the machine 1824.q ucbarpa 1825the 1826.b $f 1827macro will be 1828.q eric 1829and the 1830.b $g 1831macro will be 1832.q eric@ucbarpa. 1833.pp 1834The 1835.b $x 1836macro is set to the full name of the sender. 1837This can be determined in several ways. 1838It can be passed as flag to 1839.i sendmail. 1840The second choice is the value of the 1841.q Full-name: 1842line in the header if it exists, 1843and the third choice is the comment field 1844of a 1845.q From: 1846line. 1847If all of these fail, 1848and if the message is being originated locally, 1849the full name is looked up in the 1850.i /etc/passwd 1851file. 1852.pp 1853When sending, 1854the 1855.b $h , 1856.b $u , 1857and 1858.b $z 1859macros get set to the host, user, and home directory 1860(if local) 1861of the recipient. 1862The first two are set from the 1863.b $@ 1864and 1865.b $: 1866part of the rewriting rules, respectively. 1867.pp 1868The 1869.b $p 1870and 1871.b $t 1872macros are used to create unique strings 1873(e.g., for the 1874.q Message-Id: 1875field). 1876The 1877.b $i 1878macro is set to the queue id on this host; 1879if put into the timestamp line 1880it can be extremely useful for tracking messages. 1881The 1882.b $y 1883macro is set to the id of the terminal of the sender 1884(if known); 1885some systems like to put this 1886in the Unix 1887.q From 1888line. 1889The 1890.b $v 1891macro is set to be the version number of 1892.i sendmail ; 1893this is normally put in timestamps 1894and has been proven extremely useful for debugging. 1895The 1896.b $w 1897macro is set to the name of this host 1898if it can be determined. 1899The 1900.b $c 1901field is set to the 1902.q "hop count," 1903i.e., the number of times this message has been processed. 1904This can be determined 1905by the 1906.b \-h 1907flag on the command line 1908or by counting the timestamps in the message. 1909.pp 1910The 1911.b $r 1912and 1913.b $s 1914fields are set to the protocol used to communicate with sendmail 1915and the sending hostname; 1916these are not supported in the current version. 1917.pp 1918Conditionals can be specified using the syntax: 1919.(b 1920$?x text1 $| text2 $. 1921.)b 1922This interpolates 1923.i text1 1924if the macro 1925.b $x 1926is set, 1927and 1928.i text2 1929otherwise. 1930The 1931.q else 1932(\c 1933.b $| ) 1934clause may be omitted. 1935.sh 3 "Special classes" 1936.pp 1937The class 1938.b $=w 1939is set to be the set of all names 1940this host is known by. 1941This can be used to delete local hostnames. 1942.sh 3 "The left hand side" 1943.pp 1944The left hand side of rewriting rules contains a pattern. 1945Normal words are simply matched directly. 1946Metasyntax is introduced using a dollar sign. 1947The metasymbols are: 1948.(b 1949.ta \w'\fB$=\fP\fIx\fP 'u 1950\fB$*\fP Match zero or more tokens 1951\fB$+\fP Match one or more tokens 1952\fB$\-\fP Match exactly one token 1953\fB$=\fP\fIx\fP Match any token in class \fIx\fP 1954\fB$~\fP\fIx\fP Match any token not in class \fIx\fP 1955.)b 1956If any of these match, 1957they are assigned to the symbol 1958.b $ \c 1959.i n 1960for replacement on the right hand side, 1961where 1962.i n 1963is the index in the LHS. 1964For example, 1965if the LHS: 1966.(b 1967$\-:$+ 1968.)b 1969is applied to the input: 1970.(b 1971UCBARPA:eric 1972.)b 1973the rule will match, and the values passed to the RHS will be: 1974.(b 1975.ta 4n 1976$1 UCBARPA 1977$2 eric 1978.)b 1979.sh 3 "The right hand side" 1980.pp 1981When the right hand side of a rewriting rule matches, 1982the input is deleted and replaced by the right hand side. 1983Tokens are copied directly from the RHS 1984unless they are begin with a dollar sign. 1985Metasymbols are: 1986.(b 1987.ta \w'$#mailer 'u 1988\fB$\fP\fIn\fP Substitute indefinite token \fIn\fP from LHS 1989\fB$>\fP\fIn\fP \*(lqCall\*(rq ruleset \fIn\fP 1990\fB$#\fP\fImailer\fP Resolve to \fImailer\fP 1991\fB$@\fP\fIhost\fP Specify \fIhost\fP 1992\fB$:\fP\fIuser\fP Specify \fIuser\fP 1993.)b 1994.pp 1995The 1996.b $ \c 1997.i n 1998syntax substitutes the corresponding value from a 1999.b $+ , 2000.b $\- , 2001.b $* , 2002.b $= , 2003or 2004.b $~ 2005match on the LHS. 2006It may be used anywhere. 2007.pp 2008The 2009.b $> \c 2010.i n 2011syntax 2012causes the remainder of the line to be substituted as usual 2013and then passed as the argument to ruleset 2014.i n . 2015The final value of ruleset 2016.i n 2017then becomes 2018the substitution for this rule. 2019.pp 2020The 2021.b $# 2022syntax should 2023.i only 2024be used in ruleset zero. 2025It causes evaluation of the ruleset to terminate immediately, 2026and signals to sendmail that the address has completely resolved. 2027The complete syntax is: 2028.(b 2029\fB$#\fP\fImailer\fP\fB$@\fP\fIhost\fP\fB$:\fP\fIuser\fP 2030.)b 2031This specifies the 2032{mailer, host, user} 20333-tuple necessary to direct the mailer. 2034If the mailer is local 2035the host part may be omitted. 2036The 2037.i mailer 2038and 2039.i host 2040must be a single word, 2041but the 2042.i user 2043may be multi-part. 2044.pp 2045A RHS may also be preceeded by a 2046.b $@ 2047or a 2048.b $: 2049to control evaluation. 2050A 2051.b $@ 2052prefix causes the ruleset to return with the remainder of the RHS 2053as the value. 2054A 2055.b $: 2056prefix causes the rule to terminate immediately, 2057but the ruleset to continue; 2058this can be used to avoid continued application of a rule. 2059The prefix is stripped before continuing. 2060.pp 2061The 2062.b $@ 2063and 2064.b $: 2065prefixes may preceed a 2066.b $> 2067spec; 2068for example: 2069.(b 2070.ta 8n 2071R$+ $:$>7$1 2072.)b 2073matches anything, 2074passes that to ruleset seven, 2075and continues; 2076the 2077.b $: 2078is necessary to avoid an infinite loop. 2079.sh 3 "Semantics of rewriting rule sets" 2080.pp 2081There are five rewriting sets 2082that have specific semantics. 2083These are related as depicted by figure 2. 2084.(z 2085.hl 2086.ie t .sp 2i 2087.el \{\ 2088.(c 2089 +---+ 2090 -->| 0 |-->resolved address 2091 / +---+ 2092 / +---+ +---+ 2093 / ---->| 1 |-->| S |-- 2094 +---+ / +---+ / +---+ +---+ \e +---+ 2095addr-->| 3 |-->| D |-- --->| 4 |-->msg 2096 +---+ +---+ \e +---+ +---+ / +---+ 2097 --->| 2 |-->| R |-- 2098 +---+ +---+ 2099.)c 2100 2101.ce 2102Figure 2 \*- Rewriting set semantics 2103.(c 2104D \*- sender domain addition 2105S \*- mailer-specific sender rewriting 2106R \*- mailer-specific recipient rewriting 2107.)c 2108.\} 2109.hl 2110.)z 2111.pp 2112Ruleset three 2113should turn the address into 2114.q "canonical form." 2115This form should have the basic syntax: 2116.(b 2117local-part@host-domain-spec 2118.)b 2119If no 2120.q @ 2121sign is specified, 2122then the 2123host-domain-spec 2124.i may 2125be appended from the 2126sender address 2127(if the 2128.b C 2129flag is set in the mailer definition 2130corresponding to the 2131.i sending 2132mailer). 2133Ruleset three 2134is applied by sendmail 2135before doing anything with any address. 2136.pp 2137Ruleset zero 2138is applied after ruleset three 2139to addresses that are going to actually specify recipients. 2140It must resolve to a 2141.i "{mailer, host, user}" 2142triple. 2143The 2144.i mailer 2145must be defined in the mailer definitions 2146from the configuration file. 2147The 2148.i host 2149is defined into the 2150.b $h 2151macro 2152for use in the argv expansion of the specified mailer. 2153.pp 2154Rulesets one and two 2155are applied to all sender and recipient addresses respectively. 2156They are applied before any specification 2157in the mailer definition. 2158They must never resolve. 2159.pp 2160Ruleset four is applied to all addresses 2161in the message. 2162It is typically used 2163to translate internal to external form. 2164.sh 3 "Mailer flags etc." 2165.pp 2166There are a number of flags that may be associated with each mailer, 2167each identified by a letter of the alphabet. 2168Many of them are assigned semantics internally. 2169These are detailed in Appendix C. 2170Any other flags may be used freely 2171to conditionally assign headers to messages 2172destined for particular mailers. 2173.sh 3 "The \*(lqerror\*(rq mailer" 2174.pp 2175The mailer with the special name 2176.q error 2177can be used to generate a user error. 2178The (optional) host field is a numeric exit status to be returned, 2179and the user field is a message to be printed. 2180For example, the entry: 2181.(b 2182$#error$:Host unknown in this domain 2183.)b 2184on the RHS of a rule 2185will cause the specified error to be generated 2186if the LHS matches. 2187This mailer is only functional in ruleset zero. 2188.sh 2 "Building a Configuration File From Scratch" 2189.pp 2190Building a configuration table from scratch is an extremely difficult job. 2191Fortunately, 2192it is almost never necessary to do so; 2193nearly every situation that may come up 2194may be resolved by changing an existing table. 2195In any case, 2196it is critical that you understand what it is that you are trying to do 2197and come up with a philosophy for the configuration table. 2198This section is intended to explain what the real purpose 2199of a configuration table is 2200and to give you some ideas 2201for what your philosophy might be. 2202.sh 3 "What you are trying to do" 2203.pp 2204The configuration table has three major purposes. 2205The first and simplest 2206is to set up the environment for 2207.i sendmail . 2208This involves setting the options, 2209defining a few critical macros, 2210etc. 2211Since these are described in other places, 2212we will not go into more detail here. 2213.pp 2214The second purpose is to rewrite addresses in the message. 2215This should typically be done in two phases. 2216The first phase maps addresses in any format 2217into a canonical form. 2218This should be done in ruleset three. 2219The second phase maps this canonical form 2220into the syntax appropriate for the receiving mailer. 2221.i Sendmail 2222does this in three subphases. 2223Rulesets one and two 2224are applied to all sender and recipient addresses respectively. 2225After this, 2226you may specify per-mailer rulesets 2227for both sender and recipient addresses; 2228this allows mailer-specific customization. 2229Finally, 2230ruleset four is applied to do any default conversion 2231to external form. 2232.pp 2233The third purpose 2234is to map addresses into the actual set of instructions 2235necessary to get the message delivered. 2236Ruleset zero must resolve to the internal form, 2237which is in turn used as a pointer to a mailer descriptor. 2238The mailer descriptor describes the interface requirements 2239of the mailer. 2240.sh 3 "Philosophy" 2241.pp 2242The particular philosophy you choose will depend heavily 2243on the size and structure of your organization. 2244I will present a few possible philosophies here. 2245.pp 2246One general point applies to all of these philosophies: 2247it is almost always a mistake 2248to try to do full name resolution. 2249For example, 2250if you are trying to get names of the form 2251.q user@host 2252to the Arpanet, 2253it does not pay to route them to 2254.q xyzvax!decvax!ucbvax!c70:user@host 2255since you then depend on several links not under your control. 2256The best approach to this problem 2257is to simply forward to 2258.q xyzvax!user@host 2259and let xyzvax 2260worry about it from there. 2261In summary, 2262just get the message closer to the destination, 2263rather than determining the full path. 2264.sh 4 "Large site, many hosts \*- minimum information" 2265.pp 2266Berkeley is an example of a large site, 2267i.e., more than two or three hosts. 2268We have decided that the only reasonable philosophy 2269in our environment 2270is to designate one host as the guru for our site. 2271It must be able to resolve any piece of mail it receives. 2272The other sites should have the minimum amount of information 2273they can get away with. 2274In addition, 2275any information they do have 2276should be hints rather than solid information. 2277.pp 2278For example, 2279a typical site on our local ether network is 2280.q monet. 2281Monet has a list of known ethernet hosts; 2282if it receives mail for any of them, 2283it can do direct delivery. 2284If it receives mail for any unknown host, 2285it just passes it directly to 2286.q ucbvax, 2287our master host. 2288Ucbvax may determine that the host name is illegal 2289and reject the message, 2290or may be able to do delivery. 2291However, it is important to note that when a new ethernet host is added, 2292the only host that 2293.i must 2294have its tables updated 2295is ucbvax; 2296the others 2297.i may 2298be updated as convenient, 2299but this is not critical. 2300.pp 2301This picture is slightly muddied 2302due to network connections that are not actually located 2303on ucbvax. 2304For example, 2305our TCP connection is currently on 2306.q ucbarpa. 2307However, 2308monet 2309.i "does not" 2310know about this; 2311the information is hidden totally between ucbvax and ucbarpa. 2312Mail going from monet to a TCP host 2313is transfered via the ethernet 2314from monet to ucbvax, 2315then via the ethernet from ucbvax to ucbarpa, 2316and then is submitted to the Arpanet. 2317Although this involves some extra hops, 2318we feel this is an acceptable tradeoff. 2319.pp 2320An interesting point is that it would be possible 2321to update monet 2322to send TCP mail directly to ucbarpa 2323if the load got too high; 2324if monet failed to note a host as a TCP host 2325it would go via ucbvax as before, 2326and if monet incorrectly sent a message to ucbarpa 2327it would still be sent by ucbarpa 2328to ucbvax as before. 2329The only problem that can occur is loops, 2330as if ucbarpa thought that ucbvax had the TCP connection 2331and vice versa. 2332For this reason, 2333updates should 2334.i always 2335happen to the master host first. 2336.pp 2337This philosophy results as much from the need 2338to have a single source for the configuration files 2339(typically built using 2340.i m4 \|(1) 2341or some similar tool) 2342as any logical need. 2343Maintaining more than three separate tables by hand 2344is essentially an impossible job. 2345.sh 4 "Small site \*- complete information" 2346.pp 2347A small site 2348(two or three hosts) 2349may find it more reasonable to have complete information 2350at each host. 2351This would require that each host 2352know exactly where each network connection is, 2353possibly including the names of each host on that network. 2354As long as the site remains small 2355and the the configuration remains relatively static, 2356the update problem will probably not be too great. 2357.sh 4 "Single host" 2358.pp 2359This is in some sense the trivial case. 2360The only major issue is trying to insure that you don't 2361have to know too much about your environment. 2362For example, 2363if you have a UUCP connection 2364you might find it useful to know about the names of hosts 2365connected directly to you, 2366but this is really not necessary 2367since this may be determined from the syntax. 2368.sh 3 "Relevant issues" 2369.pp 2370The canonical form you use 2371should almost certainly be as specified in 2372the Arpanet protocols 2373RFC819 and RFC822. 2374Copies of these RFC's are included on the 2375.i sendmail 2376tape 2377as 2378.i doc/rfc819.lpr 2379and 2380.i doc/rfc822.lpr . 2381.pp 2382RFC822 2383describes the format of the mail message itself. 2384.i Sendmail 2385follows this RFC closely, 2386to the extent that many of the standards described in this document 2387can not be changed without changing the code. 2388In particular, 2389the following characters have special interpretations: 2390.(b 2391< > ( ) " \e 2392.)b 2393Any attempt to use these characters for other than their RFC822 2394purpose in addresses is probably doomed to disaster. 2395.pp 2396RFC819 2397describes the specifics of the domain-based addressing. 2398This is touched on in RFC822 as well. 2399Essentially each host is given a name 2400which is a right-to-left dot qualified pseudo-path 2401from a distinguished root. 2402The elements of the path need not be physical hosts; 2403the domain is logical rather than physical. 2404For example, 2405at Berkeley 2406one legal host is 2407.q a.cc.berkeley.arpa ; 2408reading from right to left, 2409.q arpa 2410is a top level domain 2411(related to, but not limited to, the physical Arpanet), 2412.q berkeley 2413is both an Arpanet host and a logical domain 2414which is actually interpreted by 2415a host called ucbvax 2416(which is actually just the 2417.q "major" 2418host for this domain), 2419.q cc 2420represents the Computer Center, 2421(in this case a strictly logical entity), 2422and 2423.q a 2424is a host in the Computer Center; 2425this particular host happens to be connected 2426via berknet, 2427but other hosts might be connected via one of two ethernets 2428or some other network. 2429.pp 2430Beware when reading RFC819 2431that there are a number of errors in it. 2432.sh 3 "How to proceed" 2433.pp 2434Once you have decided on a philosophy, 2435it is worth examining the available configuration tables 2436to decide if any of them are close enough 2437to steal major parts of. 2438Even under the worst of conditions, 2439there is a fair amount of boiler plate that can be collected safely. 2440.pp 2441The next step is to build ruleset three. 2442This will be the hardest part of the job. 2443Beware of doing too much to the address in this ruleset, 2444since anything you do will reflect through 2445to the message. 2446In particular, 2447stripping of local domains is best deferred, 2448since this can leave you with addresses with no domain spec at all. 2449Since 2450.i sendmail 2451likes to append the sending domain to addresses with no domain, 2452this can change the semantics of addresses. 2453Also try to avoid 2454fully qualifying domains in this ruleset. 2455Although technically legal, 2456this can lead to unpleasantly and unnecessarily long addresses 2457reflected into messages. 2458The Berkeley configuration files 2459define ruleset nine 2460to qualify domain names and strip local domains. 2461This is called from ruleset zero 2462to get all addresses into a cleaner form. 2463.pp 2464Once you have ruleset three finished, 2465the other rulesets should be relatively trivial. 2466If you need hints, 2467examine the supplied configuration tables. 2468.sh 3 "Testing the rewriting rules \*- the \-bt flag" 2469.pp 2470When you build a configuration table, 2471you can do a certain amount of testing 2472using the 2473.q "test mode" 2474of 2475.i sendmail . 2476For example, 2477you could invoke 2478.i sendmail 2479as: 2480.(b 2481sendmail \-bt \-Ctest.cf 2482.)b 2483which would read the configuration file 2484.q test.cf 2485and enter test mode. 2486In this mode, 2487you enter lines of the form: 2488.(b 2489rwset address 2490.)b 2491where 2492.i rwset 2493is the rewriting set you want to use 2494and 2495.i address 2496is an address to apply the set to. 2497Test mode shows you the steps it takes 2498as it proceeds, 2499finally showing you the address it ends up with. 2500You may use a comma separated list of rwsets 2501for sequential application of rules to an input; 2502ruleset three is always applied first. 2503For example: 2504.(b 25051,21,4 monet:bollard 2506.)b 2507first applies ruleset three to the input 2508.q monet:bollard. 2509Ruleset one is then applied to the output of ruleset three, 2510followed similarly by rulesets twenty-one and four. 2511.pp 2512If you need more detail, 2513you can also use the 2514.q \-d21 2515flag to turn on more debugging. 2516For example, 2517.(b 2518sendmail \-bt \-d21.99 2519.)b 2520turns on an incredible amount of information; 2521a single word address 2522is probably going to print out several pages worth of information. 2523.sh 3 "Building mailer descriptions" 2524.pp 2525To add an outgoing mailer to your mail system, 2526you will have to define the characteristics of the mailer. 2527.pp 2528Each mailer must have an internal name. 2529This can be arbitrary, 2530except that the names 2531.q local 2532and 2533.q prog 2534must be defined. 2535.pp 2536The pathname of the mailer must be given in the P field. 2537If this mailer should be accessed via an IPC connection, 2538use the string 2539.q [IPC] 2540instead. 2541.pp 2542The F field defines the mailer flags. 2543You should specify an 2544.q f 2545or 2546.q r 2547flag to pass the name of the sender as a 2548.b \-f 2549or 2550.b \-r 2551flag respectively. 2552These flags are only passed if they were passed to 2553.i sendmail, 2554so that mailers that give errors under some circumstances 2555can be placated. 2556If the mailer is not picky 2557you can just specify 2558.q "\-f $g" 2559in the argv template. 2560If the mailer must be called as 2561.b root 2562the 2563.q S 2564flag should be given; 2565this will not reset the userid 2566before calling the mailer\**. 2567.(f 2568\**\c 2569.i Sendmail 2570must be running setuid to root 2571for this to work. 2572.)f 2573If this mailer is local 2574(i.e., will perform final delivery 2575rather than another network hop) 2576the 2577.q l 2578flag should be given. 2579Quote characters 2580(backslashes and " marks) 2581can be stripped from addresses if the 2582.q s 2583flag is specified; 2584if this is not given 2585they are passed through. 2586If the mailer is capable of sending to more than one user 2587on the same host 2588in a single transaction 2589the 2590.q m 2591flag should be stated. 2592If this flag is on, 2593then the argv template containing 2594.b $u 2595will be repeated for each unique user 2596on a given host. 2597The 2598.q e 2599flag will mark the mailer as being 2600.q expensive, 2601which will cause 2602.i sendmail 2603to defer connection 2604until a queue run\**. 2605.(f 2606\**The 2607.q c 2608configuration option must be given 2609for this to be effective. 2610.)f 2611.pp 2612An unusual case is the 2613.q C 2614flag. 2615This flag applies to the mailer that the message is received from, 2616rather than the mailer being sent to; 2617if set, 2618the domain spec of the sender 2619(i.e., the 2620.q @host.domain 2621part) 2622is saved 2623and is appended to any addresses in the message 2624that do not already contain a domain spec. 2625For example, 2626a message of the form: 2627.(b 2628From: eric@ucbarpa 2629To: wnj@monet, mckusick 2630.)b 2631will be modified to: 2632.(b 2633From: eric@ucbarpa 2634To: wnj@monet, mckusick@ucbarpa 2635.)b 2636.i "if and only if" 2637the 2638.q C 2639flag is defined in the mailer corresponding to 2640.q eric@ucbarpa. 2641.pp 2642Other flags are described 2643in Appendix C. 2644.pp 2645The S and R fields in the mailer description 2646are per-mailer rewriting sets 2647to be applied to sender and recipient addresses 2648respectively. 2649These are applied after the sending domain is appended 2650and the general rewriting sets 2651(numbers one and two) 2652are applied, 2653but before the output rewrite 2654(ruleset four) 2655is applied. 2656A typical use is to append the current domain 2657to addresses that do not already have a domain. 2658For example, 2659a header of the form: 2660.(b 2661From: eric 2662.)b 2663might be changed to be: 2664.(b 2665From: eric@ucbarpa 2666.)b 2667or 2668.(b 2669From: ucbvax!eric 2670.)b 2671depending on the domain it is being shipped into. 2672These sets can also be used 2673to do special purpose output rewriting 2674in cooperation with ruleset four. 2675.pp 2676The E field defines the string to use 2677as an end-of-line indication. 2678A string containing only newline is the default. 2679The usual backslash escapes 2680(\er, \en, \ef, \eb) 2681may be used. 2682.pp 2683Finally, 2684an argv template is given as the E field. 2685It may have embedded spaces. 2686If there is no argv with a 2687.b $u 2688macro in it, 2689.i sendmail 2690will speak SMTP 2691to the mailer. 2692If the pathname for this mailer is 2693.q [IPC], 2694the argv should be 2695.(b 2696IPC $h [ \fIport\fP ] 2697.)b 2698where 2699.i port 2700is the optional port number 2701to connect to. 2702.pp 2703For example, 2704the specifications: 2705.(b 2706.ta \w'Mlocal, 'u +\w'P=/bin/mail, 'u +\w'F=rlsm, 'u +\w'S=10, 'u +\w'R=20, 'u 2707Mlocal, P=/bin/mail, F=rlsm S=10, R=20, A=mail \-d $u 2708Mether, P=[IPC], F=meC, S=11, R=21, A=IPC $h, M=100000 2709.)b 2710specifies a mailer to do local delivery 2711and a mailer for ethernet delivery. 2712The first is called 2713.q local, 2714is located in the file 2715.q /bin/mail, 2716takes a picky 2717.b \-r 2718flag, 2719does local delivery, 2720quotes should be stripped from addresses, 2721and multiple users can be delivered at once; 2722ruleset ten 2723should be applied to sender addresses in the message 2724and ruleset twenty 2725should be applied to recipient addresses; 2726the argv to send to a message will be the word 2727.q mail, 2728the word 2729.q \-d, 2730and words containing the name of the receiving user. 2731If a 2732.b \-r 2733flag is inserted 2734it will be between the words 2735.q mail 2736and 2737.q \-d. 2738The second mailer is called 2739.q ether, 2740it should be connected to via an IPC connection, 2741it can handle multiple users at once, 2742connections should be deferred, 2743and any domain from the sender address 2744should be appended to any receiver name 2745without a domain; 2746sender addresses should be processed by ruleset eleven 2747and recipient addresses by ruleset twenty-one. 2748There is a 100,000 byte limit on messages passed through this mailer. 2749.++ A 2750.+c "COMMAND LINE FLAGS" 2751.ba 0 2752.nr ii 1i 2753.pp 2754Arguments must be presented with flags before addresses. 2755The flags are: 2756.ip "\-f\ \fIaddr\fP" 2757The sender's machine address is 2758.i addr . 2759This flag is ignored unless the real user 2760is listed as a 2761.q "trusted user" 2762or if 2763.i addr 2764contains an exclamation point 2765(because of certain restrictions in UUCP). 2766.ip "\-r\ \fIaddr\fP" 2767An obsolete form of 2768.b \-f . 2769.ip "\-h\ \fIcnt\fP" 2770Sets the 2771.q "hop count" 2772to 2773.i cnt . 2774This represents the number of times this message has been processed 2775by 2776.i sendmail 2777(to the extent that it is supported by the underlying networks). 2778.i Cnt 2779is incremented during processing, 2780and if it reaches 2781MAXHOP 2782(currently 30) 2783.i sendmail 2784throws away the message with an error. 2785.ip \-F\fIname\fP 2786Sets the full name of this user to 2787.i name . 2788.ip \-n 2789Don't do aliasing or forwarding. 2790.ip \-t 2791Read the header for 2792.q To: , 2793.q Cc: , 2794and 2795.q Bcc: 2796lines, and send to everyone listed in those lists. 2797The 2798.q Bcc: 2799line will be deleted before sending. 2800Any addresses in the argument vector will be deleted 2801from the send list. 2802.ip \-b\fIx\fP 2803Set operation mode to 2804.i x . 2805Operation modes are: 2806.(b 2807.ta 4n 2808m Deliver mail (default) 2809a Run in arpanet mode (see below) 2810s Speak SMTP on input side 2811d Run as a daemon 2812t Run in test mode 2813v Just verify addresses, don't collect or deliver 2814i Initialize the alias database 2815p Print the mail queue 2816z Freeze the configuration file 2817.)b 2818The special processing for the 2819ARPANET 2820includes reading the 2821.q "From:" 2822line from the header to find the sender, 2823printing 2824ARPANET 2825style messages 2826(preceded by three digit reply codes for compatibility with 2827the FTP protocol 2828[Neigus73, Postel74, Postel77]), 2829and ending lines of error messages with <CRLF>. 2830.ip \-q\fItime\fP 2831Try to process the queued up mail. 2832If the time is given, 2833a sendmail will run through the queue at the specified interval 2834to deliver queued mail; 2835otherwise, it only runs once. 2836.ip \-C\fIfile\fP 2837Use a different configuration file. 2838.ip \-d\fIlevel\fP 2839Set debugging level. 2840.ip \-o\fIx\|value\fP 2841Set option 2842.i x 2843to the specified 2844.i value . 2845These options are described in Appendix B. 2846.pp 2847There are a number of options that may be specified as 2848primitive flags 2849(provided for compatibility with 2850.i delivermail ). 2851These are the e, i, m, and v options. 2852Also, 2853the f option 2854may be specified as the 2855.b \-s 2856flag. 2857.+c "CONFIGURATION OPTIONS" 2858.pp 2859The following options may be set using the 2860.b \-o 2861flag on the command line 2862or the 2863.b O 2864line in the configuration file: 2865.nr ii 1i 2866.ip A\fIfile\fP 2867Use the named 2868.i file 2869as the alias file. 2870If no file is specified, 2871use 2872.i aliases 2873in the current directory. 2874.ip a 2875If set, 2876wait for an 2877.q @:@ 2878entry to exist in the alias database 2879before starting up. 2880If it does not appear in five minutes, 2881rebuild the database. 2882.ip c 2883If an outgoing mailer is marked as being expensive, 2884don't connect immediately. 2885This requires that queueing be compiled in, 2886since it will depend on a queue run process to 2887actually send the mail. 2888.ip d\fIx\fP 2889Deliver in mode 2890.i x . 2891Legal modes are: 2892.(b 2893.ta 4n 2894i Deliver interactively (synchronously) 2895b Deliver in background (asynchronously) 2896q Just queue the message (deliver during queue run) 2897.)b 2898.ip D 2899If set, 2900rebuild the alias database if necessary and possible. 2901If this option is not set, 2902.i sendmail 2903will never rebuild the alias database 2904unless explicitly requested 2905using 2906.b \-bi . 2907.ip e\fIx\fP 2908Dispose of errors using mode 2909.i x . 2910The values for 2911.i x 2912are: 2913.(b 2914p Print error messages (default) 2915q No messages, just give exit status 2916m Mail back errors 2917w Write back errors (mail if user not logged in) 2918e Mail back errors and give zero exit stat always 2919.)b 2920.ip F\fIn\fP 2921The temporary file mode, 2922in octal. 2923644 and 600 are good choices. 2924.ip f 2925Save 2926Unix-style 2927.q From 2928lines at the front of headers. 2929Normally they are assumed redundant 2930and discarded. 2931.ip g\fIn\fP 2932Set the default group id 2933for mailers to run in 2934to 2935.i n . 2936.ip H\fIfile\fP 2937Specify the help file 2938for SMTP. 2939.ip i 2940Ignore dots in incoming messages. 2941.ip L\fIn\fP 2942Set the default log level to 2943.i n . 2944.ip M\fIx\|value\fP 2945Set the macro 2946.i x 2947to 2948.i value . 2949This is intended only for use from the command line. 2950.ip m 2951Send to me too, 2952even if I am in an alias expansion. 2953.ip N 2954Set the maximum number of connnections that 2955.i sendmail 2956will accept simultaneously over an IPC connection 2957(default four). 2958This can be used to try to limit the mail load on your system. 2959Note that this only applies to mail coming in 2960over an IPC connection, 2961so that mail submissions occuring from calling 2962.i sendmail 2963directly are never restricted. 2964.ip o 2965Assume that the headers may be in old format, 2966i.e., 2967spaces delimit names. 2968This actually turns on 2969an adaptive algorithm: 2970if any recipient address contains a comma, parenthesis, 2971or angle bracket, 2972it will be assumed that commas already exist. 2973If this flag is not on, 2974only commas delimit names. 2975Headers are always output with commas between the names. 2976.ip Q\fIdir\fP 2977Use the named 2978.i dir 2979as the queue directory. 2980.ip r\fItime\fP 2981Timeout reads after 2982.i time 2983interval. 2984.ip S\fIfile\fP 2985Log statistics in the named 2986.i file . 2987.ip s 2988Be super-safe when running things, 2989i.e., 2990always instantiate the queue file, 2991even if you are going to attempt immediate delivery. 2992.i Sendmail 2993always instantiates the queue file 2994before returning control the the client 2995under any circumstances. 2996.ip T\fItime\fP 2997Set the queue timeout to 2998.i time . 2999After this interval, 3000messages that have not been successfully sent 3001will be returned to the sender. 3002.ip t\fIS,D\fP 3003Set the local timezone name to 3004.i S 3005for standard time and 3006.i D 3007for daylight time; 3008this is only used under version six. 3009.ip u\fIn\fP 3010Set the default userid for mailers to 3011.i n . 3012Mailers without the 3013.i S 3014flag in the mailer definition 3015will run as this user. 3016.ip v 3017Run in verbose mode. 3018.+c "MAILER FLAGS" 3019The following flags may be set in the mailer description. 3020.nr ii 4n 3021.ip f 3022The mailer wants a 3023.b \-f 3024.i from 3025flag, 3026but only if this is a network forward operation 3027(i.e., 3028the mailer will give an error 3029if the executing user 3030does not have special permissions). 3031.ip r 3032Same as 3033.b f , 3034but sends a 3035.b \-r 3036flag. 3037.ip S 3038Don't reset the userid 3039before calling the mailer. 3040This would be used in a secure environment 3041where 3042.i sendmail 3043ran as root. 3044This could be used to avoid forged addresses. 3045This flag is suppressed if given from an 3046.q unsafe 3047environment 3048(e.g, a user's mail.cf file). 3049.ip n 3050Do not insert a UNIX-style 3051.q From 3052line on the front of the message. 3053.ip l 3054This mailer is local 3055(i.e., 3056final delivery will be performed). 3057.ip s 3058Strip quote characters off of the address 3059before calling the mailer. 3060.ip m 3061This mailer can send to multiple users 3062on the same host 3063in one transaction. 3064When a 3065.b $u 3066macro occurs in the 3067.i argv 3068part of the mailer definition, 3069that field will be repeated as necessary 3070for all qualifying users. 3071.ip F 3072This mailer wants a 3073.q From: 3074header line. 3075.ip D 3076This mailer wants a 3077.q Date: 3078header line. 3079.ip M 3080This mailer wants a 3081.q Message-Id: 3082header line. 3083.ip x 3084This mailer wants a 3085.q Full-Name: 3086header line. 3087.ip P 3088This mailer wants a 3089.q Return-Path: 3090line. 3091.ip u 3092Upper case should be preserved in user names 3093for this mailer. 3094.ip h 3095Upper case should be preserved in host names 3096for this mailer. 3097.ip A 3098This is an Arpanet-compatible mailer, 3099and all appropriate modes should be set. 3100.ip U 3101This mailer wants Unix-style 3102.q From 3103lines with the ugly UUCP-style 3104.q "remote from <host>" 3105on the end. 3106.ip e 3107This mailer is expensive to connect to, 3108so try to avoid connecting normally; 3109any necessary connection will occur during a queue run. 3110.ip X 3111This mailer want to use the hidden dot algorithm 3112as specified in RFC821; 3113basically, 3114any line beginning with a dot 3115will have an extra dot prepended 3116(to be stripped at the other end). 3117This insures that lines in the message containing a dot 3118will not terminate the message prematurely. 3119.ip L 3120Limit the line lengths as specified in RFC821. 3121.ip P 3122Use the return-path in the SMTP 3123.q "MAIL FROM:" 3124command 3125rather than just the return address; 3126although this is required in RFC821, 3127many hosts do not process return paths properly. 3128.ip I 3129This mailer will be speaking SMTP 3130to another 3131.i sendmail 3132\*- 3133as such it can use special protocol features. 3134This option is not required 3135(i.e., 3136if this option is omitted the transmission will still operate successfully, 3137although perhaps not as efficiently as possible). 3138.ip C 3139If mail is 3140.i received 3141from a mailer with this flag set, 3142any addresses in the header that do not have an at sign 3143(\c 3144.q @ ) 3145after being rewritten by ruleset three 3146will have the 3147.q @domain 3148clause from the sender 3149tacked on. 3150This allows mail with headers of the form: 3151.(b 3152From: usera@hosta 3153To: userb@hostb, userc 3154.)b 3155to be rewritten as: 3156.(b 3157From: usera@hosta 3158To: userb@hostb, userc@hosta 3159.)b 3160automatically. 3161.+c "OTHER CONFIGURATION" 3162.rm $0 3163.nr ii 1i 3164.pp 3165There are some configuration changes that can be made by 3166recompiling 3167.i sendmail . 3168These are located in three places: 3169.ip Makefile 3170Changes in the makefile are operating-system dependent. 3171These include information about what version of UNIX 3172you are running, etc. 3173.ip conf.h 3174Configuration parameters that may be tweaked by the installer 3175are included in conf.h. 3176.ip conf.c 3177Some special routines and a few variables 3178may be defined in conf.c. 3179For the most part these are selected from the settings 3180in conf.h. 3181.uh "Changes to the Makefile" 3182.pp 3183The following compilation flags may be defined in the makefile 3184to define the environment in which you are operating. 3185.ip V6 3186If set, 3187this will compile a version 6 system, 3188with 8-bit user id's, 3189single character tty id's, 3190etc. 3191.ip VMUNIX 3192If set, 3193you will be assumed to have a Berkeley 4BSD or 4.1BSD, 3194including the 3195.i vfork \|(2) 3196system call, 3197special types defined in <sys/types.h> 3198(e.g, u_char), 3199etc. 3200.lp 3201If none of these flags are set, 3202a version 7 system is assumed. 3203.uh "Parameters in conf.h" 3204.pp 3205Parameters and compilation options 3206are defined in conf.h. 3207Most of these need not normally be tweaked; 3208common parameters are all in sendmail.cf. 3209However, the sizes of certain primitive vectors, etc., 3210are included in this file. 3211The numbers following the parameters 3212are their default value. 3213.nr ii 1.2i 3214.ip "MAXLINE [256]" 3215The maximum line length of any input line. 3216If message lines exceed this length 3217they will still be processed correctly; 3218however, header lines, 3219configuration file lines, 3220alias lines, 3221etc., 3222must fit within this limit. 3223.ip "MAXNAME [128]" 3224The maximum length of any name, 3225such as a host or a user name. 3226.ip "MAXFIELD [2500]" 3227The maximum total length of any header field, 3228including continuation lines. 3229.ip "MAXPV [40]" 3230The maximum number of parameters to any mailer. 3231This limits the number of recipients that may be passed in one transaction. 3232.ip "MAXHOP [30]" 3233When a message has been processed more than this number of times, 3234sendmail rejects the message 3235on the assumption that there has been an aliasing loop. 3236This can be determined from the 3237.b \-h 3238flag 3239or by counting the number of trace fields 3240(i.e, 3241.q Received: 3242lines) 3243in the message header. 3244.ip "MAXATOM [100]" 3245The maximum number of atoms 3246(tokens) 3247in a single address. 3248For example, 3249the address 3250.q "eric@Berkeley" 3251is three atoms. 3252.ip "MAXMAILERS [25]" 3253The maximum number of mailers that may be defined 3254in the configuration file. 3255.ip "MAXRWSETS [30]" 3256The maximum number of rewriting sets 3257that may be defined. 3258.ip "MAXPRIORITIES [25]" 3259The maximum number of values for the 3260.q Precedence: 3261field that may be defined 3262(using the 3263.b P 3264line in sendmail.cf). 3265.ip "MAXTRUST [30]" 3266The maximum number of trusted users that may be defined 3267(using the 3268.b T 3269line in sendmail.cf). 3270.lp 3271A number of other compilation options exist. 3272These specify whether or not specific code should be compiled in. 3273.nr ii 1i 3274.ip DBM 3275If set, 3276the 3277.q DBM 3278package in UNIX is used 3279(see DBM(3X) in [UNIX80]). 3280If not set, 3281a much less efficient algorithm for processing aliases is used. 3282.ip DEBUG 3283If set, debugging information is compiled in. 3284To actually get the debugging output, 3285the 3286.b \-d 3287flag must be used. 3288.ip LOG 3289If set, 3290the 3291.i syslog 3292routine in use at some sites is used. 3293This makes an informational log record 3294for each message processed, 3295and makes a higher priority log record 3296for internal system errors. 3297.ip QUEUE 3298This flag should be set to compile in the queueing code. 3299If this is not set, 3300mailers must accept the mail immediately 3301or it will be returned to the sender. 3302.ip SMTP 3303If set, 3304the code to handle user and server SMTP will be compiled in. 3305This is only necessary if your machine has some mailer 3306that speaks SMTP. 3307.ip DAEMON 3308If set, 3309code to run a daemon is compiled in. 3310This code is for 4.2BSD 3311if the 3312NVMUNIX 3313flag is specified; 3314otherwise, 33154.1a BSD code is used. 3316Beware however 3317that there are bugs in the 4.1a code 3318that make it impossible for 3319.b sendmail 3320to work correctly 3321under heavy load. 3322.ip UGLYUUCP 3323If you have a UUCP host adjacent to you which is not running 3324a reasonable version of 3325.i rmail , 3326you will have to set this flag to include the 3327.q "remote from sysname" 3328info on the from line. 3329Otherwise, UUCP gets confused about where the mail came from. 3330.ip NOTUNIX 3331If you are using a non-UNIX mail format, 3332you can set this flag to turn off special processing 3333of UNIX-style 3334.q "From " 3335lines. 3336.uh "Configuration in conf.c" 3337.pp 3338Not all header semantics are defined in the configuration file. 3339Header lines that should only be included by certain mailers 3340(as well as other more obscure semantics) 3341must be specified in the 3342.i HdrInfo 3343table in 3344.i conf.c . 3345This table contains the header name 3346(which should be in all lower case) 3347and a set of header control flags (described below), 3348The flags are: 3349.ip H_ACHECK 3350Normally when the check is made to see if a header line is compatible 3351with a mailer, 3352.i sendmail 3353will not delete an existing line. 3354If this flag is set, 3355.i sendmail 3356will delete 3357even existing header lines. 3358That is, 3359if this bit is set and the mailer does not have flag bits set 3360that intersect with the required mailer flags 3361in the header definition in 3362sendmail.cf, 3363the header line is 3364.i always 3365deleted. 3366.ip H_EOH 3367If this header field is set, 3368treat it like a blank line, 3369i.e., 3370it will signal the end of the header 3371and the beginning of the message text. 3372.ip H_FORCE 3373Add this header entry 3374even if one existed in the message before. 3375If a header entry does not have this bit set, 3376.i sendmail 3377will not add another header line if a header line 3378of this name already existed. 3379This would normally be used to stamp the message 3380by everyone who handled it. 3381.ip H_TRACE 3382If set, 3383this is a timestamp 3384(trace) 3385field. 3386If the number of trace fields in a message 3387exceeds a preset amount 3388the message is returned 3389on the assumption that it has an aliasing loop. 3390.ip H_RCPT 3391If set, 3392this field contains recipient addresses. 3393This is used by the 3394.b \-t 3395flag to determine who to send to 3396when it is collecting recipients from the message. 3397.ip H_FROM 3398This flag indicates that this field 3399specifies a sender. 3400The order of these fields in the 3401.i HdrInfo 3402table specifies 3403.i sendmail's 3404preference 3405for which field to return error messages to. 3406.nr ii 5n 3407.lp 3408Let's look at a sample 3409.i HdrInfo 3410specification: 3411.(b 3412.ta 4n +\w'"return-receipt-to", 'u 3413struct hdrinfo HdrInfo[] = 3414{ 3415 /* originator fields, most to least significant */ 3416 "resent-sender", H_FROM, 3417 "resent-from", H_FROM, 3418 "sender", H_FROM, 3419 "from", H_FROM, 3420 "full-name", H_ACHECK, 3421 /* destination fields */ 3422 "to", H_RCPT, 3423 "resent-to", H_RCPT, 3424 "cc", H_RCPT, 3425 /* message identification and control */ 3426 "message", H_EOH, 3427 "text", H_EOH, 3428 /* trace fields */ 3429 "received", H_TRACE|H_FORCE, 3430 3431 NULL, 0, 3432}; 3433.)b 3434This structure indicates that the 3435.q To: , 3436.q Resent-To: , 3437and 3438.q Cc: 3439fields 3440all specify recipient addresses. 3441Any 3442.q Full-Name: 3443field will be deleted unless the required mailer flag 3444(indicated in the configuration file) 3445is specified. 3446The 3447.q Message: 3448and 3449.q Text: 3450fields will terminate the header; 3451these are specified in new protocols 3452[NBS80] 3453or used by random dissenters around the network world. 3454The 3455.q Received: 3456field will always be added, 3457and can be used to trace messages. 3458.pp 3459There are a number of important points here. 3460First, 3461header fields are not added automatically just because they are in the 3462.i HdrInfo 3463structure; 3464they must be specified in the configuration file 3465in order to be added to the message. 3466Any header fields mentioned in the configuration file but not 3467mentioned in the 3468.i HdrInfo 3469structure have default processing performed; 3470that is, 3471they are added unless they were in the message already. 3472Second, 3473the 3474.i HdrInfo 3475structure only specifies cliched processing; 3476certain headers are processed specially by ad hoc code 3477regardless of the status specified in 3478.i HdrInfo . 3479For example, 3480the 3481.q Sender: 3482and 3483.q From: 3484fields are always scanned on ARPANET mail 3485to determine the sender; 3486this is used to perform the 3487.q "return to sender" 3488function. 3489The 3490.q "From:" 3491and 3492.q "Full-Name:" 3493fields are used to determine the full name of the sender 3494if possible; 3495this is stored in the macro 3496.b $x 3497and used in a number of ways. 3498.pp 3499The file 3500.i conf.c 3501also contains the specification of ARPANET reply codes. 3502There are four classifications these fall into: 3503.(b 3504.sz -1 3505.ta \w'char 'u +\w'Arpa_TUsrerr[] = 'u +\w'"888"; 'u 3506char Arpa_Info[] = "050"; /* arbitrary info */ 3507char Arpa_TSyserr[] = "455"; /* some (transient) system error */ 3508char Arpa_PSyserr[] = "554"; /* some (transient) system error */ 3509char Arpa_Usrerr[] = "554"; /* some (fatal) user error */ 3510.sz 3511.)b 3512The class 3513.i Arpa_Info 3514is for any information that is not required by the protocol, 3515such as forwarding information. 3516.i Arpa_TSyserr 3517and 3518.i Arpa_PSyserr 3519is printed by the 3520.i syserr 3521routine. 3522TSyserr 3523is printed out for transient errors, 3524whereas PSyserr 3525is printed for permanent errors; 3526the distinction is made based on the value of 3527.i errno . 3528Finally, 3529.i Arpa_Usrerr 3530is the result of a user error 3531and is generated by the 3532.i usrerr 3533routine; 3534these are generated when the user has specified something wrong, 3535and hence the error is permanent, 3536i.e., 3537it will not work simply by resubmitting the request. 3538.pp 3539If it is necessary to restrict mail through a relay, 3540the 3541.i checkcompat 3542routine can be modified. 3543This routine is called for every recipient address. 3544It can return 3545.b TRUE 3546to indicate that the address is acceptable 3547and mail processing will continue, 3548or it can return 3549.b FALSE 3550to reject the recipient. 3551If it returns false, 3552it is up to 3553.i checkcompat 3554to print an error message 3555(using 3556.i usrerr ) 3557saying why the message is rejected. 3558For example, 3559.i checkcompat 3560could read: 3561.(b 3562.re 3563.sz -1 3564.ta 4n +4n +4n +4n +4n +4n +4n 3565bool 3566checkcompat(to) 3567 register ADDRESS *to; 3568{ 3569 if (MsgSize > 50000 && to->q_mailer != LocalMailer) 3570 { 3571 usrerr("Message too large for non-local delivery"); 3572 NoReturn = TRUE; 3573 return (FALSE); 3574 } 3575 return (TRUE); 3576} 3577.sz 3578.)b 3579This would reject messages greater than 50000 bytes 3580unless they were local. 3581The 3582.i NoReturn 3583flag can be sent to supress the return of the actual body 3584of the message in the error return. 3585The actual use of this routine is highly dependent on the 3586implementation, 3587and use should be limited. 3588.+c "SUMMARY OF SUPPORT FILES" 3589.pp 3590This is a summary of the support files 3591that 3592.i sendmail 3593creates or generates. 3594.nr ii 1i 3595.ip "/usr/lib/sendmail" 3596The binary of 3597.i sendmail . 3598.ip /usr/bin/newaliases 3599A link to /usr/lib/sendmail; 3600causes the alias database to be rebuilt. 3601Running this program is completely equivalent to giving 3602.i sendmail 3603the 3604.b \-bi 3605flag. 3606.ip /usr/bin/mailq 3607Prints a listing of the mail queue. 3608This program is equivalent to using the 3609.b \-bp 3610flag to 3611.i sendmail . 3612.ip /usr/lib/sendmail.cf 3613The configuration file, 3614in textual form. 3615.ip /usr/lib/sendmail.fc 3616The configuration file 3617represented as a memory image. 3618.ip /usr/lib/sendmail.hf 3619The SMTP help file. 3620.ip /usr/lib/sendmail.st 3621A statistics file; need not be present. 3622.ip /usr/lib/aliases 3623The textual version of the alias file. 3624.ip /usr/lib/aliases.{pag,dir} 3625The alias file in 3626.i dbm \|(3) 3627format. 3628.ip /etc/syslog 3629The program to do logging. 3630.ip /etc/syslog.conf 3631The configuration file for syslog. 3632.ip /etc/syslog.pid 3633Contains the process id of the currently running syslog. 3634.ip /usr/spool/mqueue 3635The directory in which the mail queue 3636and temporary files reside. 3637.ip /usr/spool/mqueue/qf* 3638Control (queue) files for messages. 3639.ip /usr/spool/mqueue/df* 3640Data files. 3641.ip /usr/spool/mqueue/lf* 3642Lock files 3643.ip /usr/spool/mqueue/tf* 3644Temporary versions of the qf files, 3645used during queue file rebuild. 3646.ip /usr/spool/mqueue/nf* 3647A file used when creating a unique id. 3648.ip /usr/spool/mqueue/xf* 3649A transcript of the current session. 3650.ro 3651.ls 1 3652.tp 3653.sp 2i 3654.in 0 3655.ce 100 3656.sz 24 3657.b SENDMAIL 3658.sz 14 3659.sp 3660INSTALLATION AND OPERATION GUIDE 3661.sp 3662.sz 10 3663Eric Allman 3664Britton-Lee, Inc. 3665.sp 3666Version 3.18 3667.sp 2 3668.sz 14 3669DRAFT 3670.ce 0 3671.bp 1 3672.ce 3673.sz 12 3674TABLE OF CONTENTS 3675.sz 10 3676.sp 2 3677.\" remove some things to avoid "out of temp file space" problem 3678.rm sh 3679.rm (x 3680.rm )x 3681.rm ip 3682.rm pp 3683.rm lp 3684.rm he 3685.rm fo 3686.rm eh 3687.rm oh 3688.rm ef 3689.rm of 3690.xp 3691