idc@cs.hw.ac.uk (Ian Crorie) (01/24/89)
#!/bin/sh # to extract, remove the header and type "sh filename" if `test ! -d ./Docs` then mkdir ./Docs echo "mkdir ./Docs" fi if `test ! -s ./Docs/Makefile` then echo "Writing ./Docs/Makefile" cat > ./Docs/Makefile << '\Rogue\Monster\' # Documentation production MS=Overview.ms Guide.ms Tutorial.ms TROFF=Overview.troff Guide.troff Tutorial.troff NROFF=Overview.nroff Guide.nroff Tutorial.nroff .SUFFIXES: .ms .troff .nroff .ms.troff: troff -ms -t $*.ms > $*.troff .ms.nroff: nroff -ms -t $*.ms > $*.nroff $(TROFF) $(NROFF): $(MS) nroff: $(NROFF) troff: $(TROFF) \Rogue\Monster\ else echo "Will not over-write ./Docs/Makefile" fi chmod 444 ./Docs/Makefile if [ `wc -c < ./Docs/Makefile` -ne 339 ] then echo 'Got' `wc -c < ./Docs/Makefile` ', Expected ' 339 fi if `test ! -s ./Docs/Guide.ms` then echo "Writing ./Docs/Guide.ms" cat > ./Docs/Guide.ms << '\Rogue\Monster\' .TL Sendmail Configuration Package UK-2.1 .sp User Guide .AU Jim Crammond .AI Dept of Computing, Imperial College, London, England .AU Jem Taylor .AI Dept of Computing Science, University of Glasgow, Glasgow, Scotland .ND 27 November 1988 .LP .NH The Configuration Description File .NH 2 Purpose .LP The configuration description file names all the options and data required for producing a particular sendmail configuration file. It is invoked by the command .IP % Config <configfile> .LP We recommend that all configuration description files be named .I config. <name> where <name> is the same as the value of the config=<name> directive in the configuration description. .NH 2 Mandatory directives .LP The following directives are obligatory in the file and must come before any domain or channel declarations: .IP config=<name> This specifies the .I "configuration name" which is usually the hostname of the target system, or the name of a class of hosts such as "slave". It simply determines the names of certain files created when making the configuration. .IP domain=<domainname> This should be the official domain name as registered with some administrative body such as the NRS or NIC. In the absence of any such official name, a pseudo-domain-name such as 'uucpname'.uucp should be used; however this should be done only as a strictly interim measure until a name is officially registered. .NH 2 Optional directives .LP The following directives are optional, but must come before any domain or channel declarations: .IP configdir=<subdirectory> This specifies the subdirectory in which to create the files that make up the sendmail configuration file. By default, this is set to the configuration name. .IP tabledir=<subdirectory> This specifies the subdirectory which contains the domain and channel tables. This allows tables for several configurations to be stored in the same directory, if desired. By default, this is set to the configuration name, .IP postmaster=<mailbox> This is the local mailbox from which errors are generated. Sensible values include "POSTMASTER" (the default) and "MAILER-DAEMON". .IP options=<option1>,<option2>,... This directive may be used to select optional processing. Options include: .RS .IP multihost The configuration is for a "multihost" site - i.e. more than one host will show itself to the outside world with the domain name <domainname>. In addition, this host has a host specific domain name of the form `hostname`.<domainname> .IP nrsformat This enables addresses with domains in the NRS domain order to be recognised and generated. This option MUST be specified if the janet channel is used. .IP nameserver For sendmails which contain nameserver code, this makes a request to the nameserver to obtain the official domain name of a host/domain. It should not be specified unless all sendmails which will use the configuration have the nameserver code compiled in. .RE .IP install=<flags> Set the flags to be used in the call to Install.sh from the Makefile created by Config (see section 4). .NH 2 Domain declarations .LP Domain declarations may be repeated as often as necessary and take the following form .IP domain .I type file=" .I filename " .LP type may be 'std', 'ida' or 'top'. A domain declaration of the standard type 'std' indicates that .I filename is a domain table to be compiled directly into sendmail rules and classes. If the type is 'ida' then instead .I filename will be compiled into a dbm database file which is called from the sendmail configuration file using a dbm lookup facility. The type 'top' specifies that .I filename is a domain table listing top level domains. .NH 2 Channel declarations .LP Channel declarations may also be repeated as often as is needed for each channel. The existance of a channel is declared by one or more declarations of the appropriate type. The form of a channel declaration is .IP channel .I type file=" .I filename " [, .I channeloption ]* .LP where .I type is a channel type, .I filename is a channel table, and .I channeloption is an option specific to this channel. .KS .NH 3 Channel types .LP Valid channel types include: .IP local ether tcp uucp janet news decnet csnet xerox top .KE .LP Details about the channel tables are given in section 3. .NH 3 Channel options .LP Channel specific options include the following possibilities: .IP "local channel:" .RS .IP showldomain Local addresses are presented locally with the local domain name appended. By default, the local domain name is stripped from addresses in headers leaving just the username. .IP shownrs All domain addresses are presented locally in NRS domain ordering (i.e. big-endian). By default, all addresses are presented in RFC822 order. The "nrsformat" option is required with this option. .IP showuucp Addresses containing two or more hostnames are presented locally in uucp bang style. .RE .IP "uucp channel:" .RS .IP sysname=<name> Set the uucp system name this machine is known by to <name>. .IP "muucp " Use the muucp program to interface with uucp (supplied in the Support directory) instead of calling uux directly. .RE .IP "janet channel:" .RS .IP hhsend Set the mailer specification to use hhsend (York X.25) instead of ni_send (Unix-Niftp). .RE .IP "news channel:" .RS .IP relayed This indicates that .I all news is relayed to another host. .RE .IP "uucp, janet, decnet, csnet and xerox channels:" .RS .IP auth Set the mailer specification to invoke the authorise program for mail authorisation by host. The authorise program in the Support directory needs to be installed to use this option. .RE .IP "all channels:" .RS .IP ida Rather than generate sendmail rules directly from the channel table, create an IDA database file and arrange for sendmail to lookup this file instead (see section 3). The configuration should not be exported to another host unless that host also has access to the same file by the same name. This option does not apply to local, uucp or news channels. .IP "ldomain=<domainname>" Messages sent on this channel will have the local domain name stamped as <domainname> rather than the official domain name. This has no effect on the local channel. .RE .NH Domain Tables .NH 2 General .LP It is recommended that you have some idea of what domains are before you start. RFC819 (supplied with the sendmail documentation) is a good starting point for this. .LP The domain tables provide the information that allows sendmail to expand host/site names or abbreviated domain names to fully qualified domain names. .LP The tables consist of rules (1 per line) which consist of two strings separated by white space. Essentially, any address whose domain part ends in the string given on the LHS of a rule will be expanded to the string given on the RHS. .LP For example, if the following entry was in the domain tables .DS I hw hw.ac.uk .DE .LP then a user can give the address .I jim@hw and sendmail will expand this to the fully qualified name .I jim@hw.ac.uk. Also, this will expand .I jim@cs.hw to .I jim@cs.hw.ac.uk . .SH Notes .IP (1) The above line will NOT cause .I jim@hw.ac to be expanded to .I jim@hw.ac.uk . To achieve this, the line .DS I ac ac.uk .DE .IP must also be included in the domain tables. (This is a change from previous versions of UK-sendmail). .IP (2) The names in the domain tables must be given in RFC822 (little-endian) form with the most general part rightmost. e.g. hw.ac.uk, regardless of whether the "nrsformat" option has been specified. .LP Probably the minimum information you need to specify in the domain tables is a mapping from your host name to your domain name, e.g. .DS I sun6 sun6.cs.hw.ac.uk .DE .LP This would mean users would always have to give fully qualified addresses to send mail elsewhere. .LP In the NRS registration scheme, domain names are structured with "uk" at the top level, with two main subdomains distinguishing academic from commercial sites, and institution or company names at the third level. .LP A sensible choice for domain tables in such a scheme would be to include siblings of the subdomains that make up your domain name starting from the institution name (third level), e.g. for the host .I sun6.cs.hw.ac.uk this means all subdomains of "ac.uk", "hw.ac.uk" and "cs.hw.ac.uk". .LP You can add further information, for example, you may wish to specify all the subdomains of "co.uk" as well as "ac.uk". Beware of naming conflicts, however, as there are some cases in the NRS that could cause problems. For example, if the entry .DS I kl kl.york.ac.uk .DE .LP was in your tables, then mail to Keele Computer Science addressed as .I jim@cs.kl will be expanded to .I jim@cs.kl.york.ac.uk instead of .I jim@cs.kl.ac.uk (the full address .I jim@cs.kl.ac.uk will work correctly, of course). The .I Domcheck program can spot cases where you have placed entries in your tables with the same LHS but different RHSs. .KS .LP Domain name aliases can also be included in these files; so for example, you could convert NRS abbreviated form names to standard form with the following entries: .DS I cs.gla.ac.uk cs.glasgow.ac.uk clust.hw.ac.uk cluster.heriot-watt.ac.uk doc.ic.ac.uk doc.imperial.ac.uk .DE .KE .LP so that .I jim@clust.hw.ac.uk will be aliased to .I jim@cluster.heriot-watt.ac.uk . .LP It should be noted that many domain aliases placed in a standard type domain table can result in generating a large sendmail configuration file, so if you map all (700+) abbreviated form NRS names to their standard form then your sendmail may run rather slowly! .LP This is an example where IDA sendmail is useful; by changing the domain table type to 'ida', a dbm(3) file is created from which IDA sendmail will lookup the domain directly. The effect is exactly the same as before only probably much faster, especially as sendmail does not have to load such a large configuration file when it is invoked. .LP If you have Yellow Pages compiled into your /usr/lib/sendmail program, and your yellow pages database only contains entries for hosts within one domain then you can use a rule such as: .DS I $%y $2.cs.hw.ac.uk .DE .LP to map all of these hostnames to domain names. .LP Finally, a "#" in the tables starts a line of comment. All text after the "#" up to the next newline is ignored. .NH 2 Top Level Domains .LP Top-domain tables are treated specially. These files contain a list of top level domain names. .LP The format of these tables is compatible with the top channel tables: a top level domain name on the LHS and a relaying domain on the RHS, e.g. .DS I uk ukc.ac.uk .DE .LP Thus you can link the top channel and top domain files, if you wish. Alternatively, if the top channel file contains a special directive such as "ALL" or "DEFAULT", then a single column list of top level domains can be used for the domain table. .NH 2 Shorthand Notation .LP Where a domain table entry is a domain specification rather than an alias, i.e. the LHS is a single token which appears as the first subdomain on the RHS, then the LHS can be omitted. For example, .DS I cs cs.glasgow.ac.uk .DE .LP can be entered as .DS I cs.glasgow.ac.uk .DE .LP but .DS I mcvax cwi.nl .DE .LP must be given as shown. This shorthand notation makes it possible to use the same file for both local network domain data and local ethernet channel data (see later). .NH 2 Examples .LP The directory Examples contains sample domain tables. These can be used as a starting point for creating your domain tables. .KS .NH Channel tables .NH 2 General .LP Having expanded addresses into fully qualified domain addresses, sendmail then selects the appropriate mailer and routing. The channel tables provide the information to associate a domain name with a mailer (or channel) and transport address (or route). .LP The channel tables contain rules (1 per line) containing two strings separated by white space. In general, the string on the LHS is a fully qualified domain name and the string on the RHS is the route or "host to send to", e.g. .IP cs.hw.ac.uk sun6 .LP specifies that addresses of the form .I user@cs.hw.ac.uk should be send to the host .I sun6 . .KE .LP If sendmail fails to find a match for a domain, e.g. .I "sun4.cs.hw.ac.uk" in the main channel tables, then it retries with successively higher level domains, e.g. .I "cs.hw.ac.uk", .I "hw.ac.uk" and .I "ac.uk" . If these fail then the top level domain relaying rule for .I "uk" is applied and matching begins again with the domain given as the relay for .I "uk". .LP The actual format of the channel tables depends on the mailer. The minimum information you need to specify depends on what mailers you have, but is essentially: .IP (a) the domain name(s) the local host is known by, .IP (b) the names of directly connected hosts, .IP (c) the list of top level domain relaying sites (see below). .LP The maximum information you can specify is limited by practical considerations such as the number of rules sendmail can cope with before running very slowly. As a guide, if more than 100 rules are generated in the channel section of the configuration, you may wish to cut down the number of entries in the channel tables. .LP Careful use of top level domain relays and/or wildcards will often help. For example, if .I ukc.ac.uk is specified as the uucp relay, then there is no need to specify any routes for uucp sites which has "ukc!" in the path (ukc.ac.uk has an extensive nameserver to do further routing). .LP Those with IDA sendmail can compile some large channel tables into ida databases. This is particularly useful for the janet channel. Note that ida channel tables may not contain wildcards. .NH 2 Channel Table Formats .LP The actual format of the channel tables depends on the channel type (i.e. mailer) that is specified in the configuration description file. These are listed below. Note, however, that all of the channel tables use the same convention for comments as used for the domain tables. .NH 3 local channel .LP This contains a one-per-line list of (fully qualified) domain names which are to be treated as local mail. In a 'multihost' this must include the site domain name and the host specific domain name, e.g. .DS I cs.hw.ac.uk sun6.cs.hw.ac.uk .DE .LP In order to allow hosts to share the same sendmail configuration file, the keyword "LHOST" must be used in place of the actual hostname, i.e. .DS I LHOST.cs.hw.ac.uk .DE .LP LHOST is substituted by the hostname (as returned by .I hostname(1) ) when sendmail starts up. Obselete names still in use, such as .IP hwcs.uucp .LP should also be included here. .TA .NH 3 general case channel .LP The ether, tcp, xerox, decnet and csnet channels all use the same "standard" channel format, as described above; a domain name on the LHS in little-endian order, and a hostname to send/relay to on the RHS. If the host name on the RHS is the same as the first subdomain, then the RHS can be omitted. Thus .DS I sun3.doc.ic.ac.uk .DE .LP is equivalent to .DS I sun3.doc.ic.ac.uk sun3 .DE .LP This shorthand notation makes it possible to use the same file both as an ethernet channel table and local domain table, for example. .KS .LP In addition, the LHS can contain .I wildcards , specified by "%s", meaning "one or more tokens". So, .DS I %s.ncr.com sun4 .DE .LP sends anything ending .I .ncr.com to the uucp relay host, .I sun4 . The RHS can also contain wildcards which correspond to the tokens matched by the wildcard on the LHS. For example, an ether channel with .DS I %s.ee.ic.ac.uk ee.%s .DE .LP would send mail for .I jim@vax2.ee.ic.ac.uk to the host .I ee.vax2 (as given in /etc/hosts). .KE .KS .LP If sendmail supports Yellow Pages, and the Yellow Pages .I hosts database only contains entries for hosts in one domain, then the special token "$%y" may be used in the following way to specify that mail to all hosts in the yellow pages database be sent directly: .DS I $%y.cs.glasgow.ac.uk $2 .DE .KE .SH Notes .IP (1) The Yellow Pages special token may not be used in entries containing wildcards. .IP (2) Wildcard entries are processed after non-wildcard entries. So, given the following entries in a tcp table: .DS I %s.cs.ucl.ac.uk %s.cs.ucl.ac.uk cs.ucl.ac.uk cs.ucl.ac.uk .DE An address such as .I jim@nss.cs.ucl.ac.uk will be routed to .I cs.ucl.ac.uk by the second rule, and not sent direct. However, wildcard rules are processed in the order in which they are presented, so .DS I %s.hw.ac.uk hw-relay %s.ac.uk ac-relay .DE should be used, rather than the reverse order. .IP (3) Internet based sites usually pass addresses to the tcp channel by default; this can be achieved with entries in the tcp channel table like: .DS # all arpa addresses to tcp %s.edu %s.edu %s.com %s.com .DE for each of the arpa-based top level domains. .NH 3 janet channel .LP The LHS domain name is in .I big-endian form in this table. The RHS is a "hostname" to send to which corresponds to the entry given in the ftp host tables. For example, .DS I # hw.cs is directly on janet uk.ac.hw.cs uk.ac.hw.cs # hw.ee uses hw.cs as an application relay uk.ac.hw.ee uk.ac.hw.cs .DE .LP The LHS and RHS may contain wildcards in the same way as in the general case channel, thus: .DS I uk.co.stc.%s uk.ac.ukc .DE .SH Notes .IP (1) If the RHS is the same as the LHS, it can be omitted; if it differs then correct JNT Application Relaying is done. .IP (2) In previous versions of UK-sendmail the janet channel would automatically assume that all "uk.ac.<name>" domains are to be routed to "uk.ac.<name>" and all "uk.co.<name>" domains are to be routed to "uk.co.<name>". It is now necessary to use the lines .DS I uk.ac.%s uk.co.%s .DE to achieve this effect if desired. .IP (3) If you do not map standard form NRS names to abbreviated from (or vice versa) in the domain tables then any entries in the janet channel table should include both forms of name on the LHS. .IP (4) In previous versions of UK-Sendmail, incoming mail from the Greybook mail listener was passed to sendmail with a command line like .DS C /usr/lib/sendmail -oiY -oMsuk.ac.sender.name ...etc... .DE This version requires that the sender domain be set in macro .I S rather than .I s for correct Via: headers to be generated. Use .DS C /usr/lib/sendmail -oiY -oMSuk.ac.sender.name ...etc... .DE to achieve this. .LP .KS .NH 3 uucp channel .LP This has a slightly different RHS syntax which the same as that produced by .I pathalias(1 ), e.g. .IP vax1.ee.hw.ac.uk sun2!vax1!%s .LP where %s is the user part of the address (converted to uucp form). .KE .LP In the frequent case where the RHS consists of the first token of the LHS suffixed with "!%s" then the RHS may be omitted. Thus the two following entries are equivalent: .DS I ukc.ac.uk ukc!%s ukc.ac.uk .DE .LP This again allows a file written completely in this shorthand notation to be used both as a domain and a channel file. .NH 3 top channel .LP The top channel has a top level domain name on the LHS and a domain name on the RHS, e.g. .DS I uk ukc.ac.uk .DE .LP which states that any address in the .I "uk" domain, which did not match a domain name in one of the mailer channel tables, is sent to .I ukc.ac.uk . .LP If you feel tempted to put .DS I %s.com nss.cs.ucl.ac.uk .DE .LP into the tcp channel for example, you should instead put .DS I com nss.cs.ucl.ac.uk .DE .LP into the top channel. The latter will use the channel tables to find a route for .I "nss.cs.ucl.ac.uk" , whereas the latter assumes it is directly connected (via tcp). If all but a few top domains are relayed by the same relay, you can use the .I "DEFAULT" keyword, e.g. .DS I DEFAULT gateway.cs.hw.ac.uk .DE .LP to specify that any top level domains listed in the top domain file, for which no relay is explictly given, should be sent to the default relay. On small or infrequently maintained machines, or when there is only one possible relay, the keyword .I "ALL" can be used, e.g. .DS I ALL gateway.cs.hw.ac.uk .DE .LP which causes all addresses that are not matched in any other channel to be sent to the relay even if they do not contain a recognised top level domain. This allows "slave" style configurations to be built. .SH Note .IP Make sure that the domains on the RHS of the relaying rules eventually match some domain on the LHS of a rule in one of the mailer channel tables. .LP .KS .NH 3 news channel .LP This has a newsgroup hierarchy name on the LHS and an optional relay name on the RHS, for example: .DS I comp.binaries.%s sun3 comp.%s bionet.%s biovax news.%s soc.%s .DE .KE .LP which sends mail for comp.binaries.<anything> to comp.binaries.<..>@sun3 and similarly mails messages to bionet.<anything> to bionet.<..>@biovax but delivers comp.<anything-else>, news.<anything> and soc.<anything> to the news system on the local host. The mail-news program from the Support directory should be installed on all hosts where news is not relayed elsewhere. .SH Note .IP The news channel acts on LOCAL USER NAMES not DOMAIN NAMES .NH 3 bitnet channel .LP The bitnet channel has been discontinued. If you need it, you are invited to re-implement it and send the authors the patches. .NH 2 Examples .LP The directory Examples contains sample channel tables. These can be used as a starting point for creating your channel tables. .NH Site specific modifications to base.m4 .LP If a file named .I localise.sh exists in the configuration directory, it will be executed by .I Config to, for example, change details of .I base.m4 such as the load average above which no work is done. The example in the Examples directory uses .I ed(1) to achieve this. .NH Installing the configuration file .LP "make test" will invoke sendmail in test mode to enable you to verify that the configuration can resolve addresses correctly. You should read the sendmail documentation if you are unfamiliar with this facility. .LP There is a shell script called .I Install.sh that will install a sendmail configuration file. Install.sh is called with the following arguments: .DS C Install.sh [-f] [-n] [-s] <host> [ <configfile> ] .DE .LP By default, this will copy the <configfile> to /usr/lib/sendmail.cf on <host>, create a freeze file and then restart the sendmail daemon. If the .I -f option is given a freeze file is .I not created. This is usually necessary for shared configurations, or when your sendmail uses Yellow Pages. The .I -n option does not copy the configuration file, it only restarts the daemon. This is used for all but the first of a group of hosts which share the same copy of /usr/lib/sendmail.cf via NFS. The .I -s option is used when the .I target system has a System V style .I ps(1) . .LP Where a configuration is made for a single host, "make install" will call Install.sh to install the configuration file for that host. Where it is shared, a shell script should be set up to call Install.sh for each of the hosts sharing the configuration. .SH Notes .IP (1) In versions of Sun software from SunOS 4.0, sendmail.cf lives in /etc so that /usr/lib can be shared more widely. If you are running the same sendmail.cf on many clients, put it in /usr/lib and make a symblink from /etc/sendmail.cf to /usr/lib/sendmail.cf on each client. If you have an NFS server which serves one configuration to its clients but uses another itself, put its own in /etc . You will need to write a short script using rcp and Install.sh -n to handle such a case. .NH Checking for name clashes .LP "make check" will run .I Domcheck on the domain tables and .I Chncheck on the channel tables used in the configuration. These programs will warn you of any name clashes or obvious syntax errors you have in your tables. .LP If you run "make install" from /usr/adm/weekly for example, we recommend that you instead run "make check install" so that none of the errors which Domcheck can detect will be put into your live system. \Rogue\Monster\ else echo "Will not over-write ./Docs/Guide.ms" fi chmod 444 ./Docs/Guide.ms if [ `wc -c < ./Docs/Guide.ms` -ne 23828 ] then echo 'Got' `wc -c < ./Docs/Guide.ms` ', Expected ' 23828 fi if `test ! -s ./Docs/Overview.ms` then echo "Writing ./Docs/Overview.ms" cat > ./Docs/Overview.ms << '\Rogue\Monster\' .TL Sendmail Configuration Package UK-2.1 .sp Overview .AU Jim Crammond .AI Dept. of Computing, Imperial College, London, England .AU Jem Taylor .AI Dept. of Computing Science, University of Glasgow, Glasgow, Scotland .ND 27 November 1988 .AB .SM UK-2.1 .NL Sendmail is a sendmail.cf generator for the .I /usr/lib/sendmail mail router used on BSD derived .SM UNIX .NL Systems. This version combines some ideas which were tested in .SM UK-1.5 .NL with several new features, including support for .SM IDA .NL databases and support for Internet hosts. The base is the hugely successful .SM UK-1.4 .NL package. This release brings the two development lines together and will be .I the definitive sendmail.cf compiler. .AE .LP .NH Overview .LP This package provides you with tools to generate a fully domain based sendmail configuration file from domain and channel tables in a format similar to that used by .SM MMDF. .NL .LP The configuration is essentially comprised of three parts: the domain tables, the channel tables and the mailer specifications. The diagram below shows how all three pieces fit together. .DS C .KF | incoming addresses | [domain tables] | fully qualified domain addresses |\bV +--------------------+ [channel tables] [mailer specs] | | mailer,host,transport addresses header addresses .DE .KE .LP The domain tables convert addresses given to sendmail into fully qualified domain addresses; these are then passed to the channel tables which select the <network, host, transport address> triple required for message delivery. .LP The domain addresses are then passed to the mailer specifications where they are converted to a form suitable for the mail headers for that particular network. .LP Anyone who has read the Sendmail Implementation Guide should recognise the similarity between this and the rulesets diagram. Basically, the domain tables correspond to ruleset 3, the channel tables to ruleset 0 and the mailer specifications to the mailer specific rulesets. .LP This manual will hopefully explain how to build these pieces and thus generate a configuration file. .LP The package also contains a number of support programs including "better" uucp/sendmail interface programs and a mail authorisation program. .NH Addresses .LP A key feature of UK-sendmail is that it does NOT perform routing based on address syntax. All addresses are converted into a single internal form and then routing is performed on the domain information. Addresses are then converted into a form suitable for the appropriate output channel (mailer). Addresses are accepted in any of the standard forms: .RS 5 .IP RFC822 10 @domain1,@domain2:user@domain3 .IP Percent user%domain3%domain2@domain1 .IP UUCP domain1!domain2!domain3!user .IP DECNET domain1::domain2::domain3::user .RE .LP If the "nrsformat" option is defined, then the GreyBook big-endian domain name ordering is also understood (e.g. uk.ac.hw.cs as well as cs.hw.ac.uk). .LP Mixed addresses are handled by using the precedence order '@' > '%' > '!' = '::' .IP e.g. domc!user%domb@doma => user%domc%domb@doma <=> doma!domb!domc!user .NH Mailers .LP The following mailer channels are supported\**: .RS 5 .IP local 10 the standard unix local mailer .IP ether mail over the ethernet using .SM SMTP/TCP .NL .IP tcp mail over the Internet using .SM SMTP/TCP .NL .IP uucp uucp mail, using muucp or uux .IP janet janet mail, using hhcp or unix-niftp .IP decnet mail over .SM DECNET .NL , using mail11 .IP csnet csnet mail, using pmdf .IP xerox mail over the Xerox Ethernet .IP news network news, using mail-news to call inews .RE .FS Note that luucp and uucp from UK-1.4 have been merged and that bitnet has been removed .FE .NH Support programs .LP The support directory contains various programs that interact with sendmail. These include: .RS 5 .IP authorise 15 A program to restrict mail access on certain channels to certain users or hosts. .IP distribute for mailing to distribution lists via /usr/lib/aliases .IP muucp which provides an interface to UUCP that conforms to RFC976. .IP mail-news which provides an interface to the netnews news "inews" program. .RE .LP Each of these programs comes with a manual page provided in the "Manuals" directory. .NH Files .LP The configuration file is generated from a set of data files (or tables), using a configuration description to describe the configuration and the files used to construct it. There are two types of data files: domain and channel data. .LP In addition some .I m4(1) macro files are used. Of these, only .I base.m4 should ever need to be edited and then only if obscure sendmail options (e.g. Ox - priority at which to stop work) are to be altered. The important options are controlled by directives in the configuration description. Changes to .I base.m4 should be made using .I localise.sh as described in the User Guide. .NH 2 The Configuration Description File .LP The program .I Config takes a configuration description and generates an environment from which .I make(1) can be used to create sendmail configurations. .NH 2 Domain and Channel Tables .LP The configuration description includes a list of files that comprise the domain tables, used to compile the domain database, and files which make up the channel tables, listing the hosts and domains reachable over each channel. .NH 2 Names .LP The configuration description requires you to specify two names for making a configuration: .IP (1) a configuration name. This will usually be the same as the .I hostname(1) of the target system (e.g. sun6), or the name of a class of hosts (e.g. workstation) for a configuration which will be used on several target systems. .IP (2) a domain name in RFC822 order. The domain name should be your official name registered with some recognised administrative body such as the NRS; e.g. .I "cs.hw.ac.uk" . Failing that, it maybe a network based domain name, e.g. .I "hwcs.UUCP" . .LP The configuration description will allow you to specify different domain names on different mailer channels, if absolutely necessary. Note, however, that you should only have one official domain name and you should use that whereever possible. .NH Multihost configuration .LP If you are a site which has a collection of machines, you will probably want to "hide" the machines behind one site domain name. .LP This will mean that people will send mail to the site, and let the sendmail on whichever machine it was received on, route the mail to the appropriate machine for that user. .LP Conceptually, this is done by making each of the hosts a subdomain of the site domain and then making each host recognise both the site domain and the host specific domain name as "local". .LP For example, the site domain .I "cs.hw.ac.uk" may have the subdomains .I "vax1" .I "vax2" and .I "sun6" . On .I vax1 , the domains .I "cs.hw.ac.uk" and .I "vax1.cs.hw.ac.uk" are recognised as local, whilst on .I sun6 the domains .I "cs.hw.ac.uk" and .I "sun6.cs.hw.ac.uk" are recognised as local. The host specific names allow mail to be routed to specific hosts within the site. .LP To make a multihost configuration, you specify the multihost option in the configuration description file, and configure the local channel table appropriately (see the example local channel tables in the Examples directory). Also, you will need to setup user aliases to route users' mail to their desired hosts (see below). .NH Aliases .LP Central to the success of the multihost configuration is the use of sendmail's aliases facility to determine which host a user's mail should be delivered to. The recommended scheme is to have a common set of aliases on all hosts containing all users and the host addresses to which their mail should be delivered, e.g. .DS I jim: jim@vax1 fred: fred@vax2 .DE .LP All addresses considered "local" are subject to aliasing. So, if the aliases file on .I vax2 contains the above entries, mail to .I "jim@vax2" will be forwarded from .I vax2 to .I vax1 . Aliases can, however, be overridden by prepending a '~' (tilde) to the user part of the address, so .I "~jim@vax2" will be delivered on .I vax2 , because when it arrives on .I vax2 , it will not be aliased. It is vital that users who wish to redirect their mail using .forward files use a '~' if the target for their mail is part of the same multihost set. .NH Running shared configuration files .LP If you are running a multihost configuration, where several machines have an identical view of the network then you can run the same configuration files on those machines, and possibly share the .I /usr/lib/sendmail.cf file if using NFS. .LP This applies, for example, where you have a number of machines on a local area network all of which send external mail to the same "gateway" machine which has a link to some wide area network. .LP Note that it is also possible to share the .I /usr/lib/aliases database as long as all entries refer to mailboxes and not (host dependent) programs. .NH Installation .IP (1) Refering to the "User Guide" and "Tutorial based on Examples", write a configuration description file describing the setup of the target system. .IP (2) Run "Config" with the name of a configuration description file as the argument. .IP This creates a directory containing the m4 files required for a host configuration and creates a <host>.mc file for use by m4. It also creates Makefiles which will be used below to create the sendmail <host>.cf file itself. .IP (3) "cd" to this directory and "make edit". This will allow you to create any data files which do not already exist, and ensure that all the data looks reasonable. .IP (4) "make check" to check for syntactic correctness, especially if you are converting from an earlier version of UK-sendmail. .IP (5) Run "make" to produce the <host>.cf file. .IP (6) Use "make test" to test the semantic correctness of the configuration - if you haven't used this before then see the sendmail documentation for details. .IP (7) Check that the mailer specification files have the correct pathnames and options to the mailers, particularly the local mailer! .IP (8) Install any appropriate mailer interfaces that you need from the "Support" directory. .IP (9) As superuser, run "make install" to install the configuration. If you have a sendmail daemon running (typically: /usr/lib/sendmail -bd -q1h), then this will kill it and start a new one. .LP If the configuration is a shared one, then you should create a shell script to invoke ../Install.sh for each of the machines that the configuration is to be installed on and/or whose daemons need to be restarted. .KS .NH Bug fixes and problems .LP If you have problems or comments then you can mail them to the UK-sendmail mailing list at the following address: .DS JANET: uk-sendmail-workers@uk.ac.hw.cs ARPA: uk-sendmail-workers@cs.hw.ac.uk UUCP: ..!ukc!cs.hw.ac.uk!uk-sendmail-workers .DE .LP Note that messages on this mailing list are also posted to the Usenet newsgroup .I comp.mail.sendmail . .KE \Rogue\Monster\ else echo "Will not over-write ./Docs/Overview.ms" fi chmod 444 ./Docs/Overview.ms if [ `wc -c < ./Docs/Overview.ms` -ne 11057 ] then echo 'Got' `wc -c < ./Docs/Overview.ms` ', Expected ' 11057 fi if `test ! -s ./Docs/Tutorial.ms` then echo "Writing ./Docs/Tutorial.ms" cat > ./Docs/Tutorial.ms << '\Rogue\Monster\' .TL Sendmail Configuration Package UK-2.1 .sp A Tutorial based on the Examples .AU Jim Crammond .AI Dept of Computing, Imperial College, University of London, England .AU Jem Taylor .AI Dept of Computing Science, University of Glasgow, Glasgow, Scotland .ND 27 November 1988 .LP .NH Setup at the example site cs.glasgow.ac.uk .LP The site .I cs.glasgow.ac.uk has several dozen machines using the generic configuration 'slave' and two machines 'gateway' and 'uurelay' which have configurations of their own. We also generate configurations for two other glasgow sites which are each set up in a similar way. This database of domain and channel tables is therefore used to make a total of five different configurations. Tables basically fall into three categories: .DS L Tables used in all configurations (with prefix "glasgow.") Tables used in cs dept. configurations (with prefix "cs-dept.") Tables used in only one configuration (e.g. with prefix "uurelay.") .DE .LP These tables can be found in the Examples directory. The following notes will cover the three configurations used for .I cs.glasgow.ac.uk. The arrangement of data files also takes account of other configurations generated from them for other sites. .LP All users have entries in .I /usr/lib/aliases which is maintained centrally on the host that has the master copy of .I /etc/passwd and we ensure that all our users have accounts on that machine, though many have .I /bin/noaccount as their login shell. .KS .NH Site topology .DS I - | |-- gateway (janet relay, sendmail database master & alias database master) | +---> janet WAN including relays to overseas domains | |-- e t-- h e-- (dozens of) 'slave's r n-- e t-- | | |-- uurelay (uucp relay & news) | +---> uucp neighbours - .DE .'have to use a vertical backbone so that troff can draw the diagram properly. .KE .NH The generic configuration 'slave' .LP The .I slave configuration is used on all machines which have only an ethernet connection. This includes two sun fileservers and their clients. The client workstations all mount /usr/spool/mail from their respective servers. Users with mailboxes on these machines have entries in /usr/lib/aliases pointing to the fileservers so that mail delivery is always done by the server. .SH Note .IP This is only safe if the NFS implementation supports flock() properly, as SUNs after version 3.4 SunOS, and 4.3BSD systems appear to do. Check your documentation. .LP The configuration itself is quite minimal, containing enough information to send mail directly to internal hosts but passing all "unknown" addresses to 'gateway' to resolve. .LP .KS .NH 2 The configuration description 'config.slave' .DS I # basic settings config=slave domain="cs.glasgow.ac.uk" options=multihost,nrsformat postmaster=mailer-daemon tabledir=tables # domain tables domain std file="cs-dept.ether.chn" domain top file="slave.top.dom" # channels channel top file="slave.top.chn" channel local file="cs-dept.local.chn", showldomain,shownrs,showuucp channel ether file="cs-dept.ether.chn" channel ether file="cs-dept.uucp.chn" channel news file="cs-dept.news.chn",relayed .DE .KE .LP Taking the lines one by one: .SH config=slave .LP The name of the configuration is 'slave'. The result of running 'make' will be a file named 'slave.cf'. .SH domain="cs.glasgow.ac.uk" .LP The domain name of the site is .I "cs.glasgow.ac.uk" . Unless otherwise specified, mail leaving the site will be marked .I "From: user@cs.glasgow.ac.uk" . .SH options=multihost,nrsformat .LP The configuration is for a 'multihost' site - more than one host will show itself to the outside world with the same site domain name. The host specific domain name is `hostname`.cs.glasgow.ac.uk but no-one outside the site will be aware of it. .LP The configuration will recognise addresses with domains in the JNT sponsored NRS domain order - e.g. .I user@uk.ac.glasgow.cs . .SH postmaster=mailer-daemon .LP When sending error messages, sendmail will stamp them .I "From: mailer-daemon" . To prevent error loops, messages .I "To: mailer-daemon" should not be allowed to cause error messages themselves. There must therefore be an alias in .I /usr/lib/aliases to send such mail to someone. .SH tabledir=tables .LP We keep the domain and channel tables for all configurations in one directory called "tables" - you will find this directory in the Examples directory. .SH domain std file="cs-dept.ether.chn" .LP The list of domains for local hosts are stored in this file (named relative to tabledir). Note that the same file is also used for the ether channel, since all local hosts are directly reachable on the ethernet. .SH domain top file="slave.top.dom" .LP This contains the top domain data. In fact it contains just the one line .DS uk .DE .LP since these machines send all mail that they cannot deliver to 'gateway'. .SH channel top file="slave.top.chn" .LP This file contains the one line .DS ALL gateway.cs.glasgow.ac.uk .DE .LP which sends all unrecognised domains to the domain .I "gateway.cs.glasgow.ac.uk" , for which there is an entry in .I cs-dept.ether.chn . The domain recognition is thus centralised on the machine 'gateway', with slave machines only containing local information. .LP The advantage of doing this is that the slave configuration only needs to be updated when new machines arrive (or disappear) locally on the ethernet. The disadvantage is that the slaves can not recognise obvious mistakes in addresses - all rubbish will be sent to 'gateway' where it gets rejected. .SH channel local file="cs-dept.local.chn", showldomain, shownrs, showuucp .LP This file contains the site domain name and host specific domain name, thus: .DS cs.glasgow.ac.uk LHOST.cs.glasgow.ac.uk .DE .LP Since this file is shared with other configurations, it also contains some obselete names which still occur from time to time (e.g. .I glasgow.uucp ). .LP Some channel-specific options are specified: .I 'showldomain' causes the local site domain name to be put on messages sent locally, so that mail from another user is delivered with .I "From: user@cs.glasgow.ac.uk" rather than .I "From: user" ; .I 'shownrs' causes message headers to have NRS domain order, so that the message is in fact delivered with .I "From: user@uk.ac.glasgow.cs" ; .I 'showuucp' uses a heuristic to detect uucp style paths in headers. If an address contains several one-word site names, it is presented as a uucp style bang path, so that e.g. .IP From: bill%tipsy%mumps@illvax .LP will be re-written as .IP From: illvax!mumps!tipsy!bill .SH channel ether file="cs-dept.ether.chn" .LP The domains listed in this file are accessible by ethernet. This is the same file as is used for internal domain data above. .SH channel ether file="cs-dept.uucp.chn" .LP We have a second ether channel table containing those few NRS names which are actually uucp sites connected to uurelay. These contain the domain name of the uucp site and 'uurelay' as the host to send to. .SH channel news file="cs-dept.news.chn",relayed .LP The "usernames" described in this file are taken to represent newsgroup names, so that (for example) mail which is addressed to a local user called "comp.mail.sendmail" is sent to the news channel. Since there are hundreds of newsgroups, we use wildcards to match just the top level newsgroup names, e.g. .DS comp.%s uurelay .DE .LP The .I 'relayed' option indicates that .I mail-news is to be invoked on a different host, in this case 'uurelay'. We run news on 'uurelay' and mount its /usr/spool/news filesystem on all the other hosts using NFS (mounted soft,read-only to prevent hanging). On all the other machines .I inews(1) is a shell script containing .DS I #!/bin/sh /usr/hosts/uurelay $0 $@ .DE .NH 2 Installing the configuration file .LP Since this is a shared configuration, we have a shell script to call the program .I Install.sh for each 'slave' host. In the case of the sun fileservers, Install.sh is invoked with the -f option that prevents a freeze file (/usr/lib/sendmail.fc) from being created; on the client machines we only wish to restart the daemons, so we use the -n option, thus we have: .DS I sh Install.sh -f sun1 slave.cf sh Install.sh -n sun2 slave.cf sh Install.sh -n sun3 slave.cf etc . . . .DE .NH 2 Shared system mailboxes .LP As mentioned above, the client workstations mount /usr/spool/mail from their NFS fileservers. At glasgow we go one stage further and only run sendmail SMTP listeners on the servers. Sendmail daemons on the client machines are started with .DS /usr/lib/sendmail -q1h .DE .LP The names of these clients are not in the ether channel or local domain tables because no mail is ever delivered to them - no user has an alias pointing to any such machine and, of course, the .I 'multihost' option ensures that mail sent from these machines contain the site domain name in the from address. .LP The same configuration runs on the NFS servers which can deliver mail locally; on these servers the sendmail daemon is started with .DS /usr/lib/sendmail -q1h -bd .DE .LP in the usual way. .NH The configuration 'gateway' .LP The host .I gateway has access to the ethernet and also has access to JANET, the X.25 based UK academic network. This configuration uses a number of domain tables derived from the NRS (Name Registration Scheme) database. These are produced automatically by the .I c-nrs program (provided with unix-niftp package). For example, the .I "uk.dom" domain table maps institution names to full domain names, with entries like: .DS glasgow glasgow.ac.uk .DE .LP Many sites in the NRS have an abbreviated (or short) name and standard (or long) name, which are different. For example, the short form for .I cs.glasgow.ac.uk is .I cs.gla.ac.uk . Some sites like to rewrite one form into the other (e.g. convert all addresses into standard form) and c-nrs provides a table in which to do this. However, with 300+ entries, this is probably only advisable with IDA sendmail where the table can be compiled to an IDA database. .LP Similarly, there are essentially two ways to set up the janet channel table depending on how much you want sendmail to do, and how much you leave to the FTP system to do: .IP (a) use just wildcards to effectively pass all (unmatched) uk.ac and uk.co addresses to the FTP system for "routing". The unix-niftp system has its own NRS database (using dbm lookup). Local overrides, for example, known uk.co sites which are not NRS registered could be placed in the FTP tables or the janet channel table. .IP (b) Put all entries into the janet channel (with no wildcards). This has the advantages that verification of addresses is done by sendmail directly and that where application relays are involved the JNT header includes the relay domain (minor point). However, addresses should be mapped to a single form in the domain tables so that only one entry is needed per host in the channel table. Again, this approach is probably only advisable with IDA sendmail where both the domain and channel tables can be compiled to ida databases, otherwise your sendmail may run rather slowly. .NH 2 The configuration description 'config.gateway' .DS I #basic settings config=gateway domain="cs.glasgow.ac.uk" options=multihost,nrsformat postmaster=mailer-daemon install=-f tabledir=tables # domain tables domain std file="cs-dept.ether.chn" domain std file="glasgow.uk.dom" # generated by c-nrs domain std file="glasgow.gla.dom" # generated by c-nrs domain std file="glasgow.local.dom" domain std file="glasgow.ukuucp.dom" domain top file="glasgow.top.dom" # channels channel local file="cs-dept.local.chn", showuucp,shownrs,showldomain channel ether file="cs-dept.ether.chn" channel ether file="cs-dept.uucp.chn" channel news file="cs-dept.news.chn",relayed channel janet file="gateway.janet.chn",auth channel top file="glasgow.top.dom" .DE .LP There are some notable differences from the 'slave' configuration: .SH install=-f .LP This configuration can be installed by "make install". The -f flag prevents a frozen configuration file (sendmail.fc) from being made when doing this. .SH Domain tables .LP The domain tables include two NRS derived tables for mapping subdomains of "ac.uk", "co.uk" and "glasgow.ac.uk" to full domains. In addition there is a domain table for mapping uucpnames of hosts connected to glasgow (via uurelay) to their NRS names, and another with names of hosts within the university but not on our ethernet and not in the NRS either. .LP The file .I glasgow.top.dom contains a complete list of top level domains that we recognise. .SH Channel tables .LP The janet channel table we use contains wildcards, with a few entries for local overrides - we run vanilla BSD4.3 sendmail. .LP The janet channel also has the .I auth directive to cause the mailer for that channel to be invoked via .I authorise(8) allowing restrictions to be placed on users of the channel. See the .I User Guide .R and the manual page for .I authorise in the .I Manual directory for more details. .LP The top channel table is the same as the top domain table, specifying relays for the various top level domains; for example, sending all NIC based domains like .I "edu" and .I "com" to .I nss.cs.ucl.ac.uk . .LP Although there is an entry for .I "uk" in this table, it is never used because of the wildcards that match all possible uk addresses in the janet channel table. If we used IDA sendmail with a complete database of uk domains in the janet channel, then we need a separate top channel table with no entry for .I uk - this avoids relaying invalid addresses elsewhere. .NH 2 The configuration description 'config.uurelay' .LP The host .I uurelay has the news system and is the uucp relay. It also has all the domain tables as well, as it's a MIPS/1000 and has lots more spare CPU cycles than 'gateway'. .DS I # basic settings config=uurelay domain="cs.glasgow.ac.uk" options=multihost,nrsformat postmaster=mailer-daemon install=-f tabledir=tables # domain tables domain std file="cs-dept.ether.chn" domain std file="glasgow.uk.dom" # generated by c-nrs domain std file="glasgow.gla.dom" # generated by c-nrs domain std file="glasgow.local.dom" domain std file="glasgow.ukuucp.dom" domain top file="glasgow.top.dom" # channels channel local file="cs-dept.local.chn", shownrs,showuucp,showldomain channel uucp file="uurelay.uucp.chn", ldomain="glasgow.uucp", sysname="glasgow",muucp channel ether file="cs-dept.ether.chn" channel news file="uurelay.news.chn" channel top file="uurelay.top.chn" .DE .LP This description shows the use of the uucp channel. Messages sent by UUCP will have the local domain name faked as "glasgow.uucp" instead of "cs.glasgow.ac.uk"; the UUCP system name is 'glasgow'; the UUCP mailer is .I muucp instead of .I uux(1) . .LP The news channel uses a file specific to this host, because on this host messages for the news are to be delivered rather than forwarded. \Rogue\Monster\ else echo "Will not over-write ./Docs/Tutorial.ms" fi chmod 444 ./Docs/Tutorial.ms if [ `wc -c < ./Docs/Tutorial.ms` -ne 14992 ] then echo 'Got' `wc -c < ./Docs/Tutorial.ms` ', Expected ' 14992 fi echo "Finished archive 2 of 4" exit