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