





          11..  SSmmaaiill IInnssttaallllaattiioonn PPrroocceedduurree

               The  basic  procedures for installing the SSmmaaiill33..11 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.

          11..11..  TThhee SSoouurrccee RReelleeaassee

               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 ssmmaaiill33..11 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 ggeettoopptt 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 ppaatthhaalliiaass 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 ccoommpp..mmaaiill..mmaappss.
               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.

          11..22..  CCoonnffiigguurriinngg SSmmaaiill ffoorr YYoouurr SSyysstteemm

               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.

          11..22..11..  DDeeffiinniinngg yyoouurr OOppeerraattiinngg SSyysstteemm

               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.

          11..22..22..  DDeeffiinniinngg yyoouurr HHoossttnnaammeess

               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.
          SSmmaaiill33..11 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 aammddaahhll..ccoomm.  The machine name  for  this  gateway  is
          aammddaahhll.        Its       value      for      DOMAINS      is
          ``uts.amdahl.com:amdahl.com:uucp''.   With  this  configura-
          tion,    the    primary    name    for    the   gateway   is
          aammddaahhll..uuttss..aammddaahhll..ccoomm     with     other     names     being
          aammddaahhll..aammddaahhll..ccoomm and aammddaahhll..uuuuccpp..

               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
          PPoossttmmaasstteerr@@aammddaahhll..ccoomm   or   PPoossttmmaasstteerr@@uuttss..aammddaahhll..ccoomm  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 uuttss..aammddaahhll..ccoomm domain
          set VISIBLE_NAME to  ``uts.amdahl.com''.   Mail  originating
          from  cchhoonnggoo  on  a  Sun named eeeekk would appear to have been
          sent   from   cchhoonnggoo@@uuttss..aammddaahhll..ccoomm,   rather   than    from
          cchhoonnggoo@@eeeekk..uuttss..aammddaahhll..ccoomm.   The  domain gateway knows where
          the user cchhoonnggoo wishes to receive his mail.   Thus,  replies
          to  mail sent from eeeekk will be returned directly to cchhoonnggoo's
          mailbox rather than passing back through eeeekk.

          11..22..33..  DDiirreeccttoorriieess ffoorr DDaattaa FFiilleess aanndd EExxeeccuuttaabblleess

               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 mmkkaalliiaasseess 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 nneewwaalliiaasseess, some compatibility can be main-
          tained with the sseennddmmaaiill 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
          mmkkaalliiaasseess  utility.   It is also the only alias file defined
          in the default smail configuration.  To maintain compatibil-
          ity  with  sseennddmmaaiill  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''.

          11..33..  BBuuiillddiinngg tthhee SSmmaaiill PPrrooggrraamm aanndd UUttiilliittiieess

               After EDITME and other compile-time configuration files
          have been adjusted (see the section  CCoonnffiigguurriinngg  SSmmaaiill  ffoorr
          YYoouurr  SSyysstteemm)  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.

          11..44..  VVeerriiffyyiinngg tthhee SSmmaaiill PPrrooggrraamm

               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 (rroooott 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.

          11..55..  IInnssttaalllliinngg tthhee PPrrooggrraammss

               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: ggeettoopptt, ppaatthhaalliiaass,  mmaakkeeddbb,  aarrppaattxxtt,  mmkklliinnee,  mmkkssoorrtt,
          ddccaasseehhoosstt,   mmkkddbbmm,  mmkkppaatthh,  mmkkhhppaatthh,  mmkkuuuuwwhhoo,  ppaatthhmmeerrggee,
          cchheecckkeerrrr,  ssaavveelloogg,  ggeettmmaapp,  gglleeeemm,  and  uunnsshhaarrmmaapp.   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.   uuuuwwhhoo  and  mmkkaalliiaasseess.   Also,  the smail
          binary is linked to the names ssmmaaiill, mmaaiillqq,  ppaatthhttoo,  ooppttttoo,
          uuuuppaatthh, rruunnqq and rrssmmttpp.

               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
          mmkkaalliiaasseess 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.   SSmmaaiill33..11  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  mmkkaalliiaasseess  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  nneewwaalliiaasseess  program
          distributed  with  Berkeley's  sseennddmmaaiill  program.   This  is
          expected to change in a future release.












                                       -8-


          11..66..  SSmmaaiill QQuueeuuee RRuunnss

               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 --qq11hh 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 SSyysstteemm VV cron program can safely  put
          this  in  the crontab file for rroooott, 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


          11..77..  LLiisstteenniinngg ffoorr SSMMTTPP RReeqquueessttss

               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 --qq 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.

          11..88..  CClleeaanniinngg UUpp AAfftteerr SSmmaaiill

               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  cchheecckkeerrrr  can  be  called
          from  cron  to  check up on this directory at intervals, and
          send a report on newly failed messages to the address  PPoosstt--
          mmaasstteerr.   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.













































