





          11..  SSmmaaiill IInnssttaallllaattiioonn PPrroocceedduurree

               The  basic  procedures for installing the SSmmaaiill33..11 pro-
          gram and its associated utilities require that  you  edit  a
          small  number  of  compile-time  configuration  files, build
          dependencies within all of the  smail  makefiles,  and  then
          build  all  of the executables and install them.  Some sites
          will wish to include the additional step of writing run-time
          configuration files, which are described in a later section.

          11..11..  TThhee SSoouurrccee RReelleeaassee

               When you receive a smail source release and install the
          sources under a directory, the following tree should exist:
               A  plain  text  file describing the release and general
               installation procedures and  giving  the  addresses  of
               useful  mailing lists.  A directory in which a compati-
               bility library is generated containing  functions  that
               do  not  exist  in  your  system's object libraries.  A
               directory containing compile-time configuration  files.
                    A  file  that  should  be  copied  and  edited  to
                    describe your machine and the locations  in  which
                    various files can be found or should be installed.
                    A directory which contains files describing  vari-
                    ous  machine  architectures, such as 32-bit archi-
                    tectures with and without virtual  memory,  or  16
                    bit architectures with extended address spaces.  A
                    directory which contains files describing  various
                    possible   driver   configurations.   These  files
                    define specifically  which  director,  router  and
                    transport  drivers are to be included in the smail
                    binary.  A directory which contains files describ-
                    ing  various  operating systems to which smail has
                    been ported.  To as large an extent as is  reason-
                    able,  operating system dependencies are described
                    solely within these files.   This  directory  con-
                    tains  shell commands and miscellaneous files used
                    from  smail  makefiles  to  digest   configuration
                    information and build dependencies.
               A directory containing the source for the various smail
               guide documents.
                    This directory contains the troff source  for  the
                    _S_m_a_i_l _A_d_m_i_n_i_s_t_r_a_t_i_o_n _a_n_d _I_n_s_t_a_l_l_a_t_i_o_n _G_u_i_d_e.
               A  file  describing  the  history of smail releases, in
               terms of source reorganizations and the addition of new
               capabilities.  A directory containing nroff sources for
               all man pages included in the ssmmaaiill33..11 release.
                    Man pages for user commands.  Man pages describing
                    run-time  configuration  file  formats.  Man pages
                    for administrative  commands  and  other  programs
                    that are not intended to be run directly by users.
               A directory containing public domain sources  that  are
               used  by the smail program or its associated utilities.
                    A replacement  for  _/_b_i_n_/_m_a_i_l  that  traps  mailer









                                       -2-


                    requests and sends them to smail.  This is for use
                    by generic System V sites,  and  for  other  sites
                    that  are  not already setup to call a mailer pro-
                    gram.  This is not normally installed.   A  public
                    domain  release  of  the  System  V ggeettoopptt library
                    function.  Also included is a getopt command which
                    implements  a  super-set of the System V _g_e_t_o_p_t(1)
                    command.  The ppaatthhaalliiaass program by Steve Bellovin,
                    as  told to Peter Honeyman with additional modifi-
                    cations suggested by Landon Noll.   These  sources
                    will  be used as a basis for pathalias version 10.
                    An  implementation  of  various  string  routines.
                    These will be used for systems that do not already
                    have these routines in an object library.  A  pro-
                    gram  for  viewing map entries distributed through
                    USENET in the newsgroup ccoommpp..mmaaiill..mmaappss.
               The source for the smail program.
                    The sources for all director  drivers  distributed
                    with smail.  Director drivers handle the low level
                    operations involved with aliasing, forwarding  and
                    the  recognition of local user names.  The sources
                    for all routing drivers.  Routing  drivers  handle
                    the  low  level  operations  of  finding routes to
                    hosts or domains and binding remote  addresses  to
                    specific  transports.   The sources for all trans-
                    port drivers.  Transport drivers perform  the  low
                    level operations of mail delivery.
               The  sources for various user and administrative utili-
               ties distributed with smail.

          11..22..  CCoonnffiigguurriinngg SSmmaaiill ffoorr YYoouurr SSyysstteemm

               The first step in configuring smail is to copy the file
          _E_D_I_T_M_E_-_d_i_s_t,  in  the  source  directory  _c_o_n_f,  to the file
          _E_D_I_T_M_E in the same directory.   As  the  name  implies,  you
          should  then  edit this file to describe your machine.  This
          file is a shell script that is used to define variables such
          as  what type of operating system you are using, the general
          class of architecture, and where particular data  files  and
          executables  should  reside.   It  is also used to describe,
          within a limited range, the default configuration to be used
          when  the optional runtime configuration files do not exist.

               The _E_D_I_T_M_E file itself contains descriptions of all  of
          the variables that can be defined in this file.  We will not
          attempt to duplicate all of the information here,  though  a
          few pointers may be useful.

          11..22..11..  DDeeffiinniinngg yyoouurr OOppeerraattiinngg SSyysstteemm

               The  variable  OS_TYPE  defines  the basename of a file
          which should describe your operating system.  Possible  val-
          ues  for  OS_TYPE  are  the  names of files in the directory
          _c_o_n_f_/_o_s.  If none of these files  accurately  describe  your









                                       -3-


          system,  then  a  new  file should be created by copying the
          file _t_e_m_p_l_a_t_e to a new name and editing it as appropriate.

               If you port Smail to a new machine, we would appreciate
          receiving  any  patches that were required as well as the os
          file describing that machine.  Any reasonable  contributions
          may be included in future releases.

          11..22..22..  DDeeffiinniinngg yyoouurr HHoossttnnaammeess

               There  are a number of variables used to describe names
          for your machine.  Usually, most of these variables will  be
          left  undefined,  forcing smail to compute the names itself.
          Some variables that you may  wish  to  change  describe  the
          domain  namespaces  in  which your machine resides.  Gateway
          hosts will often require more hostname information  so  that
          they  can  handle mail sent to the domains that they handle,
          rather than to a specific host within them.

               The most important variable to  set  is  DOMAINS  which
          describes   the  domains  under  which  your  host  resides.
          SSmmaaiill33..11 will use a system-dependent algorithm for determin-
          ing  the name for the local host, such as the _g_e_t_h_o_s_t_n_a_m_e(2)
          system call in a BSD operating  system,  or  _u_n_a_m_e(2)  under
          System  V.   The  value  of DOMAINS, in combination with the
          computed value for your machine's name, is used  to  form  a
          list of fully qualified names for your host.  For many sites
          in the UUCP zone, DOMAINS should simply be set to  ``uucp'',
          while domain gateways may need to use multiple values, sepa-
          rated by colons, such as ``uts.amdahl.com:amdahl.com:uucp''.
          The  first domain name in this list is special in that it is
          used in forming the primary (or  _c_a_n_o_n_i_c_a_l)  name  for  your
          machine.   This  name should be unique across all accessible
          networks.

               To understand the use of the  DOMAINS  variable,  let's
          use  the  value  that is used for the gateway machine to the
          domain aammddaahhll..ccoomm.  The machine name  for  this  gateway  is
          aammddaahhll.        Its       value      for      DOMAINS      is
          ``uts.amdahl.com:amdahl.com:uucp''.   With  this  configura-
          tion,    the    primary    name    for    the   gateway   is
          aammddaahhll..uuttss..aammddaahhll..ccoomm     with     other     names     being
          aammddaahhll..aammddaahhll..ccoomm and aammddaahhll..uuuuccpp..

               Additional  names  can  be given to your machine, unre-
          lated to the name smail computes for your host.  This can be
          useful  for  gateways  that  wish to be recognized under the
          names of domains for which they are a gateway.  The variable
          GATEWAY_NAMES  should be set to this colon-separated list of
          alternate  hostnames.   As  an  example,  the  gateway  host
          ``amdahl''           sets          GATEWAY_NAMES          to
          ``uts.amdahl.com:amdahl.com''.  Thus,  an  address  such  as
          PPoossttmmaasstteerr@@aammddaahhll..ccoomm   or   PPoossttmmaasstteerr@@uuttss..aammddaahhll..ccoomm  will
          reach a responsible person rather than being rejected.









                                       -4-


               As a final note on defining host  names,  the  variable
          VISIBLE_NAME  can  be  used  to define the host name used in
          addresses referring to the local host.  This  name  will  be
          used by in contexts where the canonical name is not required
          by DDN standards and can be used to group  a  collection  of
          machines under a domain.  When resolving addresses, the VIS-
          IBLE_NAME string is not matched as a local  hostname  unless
          it also appears in either HOSTNAMES or GATEWAY_NAMES.

               For example, most suns within the uuttss..aammddaahhll..ccoomm domain
          set VISIBLE_NAME to  ``uts.amdahl.com''.   Mail  originating
          from  cchhoonnggoo  on  a  Sun named eeeekk would appear to have been
          sent   from   cchhoonnggoo@@uuttss..aammddaahhll..ccoomm,   rather   than    from
          cchhoonnggoo@@eeeekk..uuttss..aammddaahhll..ccoomm.   The  domain gateway knows where
          the user cchhoonnggoo wishes to receive his mail.   Thus,  replies
          to  mail sent from eeeekk will be returned directly to cchhoonnggoo's
          mailbox rather than passing back through eeeekk.

          11..22..33..  DDiirreeccttoorriieess ffoorr DDaattaa FFiilleess aanndd EExxeeccuuttaabblleess

               As distributed, programs intended to be  run  by  users
          will be installed under the directory _/_u_s_r_/_l_o_c_a_l, while pro-
          grams intended to be run only from cron jobs or  from  other
          smail programs will be installed under _/_u_s_r_/_l_i_b_/_s_m_a_i_l.  Con-
          figuration  files  will   also   be   searched   for   under
          _/_u_s_r_/_l_i_b_/_s_m_a_i_l.   In  addition,  spool and log files will be
          placed in a hierarchy under _/_u_s_r_/_s_p_o_o_l_/_s_m_a_i_l.   These  loca-
          tions can be changed by setting the variables SMAIL_BIN_DIR,
          LIB_DIR and SPOOL_DIRS .

               As the name implies, SPOOL_DIRS can contain  more  than
          one  directory  name.   This  can be used to define multiple
          spool directory hierarchies.  When a new message  comes  in,
          an  attempt  is made to write it into the first hierarchy in
          this list.  If the file cannot be written, the next  hierar-
          chy  is  tried, then the next and so on until the spool file
          is written or no more directory names  exist  in  the  list.
          For        example,        with       a       value       of
          ``/usr/spool/smail:/usr2/spool/smail,''  if  the  filesystem
          containing _/_u_s_r_/_s_p_o_o_l_/_s_m_a_i_l fills up or runs out of _I-nodes,
          an  attempt  is  made  to   write   a   spool   file   under
          _/_u_s_r_2_/_s_p_o_o_l_/_s_m_a_i_l  instead.   Only if this second filesystem
          is also filled up will smail give up in trying to spool  the
          message.

               Some  other  path     names that you may wish to change
          are: the pathname used by smail utilities in  executing  the
          mailer.   Normally,  this will be _/_u_s_r_/_l_i_b_/_s_e_n_d_m_a_i_l which is
          where Berkeley commands and utilities expect the  mailer  to
          reside,  and  where  many public domain programs also expect
          the mailer to reside.  miscellaneous  full  pathnames  under
          which smail will be installed.  _/_b_i_n_/_r_m_a_i_l should be in this
          list, to trap mail coming in over uucp.  _/_b_i_n_/_r_s_m_t_p can also
          be in this list.  When invoked under this name, batched SMTP









                                       -5-


          commands will be read from standard input, allowing SMTP  to
          be  used  over UUCP between cooperating hosts running smail.
          an alternate pathname for the mmkkaalliiaasseess utility, which  pro-
          cesses  an  alias file for use by an _a_l_i_a_s_f_i_l_e director.  By
          installing it as nneewwaalliiaasseess, some compatibility can be main-
          tained with the sseennddmmaaiill utility of the same name.  The pri-
          mary difference is that the new version is not  set-uid  and
          cannot  be  safely  made  so.  Thus, users which do not have
          write access to the directory containing  the  aliases  file
          cannot use this command.  the pathname of the primary alias-
          ing file.  This  is  the  file  that  is  processed  by  the
          mmkkaalliiaasseess  utility.   It is also the only alias file defined
          in the default smail configuration.  To maintain compatibil-
          ity  with  sseennddmmaaiill  under 4.2BSD and 4.3BSD, this should be
          set to ``/usr/lib/aliases''.  However, you may wish to  have
          this  file  under LIB_DIR with the other smail configuration
          files.   This  can  be  done  by  setting   it   simply   to
          ``aliases''.

          11..33..  BBuuiillddiinngg tthhee SSmmaaiill PPrrooggrraamm aanndd UUttiilliittiieess

               After EDITME and other compile-time configuration files
          have been adjusted (see the section  CCoonnffiigguurriinngg  SSmmaaiill  ffoorr
          YYoouurr  SSyysstteemm)  you  are ready to start the build.  The first
          step in building the smail program  and  utilities  on  your
          machine  is  to  generate  all of the _M_a_k_e_f_i_l_e dependencies.
          This step will allow you to modify  compile-time  configura-
          tion  files  and  header  files without worrying about which
          compilations will depend on them.  This information will  be
          stored  in  the Makefiles that need them.  To generate these
          dependencies, use the command:

               make depend

          at the top of the smail source hierarchy.  This will take  a
          while, so you may wish to send the standard output and stan-
          dard error to a file and  put  the  command  in  background.
          This  can  be done in the Bourne or Korn Shell with the com-
          mand:

               make depend > mkdep.out 2>&1 &

          In the C-shell, use the command:

               make depend >& mkdep.out &

          You can watch the progress of the operation  with  the  com-
          mand:

               tail -f mkdep.out

          When the dependencies have been built, build all of the exe-
          cutables with the command:










                                       -6-


               make

          On an Amdahl 5890 this takes two minutes or  more  depending
          upon  machine  load.   For  other  machines,  this  may take
          between a half hour and two hours.

          11..44..  VVeerriiffyyiinngg tthhee SSmmaaiill PPrrooggrraamm

               It is a good idea to  verify  that  the  smail  program
          works  before  actually  installation  it  and the utilities
          around it.  A simple way to do this is to run some commands.
          To start out, try the command:

               src/smail -bv -v _y_o_u_r_-_n_a_m_e@_l_o_c_a_l_-_h_o_s_t

          Here  _y_o_u_r_-_n_a_m_e should be your login name on the local host,
          and _l_o_c_a_l_-_h_o_s_t should be a name for the local host.

          This should produce the following output:

               director user matched user _y_o_u_r_-_u_s_e_r
               _y_o_u_r_-_u_s_e_r ... deliverable


               Next, become superuser (rroooott on most UN*X machines) and
          try the command:

               src/smail -v _y_o_u_r_-_n_a_m_e

          This should produce output such as:

               make directory /usr/spool/smail
               make directory /usr/spool/smail/input
               new spool file is /usr/spool/smail/input/0dMgpi-000089

          Next give a message on standard input such as:

               Subject: This is a first test of Smail3.1

               *hi mom, please send money*
               .

          The  dot,  on  a line by itself, will terminate the message.
          Sending an end of file character will  also  suffice.   This
          should produce:

               make directory /usr/spool/smail/log
               write_log:new msg: from _y_o_u_r_-_u_s_e_r
               director user matched user _y_o_u_r_-_u_s_e_r
               transport local uses driver appendfile
               write_log:_y_o_u_r_-_u_s_e_r ... delivered
               make directory /usr/spool/smail/msglog

          Note that smail creates any directories that it requires, if









                                       -7-


          they do not already exist.  You should now have mail.

               If all of this worked, then there is  probably  nothing
          seriously wrong with the smail program itself.

          11..55..  IInnssttaalllliinngg tthhee PPrrooggrraammss

               When  you  are  satisfied  that the setup appears to be
          okay, try installing the programs on your machine by  becom-
          ing superuser and executing the command:

               make install

          This  will create any required directories and will copy the
          binaries and a small number of data files into  their  final
          locations.  The installation process will create the follow-
          ing: ggeettoopptt, ppaatthhaalliiaass,  mmaakkeeddbb,  aarrppaattxxtt,  mmkklliinnee,  mmkkssoorrtt,
          ddccaasseehhoosstt,   mmkkddbbmm,  mmkkppaatthh,  mmkkhhppaatthh,  mmkkuuuuwwhhoo,  ppaatthhmmeerrggee,
          cchheecckkeerrrr,  ssaavveelloogg,  ggeettmmaapp,  gglleeeemm,  and  uunnsshhaarrmmaapp.   Also
          copied  into the LIB_DIR directory are the files _m_k_p_a_t_h_._a_w_k,
          _m_k_u_u_w_h_o_._a_w_k and _m_k_p_a_t_h_._s_e_d which are used  by  some  of  the
          above  programs,  and  the  file  _C_O_P_Y_I_N_G  which states your
          rights and responsibilities in further distribution  of  the
          smail  programs.   uuuuwwhhoo  and  mmkkaalliiaasseess.   Also,  the smail
          binary is linked to the names ssmmaaiill, mmaaiillqq,  ppaatthhttoo,  ooppttttoo,
          uuuuppaatthh, rruunnqq and rrssmmttpp.

               The  smail  binary  will also be copied to whatever was
          named in the _E_D_I_T_M_E file as the SMAIL_NAME.  Normally,  this
          will  be  _/_u_s_r_/_l_i_b_/_s_e_n_d_m_a_i_l.   It will also be copied to any
          pathnames listed in OTHER_SMAIL_NAMES, such as _/_b_i_n_/_r_m_a_i_l or
          _/_b_i_n_/_r_s_m_t_p.   Also, if you defined a value for NEWALIASES in
          the _E_D_I_T_M_E file, such as _/_u_s_r_/_l_o_c_a_l_/_b_i_n_/_n_e_w_a_l_i_a_s_e_s, then the
          mmkkaalliiaasseess program will be copied to that name.

               All  of the copies of the smail binary will be owned by
          root and have  the  set-uid  bit  set.   SSmmaaiill33..11  has  been
          designed  so  that  it  does not need to run as root, though
          this creates the potential for a a variety of  trojan  horse
          attacks  which  must be carefully handled through configura-
          tion files.  It is generally easier to install  smail  as  a
          setuid  to  root  program  so  that the potential for trojan
          horse attacks is more easily managed.

               The current implementation of  mmkkaalliiaasseess  is  a  Bourne
          shell  script  which  cannot be made secure as a setuid pro-
          gram.  Thus, only users that can write to the directory con-
          taining  the aliases file can successfully run this program.
          This behavior is incompatible with  the  nneewwaalliiaasseess  program
          distributed  with  Berkeley's  sseennddmmaaiill  program.   This  is
          expected to change in a future release.












                                       -8-


          11..66..  SSmmaaiill QQuueeuuee RRuunnss

               When messages block for some reason and  smail  decides
          that it would be best to retry deliver at a later time, mes-
          sages will be left in the _i_n_p_u_t spool directory.   In  order
          to  reattempt  delivery,  a  smail process must scan through
          this directory at intervals  looking  for  work.   This  can
          either be accomplished by starting up one smail process that
          scans for work, sleeps for a set time period, and then scans
          again,  or _c_r_o_n(8) can be used to start up a process to scan
          for work.

               To startup a single smail process that scans  for  work
          at  intervals,  execute  the  following  command  from  your
          machine's _/_e_t_c_/_r_c file:

               /usr/lib/sendmail -q20m

          This will scan for work every twenty minutes.  To  scan  for
          work  once  per  hour use an argument of --qq11hh instead.  This
          command will automatically put itself in background, so  you
          do not need to use an ampersand after the command.

               To  execute  smail  periodically  from cron, use a line
          such as:

               0,20,40 * * * * /usr/lib/sendmail -q

          Each invocation of smail  with  this  command  will  perform
          exactly  one  scan  through the _i_n_p_u_t spool directory, which
          will be done in foreground.

               Systems using the SSyysstteemm VV cron program can safely  put
          this  in  the crontab file for rroooott, or in any other crontab
          file.  Sites running the 4.3BSD version of cron  can  put  a
          line in _/_u_s_r_/_l_i_b_/_c_r_o_n_t_a_b such as:

               0,20,40 * * * * root /usr/lib/sendmail -q


          11..77..  LLiisstteenniinngg ffoorr SSMMTTPP RReeqquueessttss

               If your site supports Berkeley networking, then you can
          use smail to process interactive SMTP requests.  This can be
          done  either  from  a  non-exiting smail daemon, or from the
          4.3BSD or Sun _i_n_e_t daemon.  The decision as  to  whether  to
          use a smail daemon, or the inet daemon depends upon how much
          mail passes through your site and whether  or  not  you  can
          always spare 300K of virtual memory.

               To  invoke  a smail daemon at system boot time, execute
          the following command from _/_e_t_c_/_r_c:











                                       -9-


               /usr/lib/sendmail -bd

          This can be combined with the --qq flag described in the  pre-
          vious section, so executing the command:

               /usr/lib/sendmail -bd -q20m

          will  handle  listening for SMTP connection requests and the
          processing of the _i_n_p_u_t directory at intervals.

               To invoke smail from the 4.3BSD _i_n_e_t_d program, put  the
          following line in _/_e_t_c_/_i_n_e_t_d_._c_o_n_f:

               smtp stream    tcp  nowait    root /usr/local/smtpd smtpd

          If  _s_m_t_p_d  was installed in a different directory, use what-
          ever is appropriate in place of _/_u_s_r_/_l_o_c_a_l_/_s_m_t_p_d.  To invoke
          smail  from  the SunOS _i_n_e_t_d program, put the following line
          in _/_e_t_c_/_s_e_r_v_e_r_s:

               smtp tcp  /usr/local/smtpd


               If you have some other form  of  networking  connection
          that can be used to create a bi-directional interactive con-
          nection, you can use  the  _s_m_t_p_d  program,  or  the  command
          _/_u_s_r_/_l_i_b_/_s_e_n_d_m_a_i_l _-_b_s to receive SMTP requests over that bi-
          directional connection.

          11..88..  CClleeaanniinngg UUpp AAfftteerr SSmmaaiill

               Smail creates log files.  If log files  are  not  trun-
          cated in a reasonable manner, then they will eventually fill
          up all available space.  To handle log  file  truncation,  a
          shell  script,  _s_a_v_e_l_o_g is provided to cycle a log through a
          set of files, where no more than a set number of  files  are
          kept.  As an example, the command:

               /usr/lib/smail/savelog /usr/spool/smail/log/logfile

          will      rename      the      smail     log     file     to
          _/_u_s_r_/_s_p_o_o_l_/_s_m_a_i_l_/_l_o_g_/_O_L_D_/_l_o_g_f_i_l_e_._1.  If  this  file  already
          exists,  it will be renamed to _l_o_g_f_i_l_e_._2 before the original
          logfile is renamed, and so on  up  to  _l_o_g_f_i_l_e_._7.   Whenever
          _l_o_g_f_i_l_e_._6  is renamed to _l_o_g_f_i_l_e_._7, this last file is simply
          removed.

               If the _c_o_m_p_r_e_s_s program is  available,  then  _l_o_g_f_i_l_e_._2
          through  _l_o_g_f_i_l_e_._7  are  kept  in  a compressed form with an
          extension of _._Z.  Different compression programs may also be
          used, generating logfiles with different extensions.

               Running  the  above  savelog command from cron once per
          day will thus keep the last  seven  days  worth  of  logfile









                                      -10-


          data, much of it in a compressed form.

               Occasionally,  smail  will  run  into  a  problem  that
          requires the attention of a mail administrator.  An  example
          of this is an error in the configuration files.  Rather than
          continually retrying a message and continually failing, mes-
          sages  are  moved  into  an  _e_r_r_o_r directory under the spool
          directory hierarchy.  The utility  cchheecckkeerrrr  can  be  called
          from  cron  to  check up on this directory at intervals, and
          send a report on newly failed messages to the address  PPoosstt--
          mmaasstteerr.   This  script  should  be run periodically, perhaps
          once per day, under a user that can write to the _e_r_r_o_r spool
          directory.   Normally,  this  requires  that it run as root,
          though the _c_h_o_w_n(1) command  can  be  used  to  assign  this
          directory to an alternate user.













































