This commit was manufactured by cvs2svn to create tag 'FreeBSD-release/1.1'.
[unix-history] / usr.sbin / sendmail / cf / README
index 4a8beda..c026b14 100644 (file)
@@ -4,7 +4,7 @@
 
                Eric Allman <eric@CS.Berkeley.EDU>
 
 
                Eric Allman <eric@CS.Berkeley.EDU>
 
-               @(#)README      8.15 (Berkeley) 10/31/93
+               @(#)README      8.27 (Berkeley) 3/12/94
 
 
 This document describes the sendmail configuration files being used
 
 
 This document describes the sendmail configuration files being used
@@ -13,7 +13,7 @@ there is an ``OLDSENDMAIL'' mode, they haven't really been tested on
 old versions of sendmail and cannot be expected to work well.
 
 These configuration files are probably not as general as previous
 old versions of sendmail and cannot be expected to work well.
 
 These configuration files are probably not as general as previous
-versions, and don't handle as many of the wierd cases automagically.
+versions, and don't handle as many of the weird cases automagically.
 I was able to simplify by them for two reasons.  First, the network
 has become more consistent -- for example, at this point, everyone
 on the internet is supposed to be running a name server, so hacks to
 I was able to simplify by them for two reasons.  First, the network
 has become more consistent -- for example, at this point, everyone
 on the internet is supposed to be running a name server, so hacks to
@@ -23,18 +23,17 @@ a long-haul protocol.  I realize that this is not universal, but it
 does describe the vast majority of sites with which I am familiar,
 including those outside the US.
 
 does describe the vast majority of sites with which I am familiar,
 including those outside the US.
 
-Of course, the downside of this is that if you do live in a wierd
-world, things are going to get wierder for you.  I'm sorry about that,
+Of course, the downside of this is that if you do live in a weird
+world, things are going to get weirder for you.  I'm sorry about that,
 but at the time we at Berkeley had a problem, and it seemed like the
 right thing to do.
 
 This package requires a post-V7 version of m4; if you are running the
 4.2bsd, SysV.2, or 7th Edition version, I suggest finding a friend with
 a newer version.  You can m4-expand on their system, then run locally.
 but at the time we at Berkeley had a problem, and it seemed like the
 right thing to do.
 
 This package requires a post-V7 version of m4; if you are running the
 4.2bsd, SysV.2, or 7th Edition version, I suggest finding a friend with
 a newer version.  You can m4-expand on their system, then run locally.
-SunOS's /usr/5bin/m4 or BSD-Net/2's m4 both work.  GNU m4 (which is a
-language unto itself) also works, but I don't intend to work so hard
-to keep this up in the future.  [Note to GNU folks:  the construct
-"define(`FOO')" should work without my having to add a null value.]
+SunOS's /usr/5bin/m4 or BSD-Net/2's m4 both work.  GNU m4 version 1.1
+also works.  Unfortunately, I'm told that the M4 on BSDI 1.0 doesn't
+work -- you'll have to use a Net/2 or GNU version.
 
 IF YOU DON'T HAVE A BERKELEY MAKE, don't despair!  Just run
 "m4 foo.mc > foo.cf" -- that should be all you need.  There is also
 
 IF YOU DON'T HAVE A BERKELEY MAKE, don't despair!  Just run
 "m4 foo.mc > foo.cf" -- that should be all you need.  There is also
@@ -52,6 +51,13 @@ I'm not pretending that this README describes everything that these
 configuration files can do; clever people can probably tweak them
 to great effect.  But it should get you started.
 
 configuration files can do; clever people can probably tweak them
 to great effect.  But it should get you started.
 
+*******************************************************************
+***  BE SURE YOU CUSTOMIZE THESE FILES!  They have some                ***
+***  Berkeley-specific assumptions built in, such as the name  ***
+***  of our UUCP-relay.  You'll want to create your own domain ***
+***  description, and use that in place of domain/Berkeley.m4. ***
+*******************************************************************
+
 
 +--------------------------+
 | INTRODUCTION AND EXAMPLE |
 
 +--------------------------+
 | INTRODUCTION AND EXAMPLE |
@@ -157,8 +163,12 @@ USENET_MAILER_PATH [/usr/lib/news/inews] The name of the program
 USENET_MAILER_FLAGS    [rlsDFMmn] The mailer flags for the usenet mailer.
 USENET_MAILER_ARGS     [-m -h -n] The command line arguments for the
                        usenet mailer.
 USENET_MAILER_FLAGS    [rlsDFMmn] The mailer flags for the usenet mailer.
 USENET_MAILER_ARGS     [-m -h -n] The command line arguments for the
                        usenet mailer.
+USENET_MAILER_MAX      [100000] The maximum size of messages that will
+                       be accepted by the usenet mailer.
 SMTP_MAILER_FLAGS      [undefined] Flags added to SMTP mailer.  Default
                        flags are `mDFMUX' (and `a' for esmtp mailer).
 SMTP_MAILER_FLAGS      [undefined] Flags added to SMTP mailer.  Default
                        flags are `mDFMUX' (and `a' for esmtp mailer).
+SMTP_MAILER_MAX                [undefined] The maximum size of messages that will
+                       be transported using the smtp or esmtp mailers.
 UUCP_MAILER_FLAGS      [undefined] Flags added to UUCP mailer.  Default
                        flags are `DFMhuU' (and `m' for suucp mailer, minus
                        `U' for uucp-dom mailer).
 UUCP_MAILER_FLAGS      [undefined] Flags added to UUCP mailer.  Default
                        flags are `DFMhuU' (and `m' for suucp mailer, minus
                        `U' for uucp-dom mailer).
@@ -166,11 +176,10 @@ UUCP_MAILER_ARGS  [uux - -r -z -a$f -gC $h!rmail ($u)] The arguments
                        passed to the UUCP mailer.
 UUCP_MAX_SIZE          [100000] The maximum size message accepted for
                        transmission by the UUCP mailers.
                        passed to the UUCP mailer.
 UUCP_MAX_SIZE          [100000] The maximum size message accepted for
                        transmission by the UUCP mailers.
-HOSTMAP_SPEC           [dbm -o /etc/hostmap] The value for the builtin
-                       hostmap key definition.  You can redefine this
-                       to change the class, flags, and filename of
-                       the hostmap.  The default flag (-o) makes this
-                       map optional.
+FAX_MAILER_PATH                [/usr/local/lib/fax/mailfax] The program used to
+                       submit FAX messages.
+FAX_MAILER_MAX         [100000] The maximum size message accepted for
+                       transmission by FAX.
 
 +---------+
 | DOMAINS |
 
 +---------+
 | DOMAINS |
@@ -186,8 +195,6 @@ UUCP_RELAY  The host that will forward UUCP-addressed email.
                connected.
 BITNET_RELAY   The host that will forward BITNET-addressed email.
                If not defined, the .BITNET pseudo-domain won't work.
                connected.
 BITNET_RELAY   The host that will forward BITNET-addressed email.
                If not defined, the .BITNET pseudo-domain won't work.
-CSNET_RELAY    The host that will forward CSNET-addressed email.
-               If not defined, the .CSNET pseudo-domain won't work.
 LOCAL_RELAY    The site that will handle unqualified names -- that
                is, names with out an @domain extension.  If not set,
                they are assumed to belong on this machine.  This
 LOCAL_RELAY    The site that will handle unqualified names -- that
                is, names with out an @domain extension.  If not set,
                they are assumed to belong on this machine.  This
@@ -241,12 +248,15 @@ uucp              The Unix-to-Unix Copy Program mailer.  Actually, this
                is for when you know that the UUCP mailer at the other
                end can handle multiple recipients in one transfer.
                When you invoke this, sendmail looks for all names in
                is for when you know that the UUCP mailer at the other
                end can handle multiple recipients in one transfer.
                When you invoke this, sendmail looks for all names in
-               the $=U class and sends them to the uucp mailer; all
-               names in the $=Y class are sent to suucp.  Note that
+               the $=U class and sends them to the uucp-old mailer; all
+               names in the $=Y class are sent to uucp-new; and all
+               names in the $=Z class are sent to uucp-uudom.  Note that
                this is a function of what version of rmail runs on
                the receiving end, and hence may be out of your control.
                this is a function of what version of rmail runs on
                the receiving end, and hence may be out of your control.
-               If smtp is defined, it also defines a "uucp-dom" mailer
-               that uses domain-style rewriting.
+               If smtp is defined, it also defines "uucp-dom" and
+               "uucp-uudom" mailers that use domain-style rewriting.
+               See the section below describing UUCP mailers in more
+               detail.
 
 usenet         Usenet (network news) delivery.  If this is specified,
                an extra rule is added to ruleset 0 that forwards all
 
 usenet         Usenet (network news) delivery.  If this is specified,
                an extra rule is added to ruleset 0 that forwards all
@@ -258,6 +268,8 @@ fax         Facsimile transmission.  This is experimental and based
                on Sam Leffler's FlexFAX software.  For more information,
                see below.
 
                on Sam Leffler's FlexFAX software.  For more information,
                see below.
 
+pop            Post Office Protocol.
+
 
 +----------+
 | FEATURES |
 
 +----------+
 | FEATURES |
@@ -401,6 +413,20 @@ Complex sites will need more local configuration information, such as
 lists of UUCP hosts they speak with directly.  This can get a bit more
 tricky.  For an example of a "complex" site, see cf/ucbvax.mc.
 
 lists of UUCP hosts they speak with directly.  This can get a bit more
 tricky.  For an example of a "complex" site, see cf/ucbvax.mc.
 
+If your host is known by several different names, you need to augment
+the $=w class.  This is a list of names by which you are known, and
+anything sent to an address using a host name in this list will be
+treated as local mail.  You can do this in two ways: either create
+the file /etc/sendmail.cw containing a list of your aliases (one per
+line), and use ``FEATURE(use_cw_file)'' in the .mc file, or add the
+line:
+
+       Cw alias.host.name
+
+at the end of that file.  See the ``vangogh.mc'' file for an example.
+Be sure you use the fully-qualified name of the host, rather than a
+short name.
+
 The SITECONFIG macro allows you to indirectly reference site-dependent
 configuration information stored in the siteconfig subdirectory.  For
 example, the line
 The SITECONFIG macro allows you to indirectly reference site-dependent
 configuration information stored in the siteconfig subdirectory.  For
 example, the line
@@ -409,18 +435,26 @@ example, the line
 
 reads the file uucp.ucbvax for local connection information.  The
 second parameter is the local name (in this case just "ucbvax" since
 
 reads the file uucp.ucbvax for local connection information.  The
 second parameter is the local name (in this case just "ucbvax" since
-it is locally connected, and hence a UUCP hostname) and the name of
-the class in which to store the host information.  Another SITECONFIG
-line reads
+it is locally connected, and hence a UUCP hostname).  The third
+parameter is the name of both a macro to store the local name (in
+this case, $U) and the name of the class (e.g., $=U) in which to store
+the host information read from the file.  Another SITECONFIG line reads
 
        SITECONFIG(uucp.ucbarpa, ucbarpa.Berkeley.EDU, W)
 
 This says that the file uucp.ucbarpa contains the list of UUCP sites
 connected to ucbarpa.Berkeley.EDU.  The $=W class will be used to
 
        SITECONFIG(uucp.ucbarpa, ucbarpa.Berkeley.EDU, W)
 
 This says that the file uucp.ucbarpa contains the list of UUCP sites
 connected to ucbarpa.Berkeley.EDU.  The $=W class will be used to
-store this list.  [The machine ucbarpa is gone now, but I've left
+store this list, and $W is defined to be ucbarpa.Berkeley.EDU, that
+is, the name of the relay to which the hosts listed in uucp.ucbarpa
+are connected.  [The machine ucbarpa is gone now, but I've left
 this out-of-date configuration file around to demonstrate how you
 might do this.]
 
 this out-of-date configuration file around to demonstrate how you
 might do this.]
 
+Note that the case of SITECONFIG with a third parameter of ``U'' is
+special; the second parameter is assumed to be the UUCP name of the
+local site, rather than the name of a remote site, and the UUCP name
+is entered into $=w (the list of local hostnames) as $U.UUCP.
+
 The siteconfig file (e.g., siteconfig/uucp.ucbvax.m4) contains nothing
 more than a sequence of SITE macros describing connectivity.  For
 example:
 The siteconfig file (e.g., siteconfig/uucp.ucbvax.m4) contains nothing
 more than a sequence of SITE macros describing connectivity.  For
 example:
@@ -433,6 +467,92 @@ same line; these are usually aliases for the same host (or are at
 least in the same company).
 
 
 least in the same company).
 
 
++--------------------+
+| USING UUCP MAILERS |
++--------------------+
+
+It's hard to get UUCP mailers right because of the extremely ad hoc
+nature of UUCP addressing.  These config files are really designed
+for domain-based addressing, even for UUCP sites.
+
+There are four UUCP mailers available.  The choice of which one to
+use is partly a matter of local preferences and what is running at
+the other end of your UUCP connection.  Unlike good protocols that
+define what will go over the wire, UUCP uses the policy that you
+should do what is right for the other end; if they change, you have
+to change.  This makes it hard to do the right thing, and discourages
+people from updating their software.  In general, if you can avoid
+UUCP, please do.
+
+The major choice is whether to go for a domainized scheme or a
+non-domainized scheme.  This depends entirely on what the other
+end will recognize.  If at all possible, you should encourage the
+other end to go to a domain-based system -- non-domainized addresses
+don't work entirely properly.
+
+The four mailers are:
+
+    uucp-old (obsolete name: "uucp")
+       This is the oldest, the worst (but the closest to UUCP) way of
+       sending messages accros UUCP connections.  It does bangify
+       everything and prepends $U (your UUCP name) to the sender's
+       address (which can already be a bang path itself).  It can
+       only send to one address at a time, so it spends a lot of
+       time copying duplicates of messages.  Avoid this if at all
+       possible.
+
+    uucp-new (obsolete name: "suucp")
+       The same as above, except that it assumes that in one rmail
+       command you can specify several recipients.  It still has a
+       lot of other problems.
+
+    uucp-dom
+       This UUCP mailer keeps everything as domain addresses.
+       Basically, it uses the SMTP mailer rewriting rules.
+
+       Unfortunately, a lot of UUCP mailer transport agents require
+       bangified addresses in the envelope, although you can use
+       domain-based addresses in the message header.  (The envelope
+       shows up as the From_ line on UNIX mail.)  So....
+
+    uucp-uudom
+       This is a cross between uucp-new (for the envelope addresses)
+       and uucp-dom (for the header addresses).  It bangifies the
+       envelope sender (From_ line in messages) without adding the
+       local hostname, unless there is no host name on the address
+       at all (e.g., "wolf") or the host component is a UUCP host name
+       instead of a domain name ("somehost!wolf" instead of
+       "some.dom.ain!wolf").
+
+Examples:
+
+We are on host grasp.insa-lyon.fr (UUCP host name "grasp").  The
+following summarizes the sender rewriting for various mailers.
+
+Mailer          sender         rewriting in the envelope
+------         ------          -------------------------
+uucp-{old,new} wolf            grasp!wolf
+uucp-dom       wolf            wolf@grasp.insa-lyon.fr
+uucp-uudom     wolf            grasp.insa-lyon.fr!wolf
+
+uucp-{old,new} wolf@fr.net     grasp!fr.net!wolf
+uucp-dom       wolf@fr.net     wolf@fr.net
+uucp-uudom     wolf@fr.net     fr.net!wolf
+
+uucp-{old,new} somehost!wolf   grasp!somehost!wolf
+uucp-dom       somehost!wolf   somehost!wolf@grasp.insa-lyon.fr
+uucp-uudom     somehost!wolf   grasp.insa-lyon.fr!somehost!wolf
+
+If you are using one of the domainized UUCP mailers, you really want
+to convert all UUCP addresses to domain format -- otherwise, it will
+do it for you (and probably not the way you expected).  For example,
+if you have the address foo!bar!baz (and you are not sending to foo),
+the heuristics will add the @uucp.relay.name or @local.host.name to
+this address.  However, if you map foo to foo.host.name first, it
+will not add the local hostname.  You can do this using the uucpdomain
+feature.
+
+
 +-------------------+
 | TWEAKING RULESETS |
 +-------------------+
 +-------------------+
 | TWEAKING RULESETS |
 +-------------------+
@@ -452,7 +572,7 @@ will cause addresses of the form "decvax!user" and "research!user"
 to be converted to "user@decvax.dec.com" and "user@research.att.com"
 respectively.
 
 to be converted to "user@decvax.dec.com" and "user@research.att.com"
 respectively.
 
-This could also be used to look hosts in a database map:
+This could also be used to look up hosts in a database map:
 
        LOCAL_RULE_3
        R$* < @ $+ > $*         $: $1 < @ $(hostmap $2 $) > $3
 
        LOCAL_RULE_3
        R$* < @ $+ > $*         $: $1 < @ $(hostmap $2 $) > $3
@@ -464,7 +584,7 @@ For example, new rules are needed to parse hostnames that you accept
 via MX records.  For example, you might have:
 
        LOCAL_RULE_0
 via MX records.  For example, you might have:
 
        LOCAL_RULE_0
-       R$+ < @ cnmat.Berkeley.EDU >    $#uucp $@ cnmat $: $1
+       R$+ <@ host.dom.ain.>   $#uucp $@ cnmat $: $1 < @ host.dom.ain.>
 
 You would use this if you had installed an MX record for cnmat.Berkeley.EDU
 pointing at this host; this rule catches the message and forwards it on
 
 You would use this if you had installed an MX record for cnmat.Berkeley.EDU
 pointing at this host; this rule catches the message and forwards it on
@@ -490,9 +610,9 @@ You can have your host masquerade as another using
 
        MASQUERADE_AS(host.domain)
 
 
        MASQUERADE_AS(host.domain)
 
-This causes outgoing SMTP mail to be labelled as coming from the
+This causes outgoing SMTP mail to be labeled as coming from the
 indicated domain, rather than $j.  One normally masquerades as one
 indicated domain, rather than $j.  One normally masquerades as one
-of your own subdomains (for example, it's unlikely that I would
+of one's own subdomains (for example, it's unlikely that I would
 choose to masquerade as an MIT site).
 
 The masquerade name is not normally canonified, so it is important
 choose to masquerade as an MIT site).
 
 The masquerade name is not normally canonified, so it is important
@@ -533,9 +653,11 @@ shared /var/spool/mail scheme, use
        define(`MAIL_HUB', mailer:hostname)
 
 Again, ``mailer:'' defaults to "smtp".  If you define both LOCAL_RELAY
        define(`MAIL_HUB', mailer:hostname)
 
 Again, ``mailer:'' defaults to "smtp".  If you define both LOCAL_RELAY
-and MAIL_HUB, unqualified names and names in class L will be sent to
-the LOCAL_RELAY and other local names will be sent to MAIL_HUB.  For
-example, if are on machine mastodon.CS.Berkeley.EDU, the following
+and MAIL_HUB, unqualified names will be sent to the LOCAL_RELAY and
+other local names will be sent to MAIL_HUB.  Names in $=L will be
+delivered locally, so you MUST have aliases or .forward files for them.
+
+For example, if are on machine mastodon.CS.Berkeley.EDU, the following
 combinations of settings will have the indicated effects:
 
 email sent to....      eric                      eric@mastodon.CS.Berkeley.EDU
 combinations of settings will have the indicated effects:
 
 email sent to....      eric                      eric@mastodon.CS.Berkeley.EDU
@@ -691,7 +813,7 @@ Sam Leffler's FlexFAX software is still in beta test -- but he expects a
 public version out "later this week" [as of 3/1/93].  The following
 blurb is direct from Sam:
 
 public version out "later this week" [as of 3/1/93].  The following
 blurb is direct from Sam:
 
-       $Header: /usr/people/sam/fax/RCS/HOWTO,v 1.14 93/05/24 11:42:16 sam Exp $
+       $Header: /home/cvs/386BSD/src/usr.sbin/sendmail/cf/README,v 1.8 1994/03/19 07:35:36 alm Exp $
 
        How To Obtain This Software (in case all you get is this file)
        --------------------------------------------------------------
 
        How To Obtain This Software (in case all you get is this file)
        --------------------------------------------------------------
@@ -826,7 +948,14 @@ Some options are likely to be deprecated in future versions -- that is,
 the option is only included to provide back-compatibility.  These are
 marked with "*".
 
 the option is only included to provide back-compatibility.  These are
 marked with "*".
 
+Remember that these options are M4 variables, and hence may need to
+be quoted.  In particular, arguments with commas will usually have to
+be ``double quoted, like this phrase'' to avoid having the comma
+confuse things.  This is common for alias file definitions and for
+the read timeout.
+
 M4 Variable Name       Default         Mac/Opt Description
 M4 Variable Name       Default         Mac/Opt Description
+================       =======         ======= ===========
 confMAILER_NAME                MAILER-DAEMON   Dn      The sender name used for
                                                internally generated
                                                outgoing messages.
 confMAILER_NAME                MAILER-DAEMON   Dn      The sender name used for
                                                internally generated
                                                outgoing messages.
@@ -846,8 +975,8 @@ confMIN_FREE_BLOCKS 4               Ob      Minimum number of free blocks
                                                SMTP mail.
 confBLANK_SUB          .               OB      Blank (space) substitution
                                                character.
                                                SMTP mail.
 confBLANK_SUB          .               OB      Blank (space) substitution
                                                character.
-confCON_EXPENSIVE      False           Oc      Connect immediately to
-                                               mailers marked expensive?
+confCON_EXPENSIVE      False           Oc      Avoid connecting immediately
+                                               to mailers marked expensive?
 confCHECKPOINT_INTERVAL        10              OC      Checkpoint queue files
                                                every N recipients.
 confDELIVERY_MODE      background      Od      Default delivery mode.
 confCHECKPOINT_INTERVAL        10              OC      Checkpoint queue files
                                                every N recipients.
 confDELIVERY_MODE      background      Od      Default delivery mode.
@@ -979,7 +1108,7 @@ feature            These hold special orthogonal features that you might
 hack           Local hacks.  These can be referenced using the HACK
                macro.  They shouldn't be of more than voyeuristic
                interest outside the .Berkeley.EDU domain, but who knows?
 hack           Local hacks.  These can be referenced using the HACK
                macro.  They shouldn't be of more than voyeuristic
                interest outside the .Berkeley.EDU domain, but who knows?
-               We've all got our own peccadilloes.
+               We've all got our own peccadillos.
 
 siteconfig     Site configuration -- e.g., tables of locally connected
                UUCP sites.
 
 siteconfig     Site configuration -- e.g., tables of locally connected
                UUCP sites.
@@ -1019,8 +1148,8 @@ RULESETS (* means built in to sendmail)
 MAILERS
 
    0   local, prog     local and program mailers
 MAILERS
 
    0   local, prog     local and program mailers
-   1   smtp            SMTP channel
-   2   uucp            UNIX-to-UNIX Copy Program
+   1   [e]smtp, relay  SMTP channel
+   2   uucp-*          UNIX-to-UNIX Copy Program
    3   netnews         Network News delivery
    4   fax             Sam Leffler's FlexFAX software
 
    3   netnews         Network News delivery
    4   fax             Sam Leffler's FlexFAX software
 
@@ -1029,7 +1158,7 @@ MACROS
 
    A
    B   Bitnet Relay
 
    A
    B   Bitnet Relay
-   C   CSNET Relay
+   C
    D   The local domain -- usually not needed
    E
    F   FAX Relay
    D   The local domain -- usually not needed
    E
    F   FAX Relay
@@ -1095,5 +1224,5 @@ M4 DIVERSIONS
    5   locally interpreted names (overrides $R)
    6   local configuration (at top of file)
    7   mailer definitions
    5   locally interpreted names (overrides $R)
    6   local configuration (at top of file)
    7   mailer definitions
-   8   special local name recognition (late in ruleset 3)
+   8
    9   special local rulesets (1 and 2)
    9   special local rulesets (1 and 2)