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