SENDMAIL INSTALLATIONANDOPERATIONGUIDE EricAllman Britton-Lee,Inc. Version4.2 SendmailimplementsageneralpurposeinternetworkmailroutingfacilityundertheUNIX* operatingsystem.Itisnottiedtoanyonetransportprotocol—itsfunctionmaybelikenedtoa crossbarswitch,relayingmessagesfromonedomainintoanother.Intheprocess,itcandoalimitedamountofmessageheadereditingtoputthemessageintoaformatthatisappropriatefor thereceivingdomain.Allofthisisdoneunderthecontrolofaconfigurationfile. Duetotherequirementsofflexibilityforsendmail,theconfigurationfilecanseemsomewhat unapproachable.However,thereareonlyafewbasicconfigurationsformostsites,forwhichstandardconfigurationfileshavebeensupplied.Mostotherconfigurationscanbebuiltbyadjusting anexistingconfigurationfilesincrementally. Althoughsendmailisintendedtorunwithouttheneedformonitoring,ithasanumberof featuresthatmaybeusedtomonitororadjusttheoperationunderunusualcircumstances.These featuresaredescribed. Sectiononedescribeshowtodoabasicsendmailinstallation.Sectiontwoexplainsthedayto-dayinformationyoushouldknowtomaintainyourmailsystem.Ifyouhavearelativelynor-malsite,thesetwosectionsshouldcontainsufficientinformationforyoutoinstallsendmailand keepithappy.Sectionthreedescribessomeparametersthatmaybesafelytweaked.Sectionfour hasinformationregardingthecommandlinearguments.Sectionfivecontainsthenitty-gritty informationabouttheconfigurationfile.Thissectionisformasochistsandpeoplewhomustwrite theirownconfigurationfile.Theappendixesgiveabriefbutdetailedexplanationofanumberof featuresnotdescribedintherestofthepaper. ThereferencesinthispaperareactuallyfoundinthecompanionpaperSendmail−An InternetworkMailRouter.Thisotherpapershouldbereadbeforethismanualtogainabasic understandingofhowthepiecesfittogether. 1.BASICINSTALLATION Therearetwobasicstepstoinstallingsendmail.Thehardpartistobuildtheconfigurationtable.Thisisafilethatsendmailreadswhenitstartsupthatdescribesthemailersit knowsabout,howtoparseaddresses,howtorewritethemessageheader,andthesettingsof variousoptions.Althoughtheconfigurationtableisquitecomplex,aconfigurationcanusually bebuiltbyadjustinganexistingoff-the-shelfconfiguration.Thesecondpartisactuallydoing theinstallation,i.e.,creatingthenecessaryfiles,etc. *UNIXisatrademarkofBellLaboratories. SendmailInstallationandOperationGuide 1 SendmailInstallationandOperationGuide 2 Theremainderofthissectionwilldescribetheinstallationofsendmailassumingyoucan useoneoftheexistingconfigurationsandthatthestandardinstallationparametersareacceptable.Allpathnamesandexamplesaregivenfromtherootofthesendmailsubtree. 1.1.Off-The-ShelfConfigurations Theconfigurationfilesareallinthesubdirectorycfofthesendmaildirectory.The onesusedatBerkeleyareinm4(1)format;fileswithnamesending“.m4”arem4include files,whilefileswithnamesending“.mc”arethemasterfiles.Fileswithnamesending “.cf”arethem4processedversionsofthecorresponding“.mc”file. Twoofftheshelfconfigurationfilesaresuppliedtohandlethebasiccases: cf/arpaproto.cfforArpanet(TCP)sitesandcf/uucpproto.cfforUUCPsites.Thesearenot inm4format.Thefileyouneedshouldbecopiedtoafilewiththesamenameasyoursystem,e.g., cpuucpproto.cfucsfcgl.cf Thisfileisnowreadyforinstallationas/usr/lib/sendmail.cf. 1.2.InstallationUsingtheMakefile Amakefileexistsintherootofthesendmaildirectorythatwilldoallofthesesteps fora4.2BSDsystem.Itmayhavetobeslightlytailoredforuseonothersystems. Beforeusingthismakefile,youshouldalreadyhavecreatedyourconfigurationfileand leftitinthefile“cf/system.cf”wheresystemisthenameofyoursystem(i.e.,whatis returnedbyhostname(1)).Ifyoudonothavehostnameyoucanusethedeclaration “HOST=system”onthemake(1)commandline.Youshouldalsoexaminethefile md/config.m4andchangethem4macrostheretoreflectanylibrariesandcompilationflags youmayneed. Thebasicinstallationprocedureistotype: make makeinstall intherootdirectoryofthesendmaildistribution.Thiswillmakeallbinariesandinstall theminthestandardplaces.Thesecondmakecommandmustbeexecutedasthesuperuser(root). 1.3.InstallationbyHand Alongwithbuildingaconfigurationfile,youwillhavetoinstallthesendmailstartup intoyourUNIXsystem.Ifyouaredoingthisinstallationinconjunctionwitharegular BerkeleyUNIXinstall,thesestepswillalreadybecomplete.Manyofthesestepswillhave tobeexecutedasthesuperuser(root). 1.3.1.lib/libsys.a Thelibraryinlib/libsys.acontainssomeroutinesthatshouldinsomesensebe partofthesystemlibrary.Thesearethesystemloggingroutinesandthenewdirectory accessroutines(ifrequired).Ifyouarenotrunningthenew4.2BSDdirectorycodeand donothavethecompatibilityroutinesinstalledinyoursystemlibrary,youshouldexecutethecommands: cdlib makendir Thiswillcompileandinstallthe4.2compatibilityroutinesinthelibrary.Youshould thentype: Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 3 cdlib#ifrequired make Thiswillrecompileandfillthelibrary. 1.3.2./usr/lib/sendmail Thebinaryforsendmailislocatedin/usr/lib.Thereisaversionavailableinthe sourcedirectorythatisprobablyinadequateforyoursystem.Youshouldplanon recompilingandinstallingtheentiresystem: cdsrc rm−f*.o make cpsendmail/usr/lib 1.3.3./usr/lib/sendmail.cf Theconfigurationfilethatyoucreatedearliershouldbeinstalledin /usr/lib/sendmail.cf: cpcf/system.cf/usr/lib/sendmail.cf 1.3.4./usr/ucb/newaliases Ifyouarerunningdelivermail,itiscriticalthatthenewaliasescommandbe replaced.Thiscanjustbealinktosendmail: rm−f/usr/ucb/newaliases ln/usr/lib/sendmail/usr/ucb/newaliases 1.3.5./usr/lib/sendmail.cf Theconfigurationfilemustbeinstalledin/usr/lib.Thisisdescribedabove. 1.3.6./usr/spool/mqueue Thedirectory/usr/spool/mqueueshouldbecreatedtoholdthemailqueue.This directoryshouldbemode777unlesssendmailisrunsetuid,whenmqueueshouldbe ownedbythesendmailownerandmode755. 1.3.7./usr/lib/aliases* Thesystemaliasesareheldinthreefiles.Thefile“/usr/lib/aliases”isthemaster copy.Asampleisgivenin“lib/aliases”whichincludessomealiaseswhichmustbe defined: cplib/aliases/usr/lib/aliases Youshouldextendthisfilewithanyaliasesthatareapropostoyoursystem. Normallysendmaillooksataversionofthesefilesmaintainedbythedbm(3)routines.Thesearestoredin“/usr/lib/aliases.dir”and“/usr/lib/aliases.pag.”Thesecan initiallybecreatedasemptyfiles,buttheywillhavetobeinitializedpromptly.These shouldbemode666ifyouarerunningareasonablyrelaxedsystem: cp/dev/null/usr/lib/aliases.dir cp/dev/null/usr/lib/aliases.pag chmod666/usr/lib/aliases.* newaliases Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 4 1.3.8./usr/lib/sendmail.fc Ifyouintendtoinstallthefrozenversionoftheconfigurationfile(forquick startup)youshouldcreatethefile/usr/lib/sendmail.fcandinitializeit.Thisstepmay besafelyskipped. cp/dev/null/usr/lib/sendmail.fc /usr/lib/sendmail−bz 1.3.9./etc/rc Itwillbenecessarytostartupthesendmaildaemonwhenyoursystemreboots. Thisdaemonperformstwofunctions:itlistensontheSMTPsocketforconnections(to receivemailfromaremotesystem)anditprocessesthequeueperiodicallytoinsure thatmailgetsdeliveredwhenhostscomeup. Addthefollowinglinesto“/etc/rc”(or“/etc/rc.local”asappropriate)inthearea whereitisstartingupthedaemons: if[−f/usr/lib/sendmail];then (cd/usr/spool/mqueue;rm−f[lnx]f*) /usr/lib/sendmail−bd−q30m& echo−n’sendmail’>/dev/console fi The“cd”and“rm”commandsinsurethatalllockfileshavebeenremoved;extraneous lockfilesmaybeleftaroundifthesystemgoesdowninthemiddleofprocessingamessage.Thelinethatactuallyinvokessendmailhastwoflags:“−bd”causesittolistenon theSMTPport,and“−q30m”causesittorunthequeueeveryhalfhour. IfyouarenotrunningaversionofUNIXthatsupportsBerkeleyTCP/IP,donot includethe−bdflag. 1.3.10./usr/lib/sendmail.hf ThisisthehelpfileusedbytheSMTPHELPcommand.Itshouldbecopied from“lib/sendmail.hf”: cplib/sendmail.hf/usr/lib 1.3.11./usr/lib/sendmail.st Ifyouwishtocollectstatisticsaboutyourmailtraffic,youshouldcreatethefile “/usr/lib/sendmail.st”: cp/dev/null/usr/lib/sendmail.st chmod666/usr/lib/sendmail.st Thisfiledoesnotgrow.Itisprintedwiththeprogram“aux/mailstats.” 1.3.12./etc/syslog Youmaywanttorunthesyslogprogram(tocollectloginformationaboutsendmail).Thisprogramnormallyresidesin/etc/syslog,withsupportfiles/etc/syslog.conf and/etc/syslog.pid.Theprogramislocatedintheauxsubdirectoryofthesendmail distribution.Thefile/etc/syslog.confdescribesthefile(s)thatsendmailwilllogin.For acompletedescriptionofsyslog,seethemanualpageforsyslog(8)(locatedinsendmail/doconthedistribution). Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 5 1.3.13./usr/ucb/newaliases Ifsendmailisinvokedas“newaliases,”itwillsimulatethe−biflag(i.e.,will rebuildthealiasdatabase;seebelow).Thisshouldbealinkto/usr/lib/sendmail. 1.3.14./usr/ucb/mailq Ifsendmailisinvokedas“mailq,”itwillsimulatethe−bpflag(i.e.,sendmailwill printthecontentsofthemailqueue;seebelow).Thisshouldbealinkto /usr/lib/sendmail. 2.NORMALOPERATIONS 2.1.QuickConfigurationStartup Afastversionoftheconfigurationfilemaybesetupbyusingthe−bzflag: /usr/lib/sendmail−bz Thiscreatesthefile/usr/lib/sendmail.fc(“frozenconfiguration”).Thisfileisanimageof sendmail’sdataspaceafterreadingintheconfigurationfile.Ifthisfileexists,itisused insteadof/usr/lib/sendmail.cfsendmail.fcmustberebuiltmanuallyeverytimesendmail.cf ischanged. Thefrozenconfigurationfilewillbeignoredifa−Cflagisspecifiedorifsendmail detectsthatitisoutofdate.However,theheuristicsarenotstrongsothisshouldnotbe trusted. 2.2.TheSystemLog Thesystemlogissupportedbythesyslog(8)program. 2.2.1.Format Eachlineinthesystemlogconsistsofatimestamp,thenameofthemachinethat generatedit(forloggingfromseveralmachinesovertheethernet),theword“sendmail:”,andamessage. 2.2.2.Levels Ifyouhavesyslog(8)oranequivalentinstalled,youwillbeabletodologging. Thereisalargeamountofinformationthatcanbelogged.Thelogisarrangedasa successionoflevels.Atthelowestlevelonlyextremelystrangesituationsarelogged. Atthehighestlevel,eventhemostmundaneanduninterestingeventsarerecordedfor posterity.Asaconvention,loglevelsundertenareconsidered“useful;”loglevelsabove tenareusuallyfordebuggingpurposes. Acompletedescriptionoftheloglevelsisgiveninsection4.3. 2.3.TheMailQueue Themailqueueshouldbeprocessedtransparently.However,youmayfindthatmanualinterventionissometimesnecessary.Forexample,ifamajorhostisdownforaperiod oftimethequeuemaybecomeclogged.Althoughsendmailoughttorecovergracefully whenthehostcomesup,youmayfindperformanceunacceptablybadinthemeantime. 2.3.1.Printingthequeue Thecontentsofthequeuecanbeprintedusingthemailqcommand(orbyspecifyingthe−bpflagtosendmail): Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 6 mailq Thiswillproducealistingofthequeueid’s,thesizeofthemessage,thedatethemessageenteredthequeue,andthesenderandrecipients. 2.3.2.Formatofqueuefiles AllqueuefileshavetheformxfAA99999whereAA99999istheidforthisfileand thexisatype.Thetypesare: dThedatafile.Themessagebody(excludingtheheader)iskeptinthisfile. lThelockfile.Ifthisfileexists,thejobiscurrentlybeingprocessed,andaqueue runwillnotprocessthefile.Forthatreason,anextraneouslffilecancauseajob toapparentlydisappear(itwillnoteventimeout!). nThisfileiscreatedwhenanidisbeingcreated.Itisaseparatefiletoinsurethat nomailcaneverbedestroyedduetoaracecondition.Itshouldexistfornomore thanafewmillisecondsatanygiventime. qThequeuecontrolfile.Thisfilecontainstheinformationnecessarytoprocessthe job. tAtemporaryfile.Theseareanimageoftheqffilewhenitisbeingrebuilt.It shouldberenamedtoaqffileveryquickly. xAtranscriptfile,existingduringthelifeofasessionshowingeverythingthathappensduringthatsession. Theqffileisstructuredasaseriesoflineseachbeginningwithacodeletter.The linesareasfollows: DThenameofthedatafile.Theremayonlybeoneoftheselines. HAheaderdefinition.Theremaybeanynumberoftheselines.Theorderis important:theyrepresenttheorderinthefinalmessage.Theseusethesamesyntaxasheaderdefinitionsintheconfigurationfile. RArecipientaddress.Thiswillnormallybecompletelyaliased,butisactually realiasedwhenthejobisprocessed.Therewillbeonelineforeachrecipient. SThesenderaddress.Theremayonlybeoneoftheselines. TThejobcreationtime.Thisisusedtocomputewhentotimeoutthejob. PThecurrentmessagepriority.Thisisusedtoorderthequeue.Highernumbers meanlowerpriorities.Thepriorityincreasesasthemessagesitsinthequeue. Theinitialprioritydependsonthemessageclassandthesizeofthemessage. MAmessage.Thislineisprintedbythemailqcommand,andisgenerallyusedto storestatusinformation.Itcancontainanytext. Asanexample,thefollowingisaqueuefilesentto“mckusick@calder”and“wnj”: Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 7 DdfA13557 Seric T404261372 P132 Rmckusick@calder Rwnj H?D?date:23-Oct-8215:49:32-PDT(Sat) H?F?from:eric(EricAllman) H?x?full-name:EricAllman Hsubject:thisisanexamplemessage Hmessage-id:<8209232249.13557@UCBARPA.BERKELEY.ARPA> Hreceived:byUCBARPA.BERKELEY.ARPA(3.227[10/22/82]) idA13557;23-Oct-8215:49:32-PDT(Sat) Hphone:(415)548-3211 HTo:mckusick@calder,wnj Thisshowsthenameofthedatafile,thepersonwhosentthemessage,thesubmission time(insecondssinceJanuary1,1970),themessagepriority,themessageclass,the recipients,andtheheadersforthemessage. 2.3.3.Forcingthequeue Sendmailshouldrunthequeueautomaticallyatintervals.Thealgorithmisto readandsortthequeue,andthentoattempttoprocessalljobsinorder.Whenit attemptstorunthejob,sendmailfirstcheckstoseeifthejobislocked.Ifso,itignores thejob. Thereisnoattempttoinsurethatonlyonequeueprocessorexistsatanytime, sincethereisnoguaranteethatajobcannottakeforevertoprocess.Duetothe lockingalgorithm,itisimpossibleforonejobtofreezethequeue.However,anuncooperativerecipienthostoraprogramrecipientthatneverreturnscanaccumulatemany processesinyoursystem.Unfortunately,thereisnowaytoresolvethiswithoutviolatingtheprotocol. Insomecases,youmayfindthatamajorhostgoingdownforacoupleofdays maycreateaprohibitivelylargequeue.Thiswillresultinsendmailspendinganinordinateamountoftimesortingthequeue.Thissituationcanbefixedbymovingthe queuetoatemporaryplaceandcreatinganewqueue.Theoldqueuecanberunlater whentheoffendinghostreturnstoservice. Todothis,itisacceptabletomovetheentirequeuedirectory: cd/usr/spool mvmqueueomqueue;mkdirmqueue;chmod777mqueue Youshouldthenkilltheexistingdaemon(sinceitwillstillbeprocessingintheold queuedirectory)andcreateanewdaemon. Toruntheoldmailqueue,runthefollowingcommand: /usr/lib/sendmail−oQ/usr/spool/omqueue−q The−oQflagspecifiesanalternatequeuedirectoryandthe−qflagsaystojustrun everyjobinthequeue.Ifyouhaveatendencytowardvoyeurism,youcanusethe−v flagtowatchwhatisgoingon. Whenthequeueisfinallyemptied,youcanremovethedirectory: rmdir/usr/spool/omqueue Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 8 2.4.TheAliasDatabase Thealiasdatabaseexistsintwoforms.Oneisatextform,maintainedinthefile /usr/lib/aliases.Thealiasesareoftheform name:name1,name2,... Onlylocalnamesmaybealiased;e.g., eric@mit-xx:eric@berkeley willnothavethedesiredeffect.Aliasesmaybecontinuedbystartinganycontinuation lineswithaspaceoratab.Blanklinesandlinesbeginningwithasharpsign(“#”)are comments. Thesecondformisprocessedbythedbm(3)library.Thisformisinthefiles /usr/lib/aliases.dirand/usr/lib/aliases.pag.Thisistheformthatsendmailactuallyuses toresolvealiases.Thistechniqueisusedtoimproveperformance. 2.4.1.Rebuildingthealiasdatabase TheDBMversionofthedatabasemayberebuiltexplicitlybyexecutingthecommand newaliases Thisisequivalenttogivingsendmailthe−biflag: /usr/lib/sendmail−bi Ifthe“D”optionisspecifiedintheconfiguration,sendmailwillrebuildthealias databaseautomaticallyifpossiblewhenitisoutofdate.Theconditionsunderwhichit willdothisare: (1)TheDBMversionofthedatabaseismode666.-or- (2)Sendmailisrunningsetuidtoroot. Auto-rebuildcanbedangerousonheavilyloadedmachineswithlargealiasfiles;ifit mighttakemorethanfiveminutestorebuildthedatabase,thereisachancethatseveralprocesseswillstarttherebuildprocesssimultaneously. 2.4.2.Potentialproblems Thereareanumberofproblemsthatcanoccurwiththealiasdatabase.Theyall resultfromasendmailprocessaccessingtheDBMversionwhileitisonlypartially built.Thiscanhappenundertwocircumstances:Oneprocessaccessesthedatabase whileanotherprocessisrebuildingit,ortheprocessrebuildingthedatabasedies(due tobeingkilledorasystemcrash)beforecompletingtherebuild. Sendmailhastwotechniquestotrytorelievetheseproblems.First,itignores interruptswhilerebuildingthedatabase;thisavoidstheproblemofsomeoneaborting theprocessleavingapartiallyrebuiltdatabase.Second,attheendoftherebuildit addsanaliasoftheform @:@ (whichisnotnormallylegal).Beforesendmailwillaccessthedatabase,itchecksto insurethatthisentryexists1.Itwillwaituptofiveminutesforthisentrytoappear,at 1The“a”optionisrequiredintheconfigurationforthisactiontooccur.Thisshouldnormallybespecifiedunless youarerunningdelivermailinparallelwithsendmail. Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 9 whichpointitwillforcearebuilditself2. 2.4.3.Listowners Ifanerroroccursonsendingtoacertainaddress,say“x”,sendmailwilllookfor analiasoftheform“owner-x”toreceivetheerrors.Thisistypicallyusefulforamail-inglistwherethesubmitterofthelisthasnocontroloverthemaintanenceofthelist itself;inthiscasethelistmaintainerwouldbetheownerofthelist.Forexample: unix-wizards:eric@ucbarpa,wnj@monet,nosuchuser, sam@matisse owner-unix-wizards:eric@ucbarpa wouldcause“eric@ucbarpa”togettheerrorthatwilloccurwhensomeonesendsto unix-wizardsduetotheinclusionof“nosuchuser”onthelist. 2.5.Per-UserForwarding(.forwardFiles) Asanalternativetothealiasdatabase,anyusermayputafilewiththename“.forward”inhisorherhomedirectory.Ifthisfileexists,sendmailredirectsmailforthatuser tothelistofaddresseslistedinthe.forwardfile.Forexample,ifthehomedirectoryfor user“mckusick”hasa.forwardfilewithcontents: mckusick@ernie kirk@calder thenanymailarrivingfor“mckusick”willberedirectedtothespecifiedaccounts. 2.6.SpecialHeaderLines Severalheaderlineshavespecialinterpretationsdefinedbytheconfigurationfile. Othershaveinterpretationsbuiltintosendmailthatcannotbechangedwithoutchanging thecode.Thesebuiltinsaredescribedhere. 2.6.1.Return-Receipt-To: Ifthisheaderissent,amessagewillbesenttoanyspecifiedaddresseswhenthe finaldeliveryiscomplete.ifthemailerhasthelflag(localdelivery)setinthemailer descriptor. 2.6.2.Errors-To: Iferrorsoccuranywhereduringprocessing,thisheaderwillcauseerrormessages togotothelistedaddressesratherthantothesender.Thisisintendedformailing lists. 2.6.3.Apparently-To: Ifamessagecomesinwithnorecipientslistedinthemessage(inaTo:,Cc:,or Bcc:line)thensendmailwilladdan“Apparently-To:”headerlineforanyrecipientsitis awareof.Thisisnotputinasastandardrecipientlinetowarnanyrecipientsthatthe listisnotcomplete. AtleastonerecipientlineisrequiredunderRFC822. 2Note:the“D”optionmustbespecifiedintheconfigurationfileforthisoperationtooccur. Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 10 3.ARGUMENTS ThecompletelistofargumentstosendmailisdescribedindetailinAppendixA.Some importantargumentsaredescribedhere. 3.1.QueueInterval Theamountoftimebetweenforkingaprocesstorunthroughthequeueisdefinedby the−qflag.Ifyouruninmodeforathiscanberelativelylarge,sinceitwillonlyberelevantwhenahostthatwasdowncomesbackup.Ifyouruninqmodeitshouldberelativelyshort,sinceitdefinesthemaximumamountoftimethatamessagemaysitinthe queue. 3.2.DaemonMode IfyouallowincomingmailoveranIPCconnection,youshouldhaveadaemonrunning.Thisshouldbesetbyyour/etc/rcfileusingthe−bdflag.The−bdflagandthe −qflagmaybecombinedinonecall: /usr/lib/sendmail−bd−q30m 3.3.ForcingtheQueue Insomecasesyoumayfindthatthequeuehasgottencloggedforsomereason.You canforceaqueuerunusingthe−qflag(withnovalue).Itisentertainingtousethe−v flag(verbose)whenthisisdonetowatchwhathappens: /usr/lib/sendmail−q−v 3.4.Debugging Thereareafairlylargenumberofdebugflagsbuiltintosendmail.Eachdebugflag hasanumberandalevel,wherehigherlevelsmeanstoprintoutmoreinformation.The conventionisthatlevelsgreaterthannineare“absurd,”i.e.,theyprintoutsomuchinformationthatyouwouldn’tnormallywanttoseethemexceptfordebuggingthatparticular pieceofcode.Debugflagsaresetusingthe−doption;thesyntaxis: debug-flag:−ddebug-list debug-list:debug-option[,debug-option] debug-option:debug-range[.debug-level] debug-range:integer|integer−integer debug-level:integer wherespacesareforreadingeaseonly.Forexample, −d12Setflag12tolevel1 −d12.3Setflag12tolevel3 −d3-17Setflags3through17tolevel1 −d3-17.4Setflags3through17tolevel4 Foracompletelistoftheavailabledebugflagsyouwillhavetolookatthecode(theyare toodynamictokeepthisdocumentationuptodate). 3.5.TryingaDifferentConfigurationFile Analternativeconfigurationfilecanbespecifiedusingthe−Cflag;forexample, /usr/lib/sendmail−Ctest.cf usestheconfigurationfiletest.cfinsteadofthedefault/usr/lib/sendmail.cf.Ifthe−Cflag hasnovalueitdefaultstosendmail.cfinthecurrentdirectory. Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 11 3.6.ChangingtheValuesofOptions Optionscanbeoverriddenusingthe−oflag.Forexample, /usr/lib/sendmail−oT2m setstheT(timeout)optiontotwominutesforthisrunonly. 4.TUNING Thereareanumberofconfigurationparametersyoumaywanttochange,dependingon therequirementsofyoursite.Mostofthesearesetusinganoptionintheconfigurationfile. Forexample,theline“OT3d”setsoption“T”tothevalue“3d”(threedays). 4.1.Timeouts Alltimeintervalsaresetusingascaledsyntax.Forexample,“10m”representsten minutes,whereas“2h30m”representstwoandahalfhours.Thefullsetofscalesis: sseconds mminutes hhours ddays wweeks 4.1.1.Queueinterval Theargumenttothe−qflagspecifieshowoftenasubdaemonwillrunthequeue. Thisistypicallysettobetweenfiveminutesandonehalfhour. 4.1.2.Readtimeouts Itispossibletotimeoutwhenreadingthestandardinputorwhenreadingfroma remoteSMTPserver.Technically,thisisnotacceptablewithinthepublishedprotocols. However,itmightbeappropriatetosetittosomethinglargeincertainenvironments (suchasanhour).Thiswillreducethechanceoflargenumbersofidledaemonspiling uponyoursystem.Thistimeoutissetusingtheroptionintheconfigurationfile. 4.1.3.Messagetimeouts Aftersittinginthequeueforafewdays,amessagewilltimeout.Thisisto insurethatatleastthesenderisawareoftheinabilitytosendamessage.Thetimeout istypicallysettothreedays.ThistimeoutissetusingtheToptionintheconfigurationfile. Thetimeofsubmissionissetinthequeue,ratherthantheamountoftimeleft untiltimeout.Asaresult,youcanflushmessagesthathavebeenhangingforashort periodbyrunningthequeuewithashortmessagetimeout.Forexample, /usr/lib/sendmail−oT1d−q willrunthequeueandflushanythingthatisonedayold. 4.2.DeliveryMode Thereareanumberofdeliverymodesthatsendmailcanoperatein,setbythe“d” configurationoption.Thesemodesspecifyhowquicklymailwillbedelivered.Legalmodes are: Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 12 ideliverinteractively(synchronously) bdeliverinbackground(asynchronously) qqueueonly(don’tdeliver) Therearetradeoffs.Mode“i”passesthemaximumamountofinformationtothesender, butishardlyevernecessary.Mode“q”putstheminimumloadonyourmachine,but meansthatdeliverymaybedelayedforuptothequeueinterval.Mode“b”isprobablya goodcompromise.However,thismodecancauselargenumbersofprocessesifyouhavea mailerthattakesalongtimetodeliveramessage. 4.3.LogLevel Thelevelofloggingcanbesetforsendmail.Thedefaultusingastandardconfigurationtableislevel9.Thelevelsareasfollows: 0Nologging. 1Majorproblemsonly. 2Messagecollectionsandfaileddeliveries. 3Successfuldeliveries. 4Messagesbeingdefered(duetoahostbeingdown,etc.). 5Normalmessagequeueups. 6Unusualbutbenignincidents,e.g.,tryingtoprocessalockedqueuefile. 9Loginternalqueueidtoexternalmessageidmappings.Thiscanbeusefulfortracing amessageasittravelsbetweenseveralhosts. 12Severalmessagesthatarebasicallyonlyofinterestwhendebugging. 16Verboseinformationregardingthequeue. 4.4.FileModes Thereareanumberoffilesthatmayhaveanumberofmodes.Themodesdependon whatfunctionalityyouwantandthelevelofsecurityyourequire. 4.4.1.Tosuidornottosuid? Sendmailcansafelybemadesetuidtoroot.Atthepointwhereitisaboutto exec(2)amailer,itcheckstoseeiftheuseridiszero;ifso,itresetstheuseridand groupidtoadefault(setbytheuandgoptions).(Thiscanbeoverriddenbysetting theSflagtothemailerformailersthataretrustedandmustbecalledasroot.)However,thiswillcausemailprocessingtobeaccounted(usingsa(8))torootratherthan totheusersendingthemail. 4.4.2.Temporaryfilemodes Themodeofalltemporaryfilesthatsendmailcreatesisdeterminedbythe“F” option.Reasonablevaluesforthisoptionare0600and0644.Ifthemorepermissive modeisselected,itwillnotbenecessarytorunsendmailasrootatall(evenwhenrunningthequeue). 4.4.3.Shouldmyaliasdatabasebewritable? AtBerkeleywehavethealiasdatabase(/usr/lib/aliases*)mode666.Thereare somedangersinherentinthisapproach:anyusercanaddhim-/her-selftoanylist,or can“steal”anyotheruser’smail.However,wehavefounduserstobebasicallytrustworthy,andthecostofhavingaread-onlydatabasegreaterthantheexpenseoffinding Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 13 anderadicatingtherarenastyperson. Thedatabasethatsendmailactuallyusedisrepresentedbythetwofiles aliases.dirandaliases.pag(bothin/usr/lib).Themodeonthesefilesshouldmatchthe modeon/usr/lib/aliases.IfaliasesiswritableandtheDBMfiles(aliases.dirand aliases.pag)arenot,userswillbeunabletoreflecttheirdesiredchangesthroughtothe actualdatabase.However,ifaliasesisread-onlyandtheDBMfilesarewritable,a slightlysophisticatedusercanarrangetostealmailanyway. IfyourDBMfilesarenotwritablebytheworldoryoudonothaveauto-rebuild enabled(withthe“D”option),thenyoumustbecarefultoreconstructthealias databaseeachtimeyouchangethetextversion: newaliases Ifthisstepisignoredorforgottenanyintendedchangeswillalsobeignoredorforgotten. 5.THEWHOLESCOOPONTHECONFIGURATIONFILE Thissectiondescribestheconfigurationfileindetail,includinghintsonhowtowriteone ofyourownifyouhaveto. Thereisonepointthatshouldbemadeclearimmediately:thesyntaxoftheconfigurationfileisdesignedtobereasonablyeasytoparse,sincethisisdoneeverytimesendmail startsup,ratherthaneasyforahumantoreadorwrite.Onthe“futureproject”listisaconfiguration-filecompiler. Anoverviewoftheconfigurationfileisgivenfirst,followedbydetailsofthesemantics. 5.1.TheSyntax Theconfigurationfileisorganizedasaseriesoflines,eachofwhichbeginswithasinglecharacterdefiningthesemanticsfortherestoftheline.Linesbeginningwithaspace oratabarecontinuationlines(althoughthesemanticsarenotwelldefinedinmany places).Blanklinesandlinesbeginningwithasharpsymbol(‘#’)arecomments. 5.1.1.RandS—rewritingrules Thecoreofaddressparsingaretherewritingrules.Theseareanorderedproductionsystem.Sendmailscansthroughthesetofrewritingruleslookingforamatchon thelefthandside(LHS)oftherule.Whenarulematches,theaddressisreplacedby therighthandside(RHS)oftherule. Thereareseveralsetsofrewritingrules.Someoftherewritingsetsareusedinternallyandmusthavespecificsemantics.Otherrewritingsetsdonothavespecifically assignedsemantics,andmaybereferencedbythemailerdefinitionsorbyotherrewritingsets. Thesyntaxofthesetwocommandsare: Sn Setsthecurrentrulesetbeingcollectedton.Ifyoubeginarulesetmorethanonceit deletestheolddefinition. Rlhsrhscomments Thefieldsmustbeseparatedbyatleastonetabcharacter;theremaybeembedded spacesinthefields.Thelhsisapatternthatisappliedtotheinput.Ifitmatches,the inputisrewrittentotherhs.Thecommentsareignored. Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 14 5.1.2.D—definemacro Macrosarenamedwithasinglecharacter.Thesemaybeselectedfromtheentire ASCIIset,butuser-definedmacrosshouldbeselectedfromthesetofuppercaseletters only.Lowercaselettersandspecialsymbolsareusedinternally. Thesyntaxformacrodefinitionsis: Dxval wherexisthenameofthemacroandvalisthevalueitshouldhave.Macroscanbe interpolatedinmostplacesusingtheescapesequence$x. 5.1.3.CandF—defineclasses Classesofwordsmaybedefinedtomatchonthelefthandsideofrewritingrules. Forexampleaclassofalllocalnamesforthissitemightbecreatedsothatattemptsto sendtooneselfcanbeeliminated.Thesecaneitherbedefineddirectlyintheconfigurationfileorreadinfromanotherfile.Classesmaybegivennamesfromthesetofupper caseletters.Lowercaselettersandspecialcharactersarereservedforsystemuse. Thesyntaxis: Ccword1word2... Fcfile[format] Thefirstformdefinestheclassctomatchanyofthenamedwords.Itispermissibleto splitthemamongmultiplelines;forexample,thetwoforms: CHmonetucbmonet and CHmonet CHucbmonet areequivalent.Thesecondformreadstheelementsoftheclasscfromthenamedfile; theformatisascanf(3)patternthatshouldproduceasinglestring. 5.1.4.M—definemailer Programsandinterfacestomailersaredefinedinthisline.Theformatis: Mname,{field=value}* wherenameisthenameofthemailer(usedinternallyonly)andthe“field=name”pairs defineattributesofthemailer.Fieldsare: PathThepathnameofthemailer FlagsSpecialflagsforthismailer SenderArewritingsetforsenderaddresses RecipientArewritingsetforrecipientaddresses ArgvAnargumentvectortopasstothismailer EolTheend-of-linestringforthismailer MaxsizeThemaximummessagelengthtothismailer Onlythefirstcharacterofthefieldnameischecked. 5.1.5.H—defineheader Theformatoftheheaderlinesthatsendmailinsertsintothemessagearedefined bytheHline.Thesyntaxofthislineis: H[?mflags?]hname:htemplate Continuationlinesinthisspecarereflecteddirectlyintotheoutgoingmessage.The Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 15 htemplateismacroexpandedbeforeinsertionintothemessage.Ifthemflags(surroundedbyquestionmarks)arespecified,atleastoneofthespecifiedflagsmustbe statedinthemailerdefinitionforthisheadertobeautomaticallyoutput.Ifoneof theseheadersisintheinputitisreflectedtotheoutputregardlessoftheseflags. Someheadershavespecialsemanticsthatwillbedescribedbelow. 5.1.6.O—setoption Thereareanumberof“random”optionsthatcanbesetfromaconfigurationfile. Optionsarerepresentedbysinglecharacters.Thesyntaxofthislineis: Oovalue Thissetsoptionotobevalue.Dependingontheoption,valuemaybeastring,an integer,aboolean(withlegalvalues“t”,“T”,“f”,or“F”;thedefaultisTRUE),ora timeinterval. 5.1.7.T—definetrustedusers Trustedusersarethoseuserswhoarepermittedtooverridethesenderaddress usingthe−fflag.Thesetypicallyare“root,”“uucp,”and“network,”butonsome usersitmaybeconvenienttoextendthislisttoincludeotherusers,perhapstosupport aseparateUUCPloginforeachhost.Thesyntaxofthislineis: Tuser1user2... Theremaybemorethanoneoftheselines. 5.1.8.P—precedencedefinitions Valuesforthe“Precedence:”fieldmaybedefinedusingthePcontrolline.The syntaxofthisfieldis: Pname=num Whenthenameisfoundina“Precedence:”field,themessageclassissettonum. Highernumbersmeanhigherprecedence.Numberslessthanzerohavethespecial propertythaterrormessageswillnotbereturned.Thedefaultprecedenceiszero.For example,ourlistofprecedencesis: Pfirst-class=0 Pspecial-delivery=100 Pjunk=−100 5.2.TheSemantics Thissectiondescribesthesemanticsoftheconfigurationfile. 5.2.1.Specialmacros,conditionals Macrosareinterpolatedusingtheconstruct$x,wherexisthenameofthemacro tobeinterpolated.Inparticular,lowercaselettersarereservedtohavespecialsemantics,usedtopassinformationinoroutofsendmail,andsomespecialcharactersare reservedtoprovideconditionals,etc. Thefollowingmacrosmustbedefinedtotransmitinformationintosendmail: Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 16 eTheSMTPentrymessage jThe“official”domainnameforthissite lTheformatoftheUNIXfromline nThenameofthedaemon(forerrormessages) oThesetof"operators"inaddresses qdefaultformatofsenderaddress The$emacroisprintedoutwhenSMTPstartsup.Thefirstwordmustbethe$j macro.The$jmacroshouldbeinRFC821format.The$land$nmacroscanbeconsideredconstantsexceptunderterriblyunusualcircumstances.The$omacroconsists ofalistofcharacterswhichwillbeconsideredtokensandwhichwillseparatetokens whendoingparsing.Forexample,if“r”wereinthe$omacro,thentheinput “address”wouldbescannedasthreetokens:“add,”“r,”and“ess.”Finally,the$q macrospecifieshowanaddressshouldappearinamessagewhenitisdefaulted.For example,onoursystemthesedefinitionsare: De$jSendmail$vreadyat$b DnMAILER-DAEMON DlFrom$g$d Do.:%@!ˆ =/ Dq$g$?x($x)$. Dj$H.$D Anacceptablealternativeforthe$qmacrois“$?x$x$.<$g>”.Thesecorrespondto thefollowingtwoformats: eric@Berkeley(EricAllman) EricAllman<eric@Berkeley> Somemacrosaredefinedbysendmailforinterpolationintoargv’sformailersor forothercontexts.Thesemacrosare: aTheoriginationdateinArpanetformat bThecurrentdateinArpanetformat cThehopcount dThedateinUNIX(ctime)format fThesender(from)address gThesenderaddressrelativetotherecipient hTherecipienthost iThequeueid pSendmail’spid rProtocolused sSender’shostname tAnumericrepresentationofthecurrenttime uTherecipientuser vTheversionnumberofsendmail wThehostnameofthissite xThefullnameofthesender yTheidofthesender’stty zThehomedirectoryoftherecipient Therearethreetypesofdatesthatcanbeused.The$aand$bmacrosarein Arpanetformat;$aisthetimeasextractedfromthe“Date:”lineofthemessage(if therewasone),and$bisthecurrentdateandtime(usedforpostmarks).Ifno “Date:”lineisfoundintheincomingmessage,$aissettothecurrenttimealso.The $dmacroisequivalenttothe$amacroinUNIX(ctime)format. Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 17 The$fmacroistheidofthesenderasoriginallydetermined;whenmailingtoa specifichostthe$gmacroissettotheaddressofthesenderrelativetotherecipient. Forexample,ifIsendto“bollard@matisse”fromthemachine“ucbarpa”the$fmacro willbe“eric”andthe$gmacrowillbe“eric@ucbarpa.” The$xmacroissettothefullnameofthesender.Thiscanbedeterminedin severalways.Itcanbepassedasflagtosendmail.Thesecondchoiceisthevalueof the“Full-name:”lineintheheaderifitexists,andthethirdchoiceisthecommentfield ofa“From:”line.Ifallofthesefail,andifthemessageisbeingoriginatedlocally,the fullnameislookedupinthe/etc/passwdfile. Whensending,the$h,$u,and$zmacrosgetsettothehost,user,andhome directory(iflocal)oftherecipient.Thefirsttwoaresetfromthe$@and$:partof therewritingrules,respectively. The$pand$tmacrosareusedtocreateuniquestrings(e.g.,forthe“Message-Id:”field).The$imacroissettothequeueidonthishost;ifputintothetimestamp lineitcanbeextremelyusefulfortrackingmessages.The$ymacroissettotheidof theterminalofthesender(ifknown);somesystemsliketoputthisintheUnix“From” line.The$vmacroissettobetheversionnumberofsendmail;thisisnormallyputin timestampsandhasbeenprovenextremelyusefulfordebugging.The$wmacroisset tothenameofthishostifitcanbedetermined.The$cfieldissettothe“hopcount,” i.e.,thenumberoftimesthismessagehasbeenprocessed.Thiscanbedeterminedby the−hflagonthecommandlineorbycountingthetimestampsinthemessage. The$rand$sfieldsaresettotheprotocolusedtocommunicatewithsendmail andthesendinghostname;thesearenotsupportedinthecurrentversion. Conditionalscanbespecifiedusingthesyntax: $?xtext1$|text2$. Thisinterpolatestext1ifthemacro$xisset,andtext2otherwise.The“else”($|) clausemaybeomitted. 5.2.2.Specialclasses Theclass$=wissettobethesetofallnamesthishostisknownby.Thiscan beusedtodeletelocalhostnames. 5.2.3.Thelefthandside Thelefthandsideofrewritingrulescontainsapattern.Normalwordsaresimply matcheddirectly.Metasyntaxisintroducedusingadollarsign.Themetasymbolsare: $*Matchzeroormoretokens $+Matchoneormoretokens $−Matchexactlyonetoken $=xMatchanytokeninclassx $˜ xMatchanytokennotinclassx Ifanyofthesematch,theyareassignedtothesymbol$nforreplacementontheright handside,wherenistheindexintheLHS.Forexample,iftheLHS: $−:$+ isappliedtotheinput: UCBARPA:eric therulewillmatch,andthevaluespassedtotheRHSwillbe: Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 18 $1UCBARPA $2eric 5.2.4.Therighthandside Whentherighthandsideofarewritingrulematches,theinputisdeletedand replacedbytherighthandside.TokensarecopieddirectlyfromtheRHSunlessthey arebeginwithadollarsign.Metasymbolsare: $nSubstituteindefinitetokennfromLHS $>n“Call”rulesetn $#mailerResolvetomailer $@hostSpecifyhost $:userSpecifyuser The$nsyntaxsubstitutesthecorrespondingvaluefroma$+,$−,$*,$=,or$˜ matchontheLHS.Itmaybeusedanywhere. The$>nsyntaxcausestheremainderofthelinetobesubstitutedasusualand thenpassedastheargumenttorulesetn.Thefinalvalueofrulesetnthenbecomesthe substitutionforthisrule. The$#syntaxshouldonlybeusedinrulesetzero.Itcausesevaluationofthe rulesettoterminateimmediately,andsignalstosendmailthattheaddresshascompletelyresolved.Thecompletesyntaxis: $#mailer$@host$:user Thisspecifiesthe{mailer,host,user}3-tuplenecessarytodirectthemailer.Ifthe mailerislocalthehostpartmaybeomitted.Themailerandhostmustbeasingle word,buttheusermaybemulti-part. ARHSmayalsobepreceededbya$@ora$:tocontrolevaluation.A$@prefix causestherulesettoreturnwiththeremainderoftheRHSasthevalue.A$:prefix causestheruletoterminateimmediately,buttherulesettocontinue;thiscanbeused toavoidcontinuedapplicationofarule.Theprefixisstrippedbeforecontinuing. The$@and$:prefixesmaypreceeda$>spec;forexample: R$+$:$>7$1 matchesanything,passesthattorulesetseven,andcontinues;the$:isnecessaryto avoidaninfiniteloop. 5.2.5.Semanticsofrewritingrulesets Therearefiverewritingsetsthathavespecificsemantics.Thesearerelatedas depictedbyfigure2. Rulesetthreeshouldturntheaddressinto“canonicalform.”Thisformshould havethebasicsyntax: local-part@host-domain-spec Ifno“@”signisspecified,thenthehost-domain-specmaybeappendedfromthesender address(iftheCflagissetinthemailerdefinitioncorrespondingtothesending mailer).Rulesetthreeisappliedbysendmailbeforedoinganythingwithanyaddress. Rulesetzeroisappliedafterrulesetthreetoaddressesthataregoingtoactually specifyrecipients.Itmustresolvetoa{mailer,host,user}triple.Themailermustbe definedinthemailerdefinitionsfromtheconfigurationfile.Thehostisdefinedintothe $hmacroforuseintheargvexpansionofthespecifiedmailer. Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 19 Rulesetsoneandtwoareappliedtoallsenderandrecipientaddressesrespectively. Theyareappliedbeforeanyspecificationinthemailerdefinition.Theymustnever resolve. Rulesetfourisappliedtoalladdressesinthemessage.Itistypicallyusedto translateinternaltoexternalform. 5.2.6.Mailerflagsetc. Thereareanumberofflagsthatmaybeassociatedwitheachmailer,eachidentifiedbyaletterofthealphabet.Manyofthemareassignedsemanticsinternally.These aredetailedinAppendixC.Anyotherflagsmaybeusedfreelytoconditionallyassign headerstomessagesdestinedforparticularmailers. 5.2.7.The“error”mailer Themailerwiththespecialname“error”canbeusedtogenerateausererror. The(optional)hostfieldisanumericexitstatustobereturned,andtheuserfieldisa messagetobeprinted.Forexample,theentry: $#error$:Hostunknowninthisdomain ontheRHSofarulewillcausethespecifiederrortobegeneratediftheLHSmatches. Thismailerisonlyfunctionalinrulesetzero. 5.3.BuildingaConfigurationFileFromScratch Buildingaconfigurationtablefromscratchisanextremelydifficultjob.Fortunately, itisalmostnevernecessarytodoso;nearlyeverysituationthatmaycomeupmaybe resolvedbychanginganexistingtable.Inanycase,itiscriticalthatyouunderstandwhat itisthatyouaretryingtodoandcomeupwithaphilosophyfortheconfigurationtable. Thissectionisintendedtoexplainwhattherealpurposeofaconfigurationtableisandto giveyousomeideasforwhatyourphilosophymightbe. 5.3.1.Whatyouaretryingtodo Theconfigurationtablehasthreemajorpurposes.Thefirstandsimplestistoset uptheenvironmentforsendmail.Thisinvolvessettingtheoptions,definingafewcriticalmacros,etc.Sincethesearedescribedinotherplaces,wewillnotgointomore detailhere. Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 20 Thesecondpurposeistorewriteaddressesinthemessage.Thisshouldtypically bedoneintwophases.Thefirstphasemapsaddressesinanyformatintoacanonical form.Thisshouldbedoneinrulesetthree.Thesecondphasemapsthiscanonicalform intothesyntaxappropriateforthereceivingmailer.Sendmaildoesthisinthreesubphases.Rulesetsoneandtwoareappliedtoallsenderandrecipientaddressesrespectively.Afterthis,youmayspecifyper-mailerrulesetsforbothsenderandrecipient addresses;thisallowsmailer-specificcustomization.Finally,rulesetfourisappliedto doanydefaultconversiontoexternalform. Thethirdpurposeistomapaddressesintotheactualsetofinstructionsnecessary togetthemessagedelivered.Rulesetzeromustresolvetotheinternalform,whichisin turnusedasapointertoamailerdescriptor.Themailerdescriptordescribestheinterfacerequirementsofthemailer. 5.3.2.Philosophy Theparticularphilosophyyouchoosewilldependheavilyonthesizeandstructureofyourorganization.Iwillpresentafewpossiblephilosophieshere. Onegeneralpointappliestoallofthesephilosophies:itisalmostalwaysamistake totrytodofullnameresolution.Forexample,ifyouaretryingtogetnamesofthe form“user@host”totheArpanet,itdoesnotpaytoroutethemto“xyzvax!decvax!ucbvax!c70:user@host”sinceyouthendependonseverallinksnotunder yourcontrol.Thebestapproachtothisproblemistosimplyforwardto“xyzvax!user@host”andletxyzvaxworryaboutitfromthere.Insummary,justgetthe messageclosertothedestination,ratherthandeterminingthefullpath. 5.3.2.1.Largesite,manyhosts—minimuminformation Berkeleyisanexampleofalargesite,i.e.,morethantwoorthreehosts.We havedecidedthattheonlyreasonablephilosophyinourenvironmentistodesignate onehostastheguruforoursite.Itmustbeabletoresolveanypieceofmailit receives.Theothersitesshouldhavetheminimumamountofinformationtheycan getawaywith.Inaddition,anyinformationtheydohaveshouldbehintsrather thansolidinformation. Forexample,atypicalsiteonourlocalethernetworkis“monet.”Monethasa listofknownethernethosts;ifitreceivesmailforanyofthem,itcandodirect delivery.Ifitreceivesmailforanyunknownhost,itjustpassesitdirectlyto“ucbvax,”ourmasterhost.Ucbvaxmaydeterminethatthehostnameisillegaland rejectthemessage,ormaybeabletododelivery.However,itisimportanttonote thatwhenanewethernethostisadded,theonlyhostthatmusthaveitstables updatedisucbvax;theothersmaybeupdatedasconvenient,butthisisnotcritical. Thispictureisslightlymuddiedduetonetworkconnectionsthatarenotactuallylocatedonucbvax.Forexample,ourTCPconnectioniscurrentlyon “ucbarpa.”However,monetdoesnotknowaboutthis;theinformationishidden totallybetweenucbvaxanducbarpa.MailgoingfrommonettoaTCPhostis transferedviatheethernetfrommonettoucbvax,thenviatheethernetfromucbvax toucbarpa,andthenissubmittedtotheArpanet.Althoughthisinvolvessome extrahops,wefeelthisisanacceptabletradeoff. AninterestingpointisthatitwouldbepossibletoupdatemonettosendTCP maildirectlytoucbarpaiftheloadgottoohigh;ifmonetfailedtonoteahostasa TCPhostitwouldgoviaucbvaxasbefore,andifmonetincorrectlysentamessage toucbarpaitwouldstillbesentbyucbarpatoucbvaxasbefore.Theonlyproblem thatcanoccurisloops,asifucbarpathoughtthatucbvaxhadtheTCPconnection andviceversa.Forthisreason,updatesshouldalwayshappentothemasterhost Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 21 first. Thisphilosophyresultsasmuchfromtheneedtohaveasinglesourceforthe configurationfiles(typicallybuiltusingm4(1)orsomesimilartool)asanylogical need.Maintainingmorethanthreeseparatetablesbyhandisessentiallyanimpossiblejob. 5.3.2.2.Smallsite—completeinformation Asmallsite(twoorthreehosts)mayfinditmorereasonabletohavecomplete informationateachhost.Thiswouldrequirethateachhostknowexactlywhere eachnetworkconnectionis,possiblyincludingthenamesofeachhostonthatnetwork.Aslongasthesiteremainssmallandthetheconfigurationremainsrelatively static,theupdateproblemwillprobablynotbetoogreat. 5.3.2.3.Singlehost Thisisinsomesensethetrivialcase.Theonlymajorissueistryingtoinsure thatyoudon’thavetoknowtoomuchaboutyourenvironment.Forexample,ifyou haveaUUCPconnectionyoumightfinditusefultoknowaboutthenamesofhosts connecteddirectlytoyou,butthisisreallynotnecessarysincethismaybedeterminedfromthesyntax. 5.3.3.Relevantissues ThecanonicalformyouuseshouldalmostcertainlybeasspecifiedintheArpanet protocolsRFC819andRFC822.CopiesoftheseRFC’sareincludedonthesendmail tapeasdoc/rfc819.lpranddoc/rfc822.lpr. RFC822describestheformatofthemailmessageitself.Sendmailfollowsthis RFCclosely,totheextentthatmanyofthestandardsdescribedinthisdocumentcan notbechangedwithoutchangingthecode.Inparticular,thefollowingcharactershave specialinterpretations: <>()"\ AnyattempttousethesecharactersforotherthantheirRFC822purposeinaddresses isprobablydoomedtodisaster. RFC819describesthespecificsofthedomain-basedaddressing.Thisistouched oninRFC822aswell.Essentiallyeachhostisgivenanamewhichisaright-to-leftdot qualifiedpseudo-pathfromadistinguishedroot.Theelementsofthepathneednotbe physicalhosts;thedomainislogicalratherthanphysical.Forexample,atBerkeleyone legalhostis“a.cc.berkeley.arpa”;readingfromrighttoleft,“arpa”isatopleveldomain (relatedto,butnotlimitedto,thephysicalArpanet),“berkeley”isbothanArpanet hostandalogicaldomainwhichisactuallyinterpretedbyahostcalleducbvax(which isactuallyjustthe“major”hostforthisdomain),“cc”representstheComputerCenter,(inthiscaseastrictlylogicalentity),and“a”isahostintheComputerCenter; thisparticularhosthappenstobeconnectedviaberknet,butotherhostsmightbeconnectedviaoneoftwoethernetsorsomeothernetwork. BewarewhenreadingRFC819thatthereareanumberoferrorsinit. 5.3.4.Howtoproceed Onceyouhavedecidedonaphilosophy,itisworthexaminingtheavailableconfigurationtablestodecideifanyofthemarecloseenoughtostealmajorpartsof.Even undertheworstofconditions,thereisafairamountofboilerplatethatcanbecollectedsafely. Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 22 Thenextstepistobuildrulesetthree.Thiswillbethehardestpartofthejob. Bewareofdoingtoomuchtotheaddressinthisruleset,sinceanythingyoudowill reflectthroughtothemessage.Inparticular,strippingoflocaldomainsisbest deferred,sincethiscanleaveyouwithaddresseswithnodomainspecatall.Since sendmaillikestoappendthesendingdomaintoaddresseswithnodomain,thiscan changethesemanticsofaddresses.Alsotrytoavoidfullyqualifyingdomainsinthis ruleset.Althoughtechnicallylegal,thiscanleadtounpleasantlyandunnecessarilylong addressesreflectedintomessages.TheBerkeleyconfigurationfilesdefinerulesetnineto qualifydomainnamesandstriplocaldomains.Thisiscalledfromrulesetzerotoget alladdressesintoacleanerform. Onceyouhaverulesetthreefinished,theotherrulesetsshouldberelativelytrivial. Ifyouneedhints,examinethesuppliedconfigurationtables. 5.3.5.Testingtherewritingrules—the−btflag Whenyoubuildaconfigurationtable,youcandoacertainamountoftesting usingthe“testmode”ofsendmail.Forexample,youcouldinvokesendmailas: sendmail−bt−Ctest.cf whichwouldreadtheconfigurationfile“test.cf”andentertestmode.Inthismode,you enterlinesoftheform: rwsetaddress whererwsetistherewritingsetyouwanttouseandaddressisanaddresstoapplythe setto.Testmodeshowsyouthestepsittakesasitproceeds,finallyshowingyouthe addressitendsupwith.Youmayuseacommaseparatedlistofrwsetsforsequential applicationofrulestoaninput;rulesetthreeisalwaysappliedfirst.Forexample: 1,21,4monet:bollard firstappliesrulesetthreetotheinput“monet:bollard.”Rulesetoneisthenappliedto theoutputofrulesetthree,followedsimilarlybyrulesetstwenty-oneandfour. Ifyouneedmoredetail,youcanalsousethe“−d21”flagtoturnonmoredebugging.Forexample, sendmail−bt−d21.99 turnsonanincredibleamountofinformation;asinglewordaddressisprobablygoing toprintoutseveralpagesworthofinformation. 5.3.6.Buildingmailerdescriptions Toaddanoutgoingmailertoyourmailsystem,youwillhavetodefinethecharacteristicsofthemailer. Eachmailermusthaveaninternalname.Thiscanbearbitrary,exceptthatthe names“local”and“prog”mustbedefined. ThepathnameofthemailermustbegiveninthePfield.Ifthismailershouldbe accessedviaanIPCconnection,usethestring“[IPC]”instead. TheFfielddefinesthemailerflags.Youshouldspecifyan“f”or“r”flagtopass thenameofthesenderasa−for−rflagrespectively.Theseflagsareonlypassedif theywerepassedtosendmail,sothatmailersthatgiveerrorsundersomecircumstances canbeplacated.Ifthemailerisnotpickyyoucanjustspecify“−f$g”intheargv template.Ifthemailermustbecalledasrootthe“S”flagshouldbegiven;thiswill Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 23 notresettheuseridbeforecallingthemailer3.Ifthismailerislocal(i.e.,willperform finaldeliveryratherthananothernetworkhop)the“l”flagshouldbegiven.Quote characters(backslashesand"marks)canbestrippedfromaddressesifthe“s”flagis specified;ifthisisnotgiventheyarepassedthrough.Ifthemaileriscapableofsendingtomorethanoneuseronthesamehostinasingletransactionthe“m”flagshould bestated.Ifthisflagison,thentheargvtemplatecontaining$uwillberepeatedfor eachuniqueuseronagivenhost.The“e”flagwillmarkthemailerasbeing“expensive,”whichwillcausesendmailtodeferconnectionuntilaqueuerun4. Anunusualcaseisthe“C”flag.Thisflagappliestothemailerthatthemessage isreceivedfrom,ratherthanthemailerbeingsentto;ifset,thedomainspecofthe sender(i.e.,the“@host.domain”part)issavedandisappendedtoanyaddressesinthe messagethatdonotalreadycontainadomainspec.Forexample,amessageofthe form: From:eric@ucbarpa To:wnj@monet,mckusick willbemodifiedto: From:eric@ucbarpa To:wnj@monet,mckusick@ucbarpa ifandonlyifthe“C”flagisdefinedinthemailercorrespondingto“eric@ucbarpa.” OtherflagsaredescribedinAppendixC. TheSandRfieldsinthemailerdescriptionareper-mailerrewritingsetstobe appliedtosenderandrecipientaddressesrespectively.Theseareappliedafterthesendingdomainisappendedandthegeneralrewritingsets(numbersoneandtwo)are applied,butbeforetheoutputrewrite(rulesetfour)isapplied.Atypicaluseisto appendthecurrentdomaintoaddressesthatdonotalreadyhaveadomain.Forexample,aheaderoftheform: From:eric mightbechangedtobe: From:eric@ucbarpa or From:ucbvax!eric dependingonthedomainitisbeingshippedinto.Thesesetscanalsobeusedtodo specialpurposeoutputrewritingincooperationwithrulesetfour. TheEfielddefinesthestringtouseasanend-of-lineindication.Astringcontain-ingonlynewlineisthedefault.Theusualbackslashescapes(\r,\n,\f,\b)maybe used. Finally,anargvtemplateisgivenastheEfield.Itmayhaveembeddedspaces. Ifthereisnoargvwitha$umacroinit,sendmailwillspeakSMTPtothemailer.If thepathnameforthismaileris“[IPC],”theargvshouldbe IPC$h[port] whereportistheoptionalportnumbertoconnectto. 3Sendmailmustberunningsetuidtorootforthistowork. 4The“c”configurationoptionmustbegivenforthistobeeffective. Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 24 Forexample,thespecifications: Mlocal,P=/bin/mail,F=rlsmS=10,R=20,A=mail−d$u Mether,P=[IPC],F=meC,S=11,R=21,A=IPC$h,M=100000 specifiesamailertodolocaldeliveryandamailerforethernetdelivery.Thefirstis called“local,”islocatedinthefile“/bin/mail,”takesapicky−rflag,doeslocaldelivery,quotesshouldbestrippedfromaddresses,andmultipleuserscanbedeliveredat once;rulesettenshouldbeappliedtosenderaddressesinthemessageandruleset twentyshouldbeappliedtorecipientaddresses;theargvtosendtoamessagewillbe theword“mail,”theword“−d,”andwordscontainingthenameofthereceivinguser. Ifa−rflagisinserteditwillbebetweenthewords“mail”and“−d.”Thesecond maileriscalled“ether,”itshouldbeconnectedtoviaanIPCconnection,itcanhandle multipleusersatonce,connectionsshouldbedeferred,andanydomainfromthesender addressshouldbeappendedtoanyreceivernamewithoutadomain;senderaddresses shouldbeprocessedbyrulesetelevenandrecipientaddressesbyrulesettwenty-one. Thereisa100,000bytelimitonmessagespassedthroughthismailer. Version4.2 LastMod7/28/83 APPENDIXA COMMANDLINEFLAGS Argumentsmustbepresentedwithflagsbeforeaddresses.Theflagsare: −faddrThesender’smachineaddressisaddr.Thisflagisignoredunlesstherealuseris listedasa“trusteduser”orifaddrcontainsanexclamationpoint(becauseofcertainrestrictionsinUUCP). −raddrAnobsoleteformof−f. −hcntSetsthe“hopcount”tocnt.Thisrepresentsthenumberoftimesthismessage hasbeenprocessedbysendmail(totheextentthatitissupportedbytheunderlyingnetworks).Cntisincrementedduringprocessing,andifitreachesMAX-HOP(currently30)sendmailthrowsawaythemessagewithanerror. −FnameSetsthefullnameofthisusertoname. −nDon’tdoaliasingorforwarding. −tReadtheheaderfor“To:”,“Cc:”,and“Bcc:”lines,andsendtoeveryonelistedin thoselists.The“Bcc:”linewillbedeletedbeforesending.Anyaddressesinthe argumentvectorwillbedeletedfromthesendlist. −bxSetoperationmodetox.Operationmodesare: mDelivermail(default) aRuninarpanetmode(seebelow) sSpeakSMTPoninputside dRunasadaemon tRunintestmode vJustverifyaddresses,don’tcollectordeliver iInitializethealiasdatabase pPrintthemailqueue zFreezetheconfigurationfile ThespecialprocessingfortheARPANETincludesreadingthe“From:”linefrom theheadertofindthesender,printingARPANETstylemessages(precededby threedigitreplycodesforcompatibilitywiththeFTPprotocol[Neigus73,Postel74,Postel77]),andendinglinesoferrormessageswith<CRLF>. −qtimeTrytoprocessthequeuedupmail.Ifthetimeisgiven,asendmailwillrun throughthequeueatthespecifiedintervaltodeliverqueuedmail;otherwise,it onlyrunsonce. −CfileUseadifferentconfigurationfile. −dlevelSetdebugginglevel. −oxvalueSetoptionxtothespecifiedvalue.TheseoptionsaredescribedinAppendixB. Thereareanumberofoptionsthatmaybespecifiedasprimitiveflags(providedforcompatibilitywithdelivermail).Thesearethee,i,m,andvoptions.Also,thefoptionmaybespecified asthe−sflag. SendmailInstallationandOperationGuide 25 APPENDIXB CONFIGURATIONOPTIONS Thefollowingoptionsmaybesetusingthe−oflagonthecommandlineortheOlinein theconfigurationfile: AfileUsethenamedfileasthealiasfile.Ifnofileisspecified,usealiasesinthecurrentdirectory. aIfset,waitforan“@:@”entrytoexistinthealiasdatabasebeforestartingup.If itdoesnotappearinfiveminutes,rebuildthedatabase. cIfanoutgoingmailerismarkedasbeingexpensive,don’tconnectimmediately. Thisrequiresthatqueueingbecompiledin,sinceitwilldependonaqueuerun processtoactuallysendthemail. dxDeliverinmodex.Legalmodesare: iDeliverinteractively(synchronously) bDeliverinbackground(asynchronously) qJustqueuethemessage(deliverduringqueuerun) DIfset,rebuildthealiasdatabaseifnecessaryandpossible.Ifthisoptionisnot set,sendmailwillneverrebuildthealiasdatabaseunlessexplicitlyrequested using−bi. exDisposeoferrorsusingmodex.Thevaluesforxare: pPrinterrormessages(default) qNomessages,justgiveexitstatus mMailbackerrors wWritebackerrors(mailifusernotloggedin) eMailbackerrorsandgivezeroexitstatalways FnThetemporaryfilemode,inoctal.644and600aregoodchoices. fSaveUnix-style“From”linesatthefrontofheaders.Normallytheyareassumed redundantanddiscarded. gnSetthedefaultgroupidformailerstoruninton. HfileSpecifythehelpfileforSMTP. iIgnoredotsinincomingmessages. LnSetthedefaultloglevelton. MxvalueSetthemacroxtovalue.Thisisintendedonlyforusefromthecommandline. mSendtometoo,evenifIaminanaliasexpansion. oAssumethattheheadersmaybeinoldformat,i.e.,spacesdelimitnames.This actuallyturnsonanadaptivealgorithm:ifanyrecipientaddresscontainsa comma,parenthesis,oranglebracket,itwillbeassumedthatcommasalready exist.Ifthisflagisnoton,onlycommasdelimitnames.Headersarealwaysoutputwithcommasbetweenthenames. SendmailInstallationandOperationGuide 26 SendmailInstallationandOperationGuide 27 QdirUsethenameddirasthequeuedirectory. rtimeTimeoutreadsaftertimeinterval. SfileLogstatisticsinthenamedfile. sBesuper-safewhenrunningthings,i.e.,alwaysinstantiatethequeuefile,evenif youaregoingtoattemptimmediatedelivery.Sendmailalwaysinstantiatesthe queuefilebeforereturningcontrolthetheclientunderanycircumstances. TtimeSetthequeuetimeouttotime.Afterthisinterval,messagesthathavenotbeen successfullysentwillbereturnedtothesender. tS,DSetthelocaltimezonenametoSforstandardtimeandDfordaylighttime;this isonlyusedunderversionsix. unSetthedefaultuseridformailerston.MailerswithouttheSflaginthemailer definitionwillrunasthisuser. vRuninverbosemode. Version4.2 LastMod7/28/83 APPENDIXC MAILERFLAGS Thefollowingflagsmaybesetinthemailerdescription. fThemailerwantsa−ffromflag,butonlyifthisisanetworkforwardoperation(i.e.,the mailerwillgiveanerroriftheexecutinguserdoesnothavespecialpermissions). rSameasf,butsendsa−rflag. SDon’tresettheuseridbeforecallingthemailer.Thiswouldbeusedinasecureenvironment wheresendmailranasroot.Thiscouldbeusedtoavoidforgedaddresses.Thisflagissuppressedifgivenfroman“unsafe”environment(e.g,auser’smail.cffile). nDonotinsertaUNIX-style“From”lineonthefrontofthemessage. lThismailerislocal(i.e.,finaldeliverywillbeperformed). sStripquotecharactersoffoftheaddressbeforecallingthemailer. mThismailercansendtomultipleusersonthesamehostinonetransaction.Whena$u macrooccursintheargvpartofthemailerdefinition,thatfieldwillberepeatedasnecessary forallqualifyingusers. FThismailerwantsa“From:”headerline. DThismailerwantsa“Date:”headerline. MThismailerwantsa“Message-Id:”headerline. xThismailerwantsa“Full-Name:”headerline. PThismailerwantsa“Return-Path:”line. uUppercaseshouldbepreservedinusernamesforthismailer. hUppercaseshouldbepreservedinhostnamesforthismailer. AThisisanArpanet-compatiblemailer,andallappropriatemodesshouldbeset. UThismailerwantsUnix-style“From”lineswiththeuglyUUCP-style“remotefrom<host>” ontheend. eThismailerisexpensivetoconnectto,sotrytoavoidconnectingnormally;anynecessary connectionwilloccurduringaqueuerun. XThismailerwanttousethehiddendotalgorithmasspecifiedinRFC821;basically,anyline beginningwithadotwillhaveanextradotprepended(tobestrippedattheotherend). Thisinsuresthatlinesinthemessagecontainingadotwillnotterminatethemessageprematurely. LLimitthelinelengthsasspecifiedinRFC821. PUsethereturn-pathintheSMTP“MAILFROM:”commandratherthanjustthereturn address;althoughthisisrequiredinRFC821,manyhostsdonotprocessreturnpathsproperly. IThismailerwillbespeakingSMTPtoanothersendmail—assuchitcanusespecialprotocol features.Thisoptionisnotrequired(i.e.,ifthisoptionisomittedthetransmissionwillstill operatesuccessfully,althoughperhapsnotasefficientlyaspossible). SendmailInstallationandOperationGuide 28 SendmailInstallationandOperationGuide 29 CIfmailisreceivedfromamailerwiththisflagset,anyaddressesintheheaderthatdonot haveanatsign(“@”)afterbeingrewrittenbyrulesetthreewillhavethe“@domain”clause fromthesendertackedon.Thisallowsmailwithheadersoftheform: From:usera@hosta To:userb@hostb,userc toberewrittenas: From:usera@hosta To:userb@hostb,userc@hosta automatically. Version4.2 LastMod7/28/83 APPENDIXD OTHERCONFIGURATION Therearesomeconfigurationchangesthatcanbemadebyrecompilingsendmail.Theseare locatedinthreeplaces: md/config.m4Thesecontainoperating-systemdependentdescriptions.Theyareinterpolated intotheMakefilesinthesrcandauxdirectories.Thisincludesinformationabout whatversionofUNIXyouarerunning,whatlibrariesyouhavetoinclude,etc. src/conf.hConfigurationparametersthatmaybetweakedbytheinstallerareincludedin conf.h. src/conf.cSomespecialroutinesandafewvariablesmaybedefinedinconf.c.Forthemost parttheseareselectedfromthesettingsinconf.h. Parametersinmd/config.m4 Thefollowingcompilationflagsmaybedefinedinthem4CONFIGmacroinmd/config.m4 todefinetheenvironmentinwhichyouareoperating. V6Ifset,thiswillcompileaversion6system,with8-bituserid’s,singlecharacter ttyid’s,etc. VMUNIXIfset,youwillbeassumedtohaveaBerkeley4BSDor4.1BSD,includingthe vfork(2)systemcall,specialtypesdefinedin<sys/types.h>(e.g,uchar),etc. Ifnoneoftheseflagsareset,aversion7systemisassumed. Youwillalsohavetospecifywhatlibrariestolinkwithsendmailinthem4LIBSmacro. Mostnotably,youwillhavetoincludeifyouarerunninga4.1BSDsystem. Parametersinsrc/conf.h Parametersandcompilationoptionsaredefinedinconf.h.Mostoftheseneednotnormally betweaked;commonparametersareallinsendmail.cf.However,thesizesofcertainprimitive vectors,etc.,areincludedinthisfile.Thenumbersfollowingtheparametersaretheirdefault value. MAXLINE[256]Themaximumlinelengthofanyinputline.Ifmessagelinesexceedthis lengththeywillstillbeprocessedcorrectly;however,headerlines,configurationfilelines,aliaslines,etc.,mustfitwithinthislimit. MAXNAME[128]Themaximumlengthofanyname,suchasahostorausername. MAXFIELD[2500]Themaximumtotallengthofanyheaderfield,includingcontinuationlines. MAXPV[40]Themaximumnumberofparameterstoanymailer.Thislimitsthenumber ofrecipientsthatmaybepassedinonetransaction. MAXHOP[30]Whenamessagehasbeenprocessedmorethanthisnumberoftimes,sendmail rejectsthemessageontheassumptionthattherehasbeenanaliasingloop. Thiscanbedeterminedfromthe−hflagorbycountingthenumberoftrace fields(i.e,“Received:”lines)inthemessageheader. MAXATOM[100]Themaximumnumberofatoms(tokens)inasingleaddress.Forexample,the address“eric@Berkeley”isthreeatoms. SendmailInstallationandOperationGuide 30 SendmailInstallationandOperationGuide 31 MAXMAILERS[25] Themaximumnumberofmailersthatmaybedefinedintheconfigurationfile. MAXRWSETS[30]Themaximumnumberofrewritingsetsthatmaybedefined. MAXPRIORITIES[25] Themaximumnumberofvaluesforthe“Precedence:”fieldthatmaybe defined(usingthePlineinsendmail.cf). MAXTRUST[30]Themaximumnumberoftrustedusersthatmaybedefined(usingtheTline insendmail.cf). Anumberofothercompilationoptionsexist.Thesespecifywhetherornotspecificcodeshould becompiledin. DBMIfset,the“DBM”packageinUNIXisused(seeDBM(3X)in[UNIX80]).Ifnot set,amuchlessefficientalgorithmforprocessingaliasesisused. DEBUGIfset,debugginginformationiscompiledin.Toactuallygetthedebuggingoutput,the−dflagmustbeused. LOGIfset,thesyslogroutineinuseatsomesitesisused.Thismakesaninformational logrecordforeachmessageprocessed,andmakesahigherprioritylogrecordfor internalsystemerrors. QUEUEThisflagshouldbesettocompileinthequeueingcode.Ifthisisnotset,mailers mustacceptthemailimmediatelyoritwillbereturnedtothesender. SMTPIfset,thecodetohandleuserandserverSMTPwillbecompiledin.Thisisonly necessaryifyourmachinehassomemailerthatspeaksSMTP. DAEMONIfset,codetorunadaemoniscompiledin.Thiscodeisfor4.2BSDifthe NVMUNIXflagisspecified;otherwise,4.1aBSDcodeisused.Bewarehowever thattherearebugsinthe4.1acodethatmakeitimpossibleforsendmailto workcorrectlyunderheavyload. UGLYUUCPIfyouhaveaUUCPhostadjacenttoyouwhichisnotrunningareasonableversionofrmail,youwillhavetosetthisflagtoincludethe“remotefromsysname” infoonthefromline.Otherwise,UUCPgetsconfusedaboutwherethemail camefrom. NOTUNIXIfyouareusinganon-UNIXmailformat,youcansetthisflagtoturnoffspecial processingofUNIX-style“From”lines. Configurationinsrc/conf.c Notallheadersemanticsaredefinedintheconfigurationfile.Headerlinesthatshouldonly beincludedbycertainmailers(aswellasothermoreobscuresemantics)mustbespecifiedinthe HdrInfotableinconf.c.Thistablecontainstheheadername(whichshouldbeinalllowercase) andasetofheadercontrolflags(describedbelow),Theflagsare: HACHECKNormallywhenthecheckismadetoseeifaheaderlineiscompatiblewitha mailer,sendmailwillnotdeleteanexistingline.Ifthisflagisset,sendmailwill deleteevenexistingheaderlines.Thatis,ifthisbitissetandthemailerdoes nothaveflagbitssetthatintersectwiththerequiredmailerflagsintheheader definitioninsendmail.cf,theheaderlineisalwaysdeleted. HEOHIfthisheaderfieldisset,treatitlikeablankline,i.e.,itwillsignaltheendofthe headerandthebeginningofthemessagetext. HFORCEAddthisheaderentryevenifoneexistedinthemessagebefore.Ifaheaderentry doesnothavethisbitset,sendmailwillnotaddanotherheaderlineifaheader lineofthisnamealreadyexisted.Thiswouldnormallybeusedtostampthe Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 32 messagebyeveryonewhohandledit. HTRACEIfset,thisisatimestamp(trace)field.Ifthenumberoftracefieldsinamessage exceedsapresetamountthemessageisreturnedontheassumptionthatithasan aliasingloop. HRCPTIfset,thisfieldcontainsrecipientaddresses.Thisisusedbythe−tflagtodeterminewhotosendtowhenitiscollectingrecipientsfromthemessage. HFROMThisflagindicatesthatthisfieldspecifiesasender.Theorderofthesefieldsin theHdrInfotablespecifiessendmail’spreferenceforwhichfieldtoreturnerror messagesto. Let’slookatasampleHdrInfospecification: structhdrinfoHdrInfo[]= { /*originatorfields,mosttoleastsignificant*/ "resent-sender",HFROM, "resent-from",HFROM, "sender",HFROM, "from",HFROM, "full-name",HACHECK, /*destinationfields*/ "to",HRCPT, "resent-to",HRCPT, "cc",HRCPT, /*messageidentificationandcontrol*/ "message",HEOH, "text",HEOH, /*tracefields*/ "received",HTRACE|HFORCE, NULL,0, }; Thisstructureindicatesthatthe“To:”,“Resent-To:”,and“Cc:”fieldsallspecifyrecipient addresses.Any“Full-Name:”fieldwillbedeletedunlesstherequiredmailerflag(indicatedinthe configurationfile)isspecified.The“Message:”and“Text:”fieldswillterminatetheheader;these arespecifiedinnewprotocols[NBS80]orusedbyrandomdissentersaroundthenetworkworld. The“Received:”fieldwillalwaysbeadded,andcanbeusedtotracemessages. Thereareanumberofimportantpointshere.First,headerfieldsarenotaddedautomaticallyjustbecausetheyareintheHdrInfostructure;theymustbespecifiedintheconfiguration fileinordertobeaddedtothemessage.Anyheaderfieldsmentionedintheconfigurationfilebut notmentionedintheHdrInfostructurehavedefaultprocessingperformed;thatis,theyareadded unlesstheywereinthemessagealready.Second,theHdrInfostructureonlyspecifiesclichedprocessing;certainheadersareprocessedspeciallybyadhoccoderegardlessofthestatusspecifiedin HdrInfo.Forexample,the“Sender:”and“From:”fieldsarealwaysscannedonARPANETmail todeterminethesender;thisisusedtoperformthe“returntosender”function.The“From:” and“Full-Name:”fieldsareusedtodeterminethefullnameofthesenderifpossible;thisisstored inthemacro$xandusedinanumberofways. Thefileconf.calsocontainsthespecificationofARPANETreplycodes.Therearefourclassificationsthesefallinto: Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide 33 charArpaInfo[]="050";/*arbitraryinfo*/ charArpaTSyserr[]="455";/*some(transient)systemerror*/ charArpaPSyserr[]="554";/*some(transient)systemerror*/ charArpaUsrerr[]="554";/*some(fatal)usererror*/ TheclassArpaInfoisforanyinformationthatisnotrequiredbytheprotocol,suchasforwarding information.ArpaTSyserrandArpaPSyserrisprintedbythesyserrroutine.TSyserrisprinted outfortransienterrors,whereasPSyserrisprintedforpermanenterrors;thedistinctionismade basedonthevalueoferrno.Finally,ArpaUsrerristheresultofausererrorandisgeneratedby theusrerrroutine;thesearegeneratedwhentheuserhasspecifiedsomethingwrong,andhence theerrorispermanent,i.e.,itwillnotworksimplybyresubmittingtherequest. Ifitisnecessarytorestrictmailthrougharelay,thecheckcompatroutinecanbemodified. Thisroutineiscalledforeveryrecipientaddress.ItcanreturnTRUEtoindicatethatthe addressisacceptableandmailprocessingwillcontinue,oritcanreturnFALSEtorejectthe recipient.Ifitreturnsfalse,itisuptocheckcompattoprintanerrormessage(usingusrerr)sayingwhythemessageisrejected.Forexample,checkcompatcouldread: bool checkcompat(to) registerADDRESS*to; { if(MsgSize>50000&&to->qmailer!=LocalMailer) { usrerr("Messagetoolargefornon-localdelivery"); NoReturn=TRUE; return(FALSE); } return(TRUE); } Thiswouldrejectmessagesgreaterthan50000bytesunlesstheywerelocal.TheNoReturnflag canbesenttosupressthereturnoftheactualbodyofthemessageintheerrorreturn.The actualuseofthisroutineishighlydependentontheimplementation,anduseshouldbelimited. Version4.2 LastMod7/28/83 APPENDIXE SUMMARYOFSUPPORTFILES Thisisasummaryofthesupportfilesthatsendmailcreatesorgenerates. /usr/lib/sendmail Thebinaryofsendmail. /usr/bin/newaliases Alinkto/usr/lib/sendmail;causesthealiasdatabasetoberebuilt.Runningthis programiscompletelyequivalenttogivingsendmailthe−biflag. /usr/bin/mailqPrintsalistingofthemailqueue.Thisprogramisequivalenttousingthe−bp flagtosendmail. /usr/lib/sendmail.cf Theconfigurationfile,intextualform. /usr/lib/sendmail.fc Theconfigurationfilerepresentedasamemoryimage. /usr/lib/sendmail.hf TheSMTPhelpfile. /usr/lib/sendmail.st Astatisticsfile;neednotbepresent. /usr/lib/aliasesThetextualversionofthealiasfile. /usr/lib/aliases.{pag,dir} Thealiasfileindbm(3)format. /etc/syslogTheprogramtodologging. /etc/syslog.confTheconfigurationfileforsyslog. /etc/syslog.pidContainstheprocessidofthecurrentlyrunningsyslog. /usr/spool/mqueue Thedirectoryinwhichthemailqueueandtemporaryfilesreside. /usr/spool/mqueue/qf* Control(queue)filesformessages. /usr/spool/mqueue/df* Datafiles. /usr/spool/mqueue/lf* Lockfiles /usr/spool/mqueue/tf* Temporaryversionsoftheqffiles,usedduringqueuefilerebuild. /usr/spool/mqueue/nf* Afileusedwhencreatingauniqueid. /usr/spool/mqueue/xf* Atranscriptofthecurrentsession. SendmailInstallationandOperationGuide xxxiv SENDMAIL INSTALLATIONANDOPERATIONGUIDE EricAllman Britton-Lee,Inc. Version4.2 SendmailInstallationandOperationGuide i TABLEOFCONTENTS 1.BASICINSTALLATION.................................................................................................1 1.1.Off-The-ShelfConfigurations...................................................................................2 1.2.InstallationUsingtheMakefile...............................................................................2 1.3.InstallationbyHand...............................................................................................2 1.3.1.lib/libsys.a......................................................................................................2 1.3.2./usr/lib/sendmail............................................................................................3 1.3.3./usr/lib/sendmail.cf........................................................................................3 1.3.4./usr/ucb/newaliases........................................................................................3 1.3.5./usr/lib/sendmail.cf........................................................................................3 1.3.6./usr/spool/mqueue.........................................................................................3 1.3.7./usr/lib/aliases*..............................................................................................3 1.3.8./usr/lib/sendmail.fc........................................................................................4 1.3.9./etc/rc.............................................................................................................4 1.3.10./usr/lib/sendmail.hf......................................................................................4 1.3.11./usr/lib/sendmail.st......................................................................................4 1.3.12./etc/syslog....................................................................................................4 1.3.13./usr/ucb/newaliases......................................................................................5 1.3.14./usr/ucb/mailq.............................................................................................5 2.NORMALOPERATIONS..............................................................................................5 2.1.QuickConfigurationStartup...................................................................................5 2.2.TheSystemLog......................................................................................................5 2.2.1.Format............................................................................................................5 2.2.2.Levels..............................................................................................................5 2.3.TheMailQueue......................................................................................................5 2.3.1.Printingthequeue..........................................................................................5 2.3.2.Formatofqueuefiles.......................................................................................6 2.3.3.Forcingthequeue............................................................................................7 2.4.TheAliasDatabase.................................................................................................8 2.4.1.Rebuildingthealiasdatabase.........................................................................8 2.4.2.Potentialproblems..........................................................................................8 2.4.3.Listowners......................................................................................................9 2.5.Per-UserForwarding(.forwardFiles)......................................................................9 2.6.SpecialHeaderLines...............................................................................................9 2.6.1.Return-Receipt-To:.........................................................................................9 2.6.2.Errors-To:........................................................................................................9 2.6.3.Apparently-To:................................................................................................9 3.ARGUMENTS................................................................................................................10 3.1.QueueInterval.........................................................................................................10 3.2.DaemonMode.........................................................................................................10 3.3.ForcingtheQueue...................................................................................................10 3.4.Debugging...............................................................................................................10 Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide ii 3.5.TryingaDifferentConfigurationFile......................................................................10 3.6.ChangingtheValuesofOptions..............................................................................11 4.TUNING.........................................................................................................................11 4.1.Timeouts.................................................................................................................11 4.1.1.Queueinterval.................................................................................................11 4.1.2.Readtimeouts.................................................................................................11 4.1.3.Messagetimeouts............................................................................................11 4.2.DeliveryMode.........................................................................................................11 4.3.LogLevel.................................................................................................................12 4.4.FileModes...............................................................................................................12 4.4.1.Tosuidornottosuid?..................................................................................12 4.4.2.Temporaryfilemodes......................................................................................12 4.4.3.Shouldmyaliasdatabasebewritable?..........................................................12 5.THEWHOLESCOOPONTHECONFIGURATIONFILE.........................................13 5.1.TheSyntax..............................................................................................................13 5.1.1.RandS—rewritingrules..............................................................................13 5.1.2.D—definemacro...........................................................................................14 5.1.3.CandF—defineclasses................................................................................14 5.1.4.M—definemailer..........................................................................................14 5.1.5.H—defineheader..........................................................................................14 5.1.6.O—setoption...............................................................................................15 5.1.7.T—definetrustedusers................................................................................15 5.1.8.P—precedencedefinitions.............................................................................15 5.2.TheSemantics.........................................................................................................15 5.2.1.Specialmacros,conditionals...........................................................................15 5.2.2.Specialclasses.................................................................................................17 5.2.3.Thelefthandside...........................................................................................17 5.2.4.Therighthandside.........................................................................................18 5.2.5.Semanticsofrewritingrulesets......................................................................18 5.2.6.Mailerflagsetc..............................................................................................19 5.2.7.The“error”mailer..........................................................................................19 5.3.BuildingaConfigurationFileFromScratch...........................................................19 5.3.1.Whatyouaretryingtodo..............................................................................19 5.3.2.Philosophy......................................................................................................20 5.3.2.1.Largesite,manyhosts—minimuminformation....................................20 5.3.2.2.Smallsite—completeinformation.........................................................21 5.3.2.3.Singlehost..............................................................................................21 5.3.3.Relevantissues................................................................................................21 5.3.4.Howtoproceed...............................................................................................21 5.3.5.Testingtherewritingrules—the−btflag.....................................................22 5.3.6.Buildingmailerdescriptions............................................................................22 AppendixA.COMMANDLINEFLAGS............................................................................25 AppendixB.CONFIGURATIONOPTIONS.....................................................................26 AppendixC.MAILERFLAGS...........................................................................................28 Version4.2 LastMod7/28/83 SendmailInstallationandOperationGuide iii AppendixD.OTHERCONFIGURATION.........................................................................30 AppendixE.SUMMARYOFSUPPORTFILES................................................................34 Version4.2 LastMod7/28/83