





          11..  BBaassiiccss ooff UUssiinngg tthhee SSmmaaiill UUttiilliittiieess

               There  are  a  fairly  large number of utility programs
          that are included in the SSmmaaiill33..11 release.   Most  of  these
          utilities are useful in creating, maintaining and displaying
          databases which can be used by smail for directing and rout-
          ing.   These  database  manipulation  tools are layered such
          that a small set of low-level utilities  are  available  for
          creating  databases in various formats, such as sorted files
          or DBM files (using the _d_b_m(3X) library).  In addition,  the
          mmkklliinnee  and  ppaatthhaalliiaass  tools  can be used in formatting raw
          alias and path data for use by the database creation  tools.
          Built  on  top of these lower level tools are configuration-
          driven tools such as  mmkkaalliiaasseess  and  mmkkppaatthh,  which  handle
          things at a higher level.

               Most  of  these smail utilities are installed under the
          smail library directory, which is normally _/_u_s_r_/_l_i_b_/_s_m_a_i_l.

          11..11..  BBuuiillddiinngg SSiimmppllee DDaattaabbaasseess

               Sorted databases, and _d_b_m-based databases, can be  used
          by  smail  directors  based  on  the  aliasfile driver or by
          routers based on the pathalias driver.  The first command to
          know  about  when  creating these databases is mmkklliinnee.  This
          command takes an alias file or path file  as  input,  strips
          comments and unnecessary white-space, and joins continuation
          lines.  For example, given the alias file:

               # Sample alias file
               Postmaster:
                    tron@futatsu             # Ronald S. Karr
                    chongo@eek               # Landon Noll

               uucp:                         gam@woof# Gordon Moffett

          the mmkklliinnee command would produce, on its standard output:

               Postmaster:tron@futatsu chongo@eek
               uucp:gam@woof


               By removing comments and continuation  lines,  programs
          that create databases can read single line records.

               Sorted  databases  can be created using either the ssoorrtt
          command or the smail mmkkssoorrtt utility.  MMkkssoorrtt does  not  have
          any  line  length  restrictions,  and  can  thus be used for
          aliases and paths containing arbitrarily large records.   It
          does require the ability to read all of its input files into
          memory.  In addition, some versions of the ssoorrtt command  are
          reported  to  have  a bug related to the use of the --ff flag,
          for performing case-independent sorting.  To creat a  sorted
          version  of  the  alias file listed above, use the following









                                       -2-


          command:

               mkline _a_l_i_a_s_f_i_l_e | mksort -f > _a_l_i_a_s_f_i_l_e.sort

          Here, _a_l_i_a_s_f_i_l_e is  the  pathname  containing  the  file  of
          interest.  The --ff flag performs a sort in a case-independent
          manner, as  required  for  the  smail  bbsseeaarrcchh  file  lookup
          method.   This  command  line could also be used to create a
          sorted paths file.  Smaller systems may wish to use ssoorrtt  to
          avoid  high  memory  usage,  or errors due to running out of
          memory.  Path files can be quite large.

               DBM databases can be created using the  mmkkddbbmm  utility.
          To  create  a  database  can  be  used by the smail ddbbmm file
          lookup  method,  for  aliasfile  directors   and   pathalias
          routers, use a command such as:

               mkline _f_i_l_e | mkdbm -f -o _n_a_m_e

          where  _f_i_l_e  is the source text for the database and _n_a_m_e is
          the name for the DBM database.  This will create two  files,
          _n_a_m_e.pag  and  _n_a_m_e.dir  containing the actual data.  The --ff
          flag causes the keys to be converted to  lower  case  before
          being stored in the database.

               Rather  than  require  that you enter a complex command
          every time you have changed the primary  _a_l_i_a_s_e_s  file,  the
          mmkkaalliiaasseess  utility  exists  to do this for you.  It uses the
          configuration defined in the EDITME file  to  determine  how
          your  aliases  file  is  to  be built, and where it is to be
          found, and builds it for you.  For example,  if  your  alias
          database   is   stored   as  a  DBM  file  with  a  name  of
          _/_u_s_r_/_l_i_b_/_a_l_i_a_s_e_s, then the command

               mkaliases

          will execute the shell command:

               mkline /usr/lib/aliases | mkdbm -f -v -o /usr/lib/aliases


          11..22..  BBuuiillddiinngg PPaatthh DDaattaabbaasseess

               Quite often, the building of  path  databases  is  more
          complex  than  taking  one  file  and  running  it through a
          mkline|mksort or a mkline|mkdbm pipeline.  Map data is often
          used,  which  must  be processed by the ppaatthhaalliiaass program to
          produce paths.  As well, this map data can come from a vari-
          ety  of sources, both from map data published monthly in the
          USENET newsgroup ccoommpp..mmaaiill..mmaappss and  from  private  sources,
          such  as maps of local area networks, or a private map entry
          for the local host.











                                       -3-


               The mmkkppaatthh utility is used to organize the path  build-
          ing  process.   It  takes  a  configuration file, describing
          where map files can be found, along with directives control-
          ling  other  data,  and  feeds all of this to pathalias.  It
          produces paths on the standard output.

               An example of a configuration file for  mkpath  is  the
          following file, _w_o_r_l_d_._c_o_n_f:

               # get the usenet world maps
               cd      /usr/spool/uumaps
               safemap d.*
               safemap u.*

               # merge in the new maps
               cd      /usr/lib/smail/maps
               safemap newmap/*.map

               # merge in our external map
               delete  `uuname -l`
               map     world.map private.map tweak.map

          The  configuration file above takes map files beginning with
          _d_.  and _u_.  from the directory  _/_u_s_r_/_s_p_o_o_l_/_u_u_m_a_p_s,  and  map
          files under _/_u_s_r_/_l_i_b_/_s_m_a_i_l_/_m_a_p_s_/_n_e_w_m_a_p.  These map files are
          sent as input to pathalias, the name of the  local  host  is
          deleted from the connectivity information that pathalias has
          collected, and then the  files  _w_o_r_l_d_._m_a_p,  _p_r_i_v_a_t_e_._m_a_p  and
          _t_w_e_a_k_._m_a_p  are  sent  to pathalias.  The reason for deleting
          the local host connectivity information is that  links  from
          the local host should not be determined based on information
          in the maps published by other sites.  After processing  all
          of  this,  a  sorted list of path file entries is written to
          the standard output.  The above configuration file could  be
          used to create a sorted paths file using the command:

               mkpath world.conf > world.path

          A  complete set of examples is distributed with smail in the
          source directory _s_a_m_p_l_e_s_/_a_m_d_a_h_l_/_m_a_p_s.

          11..33..  SSttoorriinngg aanndd DDiissppllaayyiinngg IInnffoorrmmaattiioonn aabboouutt HHoossttss

               The uuuuwwhhoo command can be used by users or site adminis-
          trators  to get a listing of the map entry for a known site.
          It makes use of a database which is formed  by  the  mmkkuuuuwwhhoo
          command.  Mkuuwho takes a mkpath configuration file and pro-
          duces a database which associates each site  name  with  the
          location of the map entry for that site.  The mkpath config-
          uration file is used only  for  determining  where  the  map
          files are to be found.

               With  the  configuration  file used above as an example
          for mmkkppaatthh, the following command can be used to  create  an









                                       -4-


          accompanying uuwho database:

               mkuuwho -u uuwho world.conf

          This  will create a DBM database, in the files _u_u_w_h_o_._p_a_g and
          _u_u_w_h_o_._d_i_r.  After the database is created, the command:

               uuwho foobar

          could be used to display a map entry such as:

               System name:     foobar
               Organization:    Foo Bar, Inc.
               System type:     pdp 11/45, v6 modified
               Contact person:  Joe Stud, III
               Email Address:   foobar!stud3
               Telephone:       +1 605 555 2175
               Postal Address:  Foo Bar, Inc., Wall SD 57790
               Long/Lat:        44 00 43 N / 102 19 59 W
               News links:      namei glotz hoptoad kgbvax kremvax

               #
               #                upstream sites

               foobar   glotz(HOURLY+LOW), namei(HOURLY+HIGH)
               #
               #        downstream sites
               foobar   kgbvax(HOURLY*4), kremvax(HOURLY*4)
               #
               #        our alt.drugs feed
               foobar   hoptoad(DAILY)


          11..44..  EExxttrraaccttiinngg MMaappss FFrroomm UUSSEENNEETT

               The ggeettmmaapp utility can be used to extract  map  entries
          from   the   maps   published   in   the   USENET  newsgroup
          ccoommpp..mmaaiill..mmaappss.  To use this utility  with  netnews  version
          2.11,  for automated map extraction, first put the following
          line into your news _s_y_s file:

               maps:comp.mail.maps,world:F:/usr/spool/uumaps/work/batch

          This  line  will  cause   netnews   to   put   a   line   in
          _/_u_s_r_/_s_p_o_o_l_/_u_u_m_a_p_s_/_w_o_r_k_/_b_a_t_c_h every time an article is posted
          to the ccoommpp..mmaaiill..mmaappss newsgroup.   This  line  contains  the
          pathname to the article file.

               Periodically,  the  ggeettmmaapp  utility  can be executed to
          process the _b_a_t_c_h file, extracting any  map  data  that  has
          been  received.  Getmap should be executed from cron under a
          user  and  group  that  can  write  to  the  map  directory,
          _/_u_s_r_/_s_p_o_o_l_/_u_u_m_a_p_s.   It  will mail any errors to the address
          ppoossttmmaasstteerr.  The period of  execution  should  preclude  the









                                       -5-


          loss  of  any  map  data  as  a  result  of a articles being
          expired, but does not necessarily need to be daily.

          11..55..  SSmmaaiill CClleeaannuupp UUttiilliittiieess

               As discussed  in  a  previous  section,  the  utilities
          cchheecckkeerrrr  and  ssaavveelloogg  exist  to clean up after smail.  The
          cchheecckkeerrrr  utility  checks  for  processing  errors,  sending
          errors  to  the  mail administrator whenever they are found.
          The ssaavveelloogg utility can be used to  perform  log  truncation
          and compression, so that the filesystem containing the smail
          logfile does not eventually fill up.  Both of  these  utili-
          ties should be executed on a daily basis from cron.

               The  ggeettmmaapp utility also keeps a log of its activities,
          in the file _/_u_s_r_/_s_p_o_o_l_/_u_u_m_a_p_s_/_w_o_r_k_/_g_e_t_m_a_p_._l_o_g.   Sites  that
          use  this utility to extract maps from USENET should use the
          ssaavveelloogg utility to truncate and compress this log  as  well.
          However, this should not grow very quickly, so a running the
          necessary savelog command on a monthly basis is  reasonable,
          particularly since this is the period over which map data is
          published.






































