BSD 4_3 development

[unix-history] / usr / contrib / mh / READ-ME

MH-GEN(8)           UNIX Programmer's Manual            MH-GEN(8)



NAME
     mh-gen - generating the MH system

READ THIS
     This documentation describes how to configure, generate, and
     install the UCI version of the Rand _\bM_\bH system.  Although the
     _\bM_\bH system was originally developed by the Rand Corporation,
     and is now in the public domain, the Rand Corporation
     assumes no responsibility for _\bM_\bH or this particular modifi-
     cation of _\bM_\bH.

     In addition, the Regents of the University of California
     issue the following disclaimer in regard to the UCI version
     of _\bM_\bH:
          "Although each program has been tested by its contribu-
          tor, no warranty, express or implied, is made by the
          contributor or the University of California, as to the
          accuracy and functioning of the program and related
          program material, nor shall the fact of distribution
          constitute any such warranty, and no responsibility is
          assumed by the contributor or the University of Cali-
          fornia in connection herewith."

     This version of _\bM_\bH is in the public domain, and as such,
     there are no real restrictions on its use.  The _\bM_\bH source
     code and documentation have no licensing restrictions what-
     soever.  As a courtesy, the authors ask only that you pro-
     vide appropriate credit to the Rand Corporation and the
     University of California for having developed the software.

     _\bM_\bH is a software package that is neither supported by the
     Rand Corporation nor the University of California.  However,
     since we do use the software ourselves and plan to continue
     using (and improving) _\bM_\bH, bug reports and their associated
     fixes should be reported back to us so that we may include
     them in future releases.  The current computer mailbox for
     _\bM_\bH is Bug-MH@UCI.EDU (in the ARPA Internet), and
     ...!ucbvax!ucivax!bug-mh (UUCP).  Presently, there are two
     Internet discussion groups, MH-Users@UCI.EDU and
     MH-Workers@UCI.EDU.  If there is sufficient interest,
     corresponding Usenet news groups may be established along
     with the appropriate gateways.

SYNOPSIS
     MAKE

DESCRIPTION
     This is a description of how one can bring up an _\bM_\bH system.
     It is assumed that you have super-user privileges in order
     to (re-)install _\bM_\bH.  Super-user privileges are not required
     to configure or generate _\bM_\bH.




MH                INTEGRATED SOLUTIONS 4.2 BSD                  1






MH-GEN(8)           UNIX Programmer's Manual            MH-GEN(8)



     Become the super-user and create a new directory under
     /usr/src/local/ (or whatever) for the _\bM_\bH area.  Tradition-
     ally, the directory's name should be mh/.  The distribution
     tape contains the hierarchy for the mh.6/ directory.  Bring
     the sources on-line:

     # mkdir /usr/src/local/mh
     % cd /usr/src/local/mh
     % tar xv

CONFIGURATION
     First, go to the conf/ directory.

     % cd conf/

     This directory contains files that will produce source files
     tailored for your choice of _\bM_\bH configuration.  You should
     edit only the file MH.  This file contains configuration
     directives.  These configuration directives are read by the
     _\bm_\bh_\bc_\bo_\bn_\bf_\bi_\bg program to produce customized files.  For examples
     of various configurations, look in the directory
     conf/examples/.  The file MH provided in conf/ is a reason-
     able default.

     Here are the _\bM_\bH configuraton options available:
     bin: /usr/local
          The directory where user-invoked programs go (see
          manual section 1).

     debug: off
          Support for debug mode of _\bM_\bH.  Don't use this unless
          you know what you're doing, which isn't likely if
          you're reading this document!

     etc: /usr/local/lib/mh
          The directory where pgm-invoked programs go (see manual
          section 8).

     mail: /usr/spool/mail
          The directory where the maildrops are stored.  If this
          pathname is absolute (i.e., begins with a / ), then the
          user's maildrop is a file called $USER in this direc-
          tory.  If the pathname is not absolute, then the user's
          maildrop is in the user's home directory under the
          given name.

     mandir: /usr/man
          The parent directory of the manual entries.

     manuals: standard
          Where manual entries should be installed, relative to
          the directory given with "mandir".  Either "local" to



MH                INTEGRATED SOLUTIONS 4.2 BSD                  2






MH-GEN(8)           UNIX Programmer's Manual            MH-GEN(8)



          install manual entries under manl/, or "new" to install
          manual entries under mann/, or "old" to install manual
          entries under mano/, or "standard" to install manual
          entries under man?/, or "gen" to generate but not
          install them, or "none" to neither generate nor install
          them.  For example, to install manual entries under
          /usr/man/u_man/man?, use "standard" and /usr/man/u_man
          for "mandir".

     chown: /etc/chown
          The location of the _\bc_\bh_\bo_\bw_\bn (8) on your system.  If _\bc_\bh_\bo_\bw_\bn
          is in your search path, just use the value of "chown".
          On SYS5 systems, this should probably be "/bin/chown".

     editor: prompter
          The default editor for _\bM_\bH.

     remove: mv -f
          How _\bM_\bH shuld backup existing files when installing a
          new file.

     mts: sendmail
          Which message transport system to use.  Either "mmdf"
          to use _\bM_\bM_\bD_\bF as the transport system, "mmdf2" to use
          _\bM_\bM_\bD_\bF-_\bI_\bI as the transport system, "sendmail" to have
          _\bS_\be_\bn_\bd_\bM_\ba_\bi_\bl as the transport system, or, "mh" to have _\bM_\bH
          as the transport system.  On 4.2BSD UNIX systems you
          can add the suffix "/smtp" to the mts setting.  This
          often yields a superior interface as _\bM_\bH will post mail
          with the local _\bS_\bM_\bT_\bP server instead of interacting
          directly with _\bM_\bM_\bD_\bF or _\bS_\be_\bn_\bd_\bM_\ba_\bi_\bl.  The "/smtp" suffix is
          described in detail in the _\bA_\bd_\bm_\bi_\bn_\bi_\bs_\bt_\br_\ba_\bt_\bo_\br'_\bs _\bG_\bu_\bi_\bd_\be.
          Hence, for 4.2BSD UNIX systems, the "/smtp" suffix to
          either "sendmail" or "mmdf2" is the preferred MTS con-
          figuration.

     bboards: off
          Support for the UCI BBoards facility.  BBoards may be
          enabled with any mts setting.

     bbhome: /usr/spool/bboards
          The home directory for the BBoards user.

     mf: off
          Support for mail filtering on those systems in which
          the message transport system isn't integrated with _\bU_\bU_\bC_\bP
          This option is strictly for an _\bM_\bH system using either
          _\bM_\bM_\bD_\bF-_\bI as its transport system or one using
          "stand-alone delivery".

     pop: off
          Support for POP service.  This allows local delivery



MH                INTEGRATED SOLUTIONS 4.2 BSD                  3






MH-GEN(8)           UNIX Programmer's Manual            MH-GEN(8)



          for non-local users (a major win).  See
          support/pop/pop.rfc for more information on the POP.
          This option currently works only on 4.2BSD UNIX sys-
          tems.  (It doesn't hurt to enable this option regard-
          less of whether or not you intend to use POP.) If POP
          is enabled, there are two additional options which are
          of interest: "RPOP" and "DPOP".  The former indicates
          that support for the UNIX variant of POP, RPOP, which
          uses privileged sockets for authentication be enabled.
          This peacefully co-exists with the standard POP.  The
          "DPOP" option indicates that POP subscribers do not
          have entries in the _\bp_\ba_\bs_\bs_\bw_\bd (5) file, and instead have
          their own separate database (another major win).  Both
          of these options can be enabled via an "options" direc-
          tive in the _\bM_\bH configuration file.

     popbboards: off
          Support for the UCI BBoards facility via the POP ser-
          vice.  Requires both bboards and pop to be enabled.

     options:
          `-D' options to _\bc_\bc (1).

          ALTOS
               Use on XENIX/v7 systems.  Also, be sure to use
               "options V7".

          ATHENA
               _\br_\be_\bp_\bl will assume `-nocc all' as the default
               instead of `-cc all'.

          ATZ
               Directs _\bM_\bH to use alpha-timezones whenever possi-
               ble.

          BANG
               Directs _\bM_\bH to favor `!' over `@'.

          BERK
               Optional for for 4.{2,3}BSD sites running Send-
               Mail.  Makes a lot of simplifying assumptions that
               makes the code run a bit faster.  Also enables one
               other change: _\bs_\bc_\ba_\bn has a -[no]reverse switch which
               does the obvious thing.  _\bM_\bH purists hate this.

          BIND
               If you are running with the BIND code under
               4.{2,3}BSD, be sure to define this.

          BSD42
               Use on Berkeley UNIX systems on or after 4.2BSD.




MH                INTEGRATED SOLUTIONS 4.2 BSD                  4






MH-GEN(8)           UNIX Programmer's Manual            MH-GEN(8)



          BSD41A
               Use on 4.1a Berkeley UNIX systems.

          BSD43
               Use on 4.3 Berkeley UNIX systems.  Also, be sure
               to use "options BSD42".

          COMPAT
               If you previously ran a version of _\bM_\bH earlier than
               mh.4 use this option.  After a short grace period,
               remove it and re-{configure,generate,install}
               everything.

          DPOP
               Enables the POP database, useful only if POP ser-
               vice is enabled.

          DUMB
               Directs _\bM_\bH to minimize address munging.

          FOLDPROT
               Defines the octal value for default folder-
               protection.  For example, FOLDPROT='"0700"'.  The
               default is "0711".

          ISI
               Tells _\br_\be_\bp_\bl to be more conservative in generating
               "cc:"s to the user.

          LINK
               Defines the filename for alternate file name for
               _\bd_\bi_\bs_\bt and _\br_\be_\bp_\bl.  For example, LINK='"\\043"'.  The
               default is "@".

          locname
               Hard-wires the local name for the host _\bM_\bH is run-
               ning on.  For example, locname='"PICKLE"'.  It's
               probably better to either let UNIX tell _\bM_\bH this
               information, or to put the information in the host
               specific mtstailor file.

          MHE
               Enables crude support for Brien Reid's MHE inter-
               face.

          MHRC
               Enables _\bM_\bH to recognize the _\bC_\bS_\bh_\be_\bl_\bl's `~'-con-
               struct.  This is useful for sites that run with a
               ~/.mhrc for their users.

          MORE
               Defines  the location of the _\bm_\bo_\br_\be (1) program.



MH                INTEGRATED SOLUTIONS 4.2 BSD                  5






MH-GEN(8)           UNIX Programmer's Manual            MH-GEN(8)



               For example, on ALTOS and DUAL systems,
               MORE='"/usr/bin/more"'.  The default is
               "/usr/ucb/more".

          MSGPROT
               Defines the octal value for default folder-
               protection For example, MSGPROT='"0600"'.  The
               default is "0644".

          NOMHSEQ
               Directs _\bM_\bH to make private sequences the default.

          OVERHEAD
               Enable _\bM_\bH commands to read profile/context from
               open fd:s without doing an open(); see mh-
               profile(5) for the details.

          RPATHS
               Directs _\bi_\bn_\bc to note UNIX From: lines as Return-
               Path: info.

          RPOP
               Enables the RPOP variant of POP, useful only if
               POP service is enabled.

          SBACKUP
               Defines the prefix string for backup file names.
               For example, SBACKUP='"\\043"'.  The default is
               ",".

          SYS5
               Use on AT&T SYSTEM 5 UNIX system.

          TTYD
               Support for TTYD.

          UCI
               First, "_" and "#" are recognized as the prefixes
               for scratch files.  Second, support for the UCI
               group-leadership mechanism is enabled in _\bc_\bo_\bn_\bf_\bl_\bi_\bc_\bt.
               Third, support for $HOME/.signature files is
               enabled.

          UK
               Directs the _\bs_\bc_\ba_\bn program to generate UK-style
               dates.

          V7
               Use on V7 UNIX systems.  Also, be sure to use
               "options void=int".

          WHATNOW



MH                INTEGRATED SOLUTIONS 4.2 BSD                  6






MH-GEN(8)           UNIX Programmer's Manual            MH-GEN(8)



               Enable certain _\bM_\bH commands to act differently when
               $mhdraft set.

     ccoptions:
          Options given directly to _\bc_\bc (1).  The most common is
          "-M" if you're running _\bM_\bH on an ALTOS.

     curses: -lcurses -ltermlib
          This should be the loader option required to load the
          _\bt_\be_\br_\bm_\bc_\ba_\bp (3) and _\bc_\bu_\br_\bs_\be_\bs (3) libraries on your system.
          On SYS5 systems, it probably should be just "-lcurses".
          Some sites have reported that both "-lcurses" and
          "-ltermlib" are necessary.

     ldoptions:
          Options given directly to _\bl_\bd (1) (via _\bc_\bc ) at the
          beginning of the command line.  Useful for machines
          which require arguments to tell _\bl_\bd to increase the
          stack space (e.g. the Gould, which uses "-m 8").  Usu-
          ally, "-ns" is a good choice in any event.

     ldoptlibs:
          Options given directly to _\bl_\bd (1) (via _\bc_\bc ) at the end
          of the command line.  The two most common are: "-ldbm"
          if you're running MMDF with the _\bd_\bb_\bm package; and,
          "-lndir" if you are generating _\bM_\bH on a system which
          does not load the new directory access mechanism by
          default (e.g., 4.1BSD, SYS5).  If you don't have
          _\bl_\bi_\bb_\bn_\bd_\bi_\br on your system, the sources are in
          miscellany/libndir/.

     oldload: off
          Support for the ALTOS loader.

     ranlib: on
          Support for systems with _\br_\ba_\bn_\bl_\bi_\bb (1).  For SYSTEM 5 sys-
          tems, this should be "off" which tells _\bM_\bH to use _\bl_\bo_\br_\bd_\be_\br
          and _\bt_\bs_\bo_\br_\bt instead.  Some SYSTEM 5 sites reported that
          running this isn't always sufficient.  If this is the
          case, then you should edit conf/makefiles/uip to
          include ../sbr/libmh.a and ../zotnet/libzot.a twice in
          the LIBES variable.

     tma: off
          Support for the TTI _\bt_\br_\bu_\bs_\bt_\be_\bd _\bm_\ba_\bi_\bl _\ba_\bg_\be_\bn_\bt (TMA).  Although
          the TTI TMA is not in the public domain, the _\bM_\bH support
          for the TTI TMA is in the public domain.  You should
          enable this option only if you are licensed to run the
          TMA software (otherwise, you don't have the software in
          your _\bM_\bH source tree).





MH                INTEGRATED SOLUTIONS 4.2 BSD                  7






MH-GEN(8)           UNIX Programmer's Manual            MH-GEN(8)



     Now edit conf/config/mtstailor, depending on your choice of
     the setting for mts in the _\bM_\bH configuration file.  for an
     mts setting of "mh", look at the file conf/tailor/mhmts; for
     an mts setting of "sendmail", "sendmail/smtp", "mmdf/smtp",
     or "mmdf2/smtp", look at the file conf/tailor/sendmts; and,
     for an mts setting of "mmdf", or  "mmdf2", look at the file
     conf/tailor/mmdf.

     Now install the configured files into the source areas.

     % make
     % mhconfig MH

     You now proceed based on your choice of a transport system
     (the setting for mts above).  The best interface is achieved
     with "sendmail" followed by "mmdf" or ("mmdf2"), and then
     "mh" (stand-alone delivery, not recommended).

     SENDMAIL
     If you want _\bS_\be_\bn_\bd_\bM_\ba_\bi_\bl to transport messages for _\bM_\bH, then go
     to the mts/sendmail/ directory.

     % cd ../mts/sendmail/

     This directory contains files whose definitions correspond
     to the configuration of your _\bS_\be_\bn_\bd_\bM_\ba_\bi_\bl system.  If you have
     enabled BBoards or POP service, then you will need to
     re-configure _\bS_\be_\bn_\bd_\bM_\ba_\bi_\bl.  First, in the "local info" section
     of your site's _\bS_\be_\bn_\bd_\bM_\ba_\bi_\bl configuration file, choose a free
     macro/class (B is used in this distribution), and add these
     lines:

          # BBoards support
          DBbboards
          CBbboards

     Second, immediately after the inclusion of the zerobase
     file, in the "machine dependent part of ruleset zero" sec-
     tion, add these lines:

          # resolve names for the BBoards system
          R$+<@$=B>      $#bboards$@$2$:$1        topic@bboards

     Third, add the line

          include(bboardsMH.m4)

     after the line

          include(localm.m4)

     in your site's _\bS_\be_\bn_\bd_\bM_\ba_\bi_\bl configuration file.  Finally, you



MH                INTEGRATED SOLUTIONS 4.2 BSD                  8






MH-GEN(8)           UNIX Programmer's Manual            MH-GEN(8)



     should link the file mts/sendmail/bboardsMH.m4 into your
     _\bS_\be_\bn_\bd_\bM_\ba_\bi_\bl cf/ directory and re-configure _\bS_\be_\bn_\bd_\bM_\ba_\bi_\bl.

     If you have enabled POP service, a similar procedure must be
     used on the POP service host, to re-configure _\bS_\be_\bn_\bd_\bM_\ba_\bi_\bl.
     First, in the "local info" section of your site's _\bS_\be_\bn_\bd_\bM_\ba_\bi_\bl
     configuration file, choose a free macro/class (P is used in
     this distribution), and add these lines:

          # POP support
          DPpop
          CPpop

     Second, immediately after the inclusion of the zerobase
     file, in the "machine dependent part of ruleset zero" sec-
     tion, add these lines:

          # resolve names for the POP system
          R$+<@$=P>      $#pop$@$2$:$1            subscriber@pop

     Third, add the line

          include(popMH.m4)

     after the line

          include(localm.m4)

     in your site's _\bS_\be_\bn_\bd_\bM_\ba_\bi_\bl configuration file.  Finally, you
     should link the file mts/sendmail/popMH.m4 into your _\bS_\be_\bn_\bd_\b-
     _\bM_\ba_\bi_\bl cf/ directory and re-configure _\bS_\be_\bn_\bd_\bM_\ba_\bi_\bl.

     MMDF
     If you want _\bM_\bM_\bD_\bF to be your transport service, and have NOT
     specified "mmdf/smtp" (or "mmdf2/smtp") as your mts setting,
     then go to the mmdf/ directory.  (If you're using
     "mmdf/smtp" or "mmdf2/smtp" as your mts setting, then skip
     to the next section.)

     % cd ../mts/mmdf/

     This directory contains files whose definitions correspond
     to the configuration of your _\bM_\bM_\bD_\bF system.

     If you're running _\bM_\bM_\bD_\bF-_\bI, then copy the following files from
     wherever you keep the _\bM_\bM_\bD_\bF sources to this directory:
     mmdf/h/ch.h, mmdf/h/conf.h, utildir/conf_util.h,
     utildir/ll_log.h, mmdf/h/mmdf.h, utildir/util.h,
     mmdf/mmdf_lib.a, and utildir/util_lib.a.

     If you're running _\bM_\bM_\bD_\bF-_\bI_\bI, then copy the following files
     from where you keep the _\bM_\bM_\bD_\bF sources to this directory:



MH                INTEGRATED SOLUTIONS 4.2 BSD                  9






MH-GEN(8)           UNIX Programmer's Manual            MH-GEN(8)



     h/ch.h, h/conf.h, h/dm.h, h/ll_log.h, h/mmdf.h, h/util.h,
     and lib/libmmdf.a

     If you have enabled bboards, then the directories
     support/bboards/mmdfI and support/bboards/mmdfII contain
     information you'll need to put a UCI BBoards channel in your
     _\bM_\bM_\bD_\bF configuration.  Similarly, if you have enabled option
     "mf" and are running _\bM_\bM_\bD_\bF-_\bI, then the zotnet/mf/mmdfI/
     directory contains information you'll need to put a _\bU_\bU_\bC_\bP
     channel in your _\bM_\bM_\bD_\bF-_\bI configuration.  Finally, the direc-
     tory support/pop/mmdfII contains information you'll need to
     put a POP channel in your _\bM_\bM_\bD_\bF-_\bI_\bI configuration.

     MMDF/SMTP
     If you are using "mmdf/smtp" as your mts setting, then no
     futher MTS-specific action is required on your part!

     MMDF2/SMTP
     If you are using "mmdf2/smtp" as your mts setting, then no
     futher MTS-specific action is required on your part!

     STAND-ALONE DELIVERY
     If, instead, you want _\bM_\bH to handle its own mail delivery,
     then no futher MTS-specific action is required on your part!

GENERATION
     Go to the mh.6/ directory and generate the system.

     % cd ../; make

     This will cause a complete generation of the _\bM_\bH system.  If
     all goes well, proceed with installation.  If not, complain,
     as there "should be no problems" at this step.

INSTALLATION
     If the directories you chose for the user-programs and
     support-programs ("bin" and "etc" in the conf/MH file) don't
     exist, you should create them at this point.

     Before proceeding, you should familiarize yourself with the
     _\bA_\bd_\bm_\bi_\bn_\bi_\bs_\bt_\br_\ba_\bt_\bo_\br'_\bs _\bG_\bu_\bi_\bd_\be.  To generate an _\bn_\br_\bo_\bf_\bf version, go to
     the doc/ directory and type:

     % (cd doc/; make ADMIN.doc)

     To generate a _\bt_\br_\bo_\bf_\bf version, type

     % (cd doc/; make guide)

     instead.





MH                INTEGRATED SOLUTIONS 4.2 BSD                 10






MH-GEN(8)           UNIX Programmer's Manual            MH-GEN(8)



     If you're already running _\bM_\bH at your site, you should also
     read the _\bm_\bh._\b6 changes document.  The sources are in
     papers/mh6/.

     Next, if you enabled support for the UCI BBoards facility,
     then create a login called "bboards" with the following
     characteristics: home directory is /usr/spool/bboards/ with
     mode 755 (actually, use the value for "bbhome" given in the
     _\bM_\bH configuration file), login shell is /bin/csh (or
     /bin/sh), and, encrypted password field is "*".  The
     "bboards" login should own the /usr/spool/bboards/ direc-
     tory.  In addition to creating /usr/spool/bboards/, also
     create /usr/spool/bboards/etc/ and
     /usr/spool/bboards/archive/.  These directories should also
     be owned by the "bboards" login.

     If you enabled support for POP, then on the POP service
     host, create a login called "pop" with the following charac-
     teristics: home directory is /usr/spool/pop/ with mode 755,
     login shell is /bin/csh, and, encrypted password field is
     "*".  If you don't have /bin/csh on your system (V7), then
     /bin/sh is just fine.  The "pop" login should own the
     /usr/spool/pop/ directory.

     If this is not the first time you have installed _\bM_\bH, you may
     wish to preserve the following files:

          _\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by                 _\bf_\bi_\bl_\be_\bs
          etc/                      MailAliases, mtstailor
          /usr/spool/bboards/       BBoards, .cshrc, .mh_profile
          /usr/spool/bboards/etc/   *

     As the super-user, and from the mh.6/ directory, install the
     system.

     # make inst-all

     This will cause the _\bM_\bH processes and files to be transferred
     to the appropriate areas with the appropriate attributes.

TAILORING
     See the _\bA_\bd_\bm_\bi_\bn_\bi_\bs_\bt_\br_\ba_\bt_\bo_\br'_\bs _\bG_\bu_\bi_\bd_\be for information on tailoring
     _\bM_\bH for the MTS, BBoards, and POP.

DOCUMENTATION
     In addition to this document, the administrator's guide, and
     the user's manual, there are several documents referenced by
     the user's manual which may be useful.  The sources for all
     of these can be found under the papers/ directory.

OTHER THINGS
     Consult the directory miscellany/ for the sources to a



MH                INTEGRATED SOLUTIONS 4.2 BSD                 11






MH-GEN(8)           UNIX Programmer's Manual            MH-GEN(8)



     number of things which aren't part of the mainstream _\bM_\bH dis-
     tribution, but which are still quite useful.

FILES
     Too numerous to mention.  Really.

SEE ALSO
     make(1)

BUGS
     The _\bm_\bh_\bc_\bo_\bn_\bf_\bi_\bg program should be smarter.

     The Makefiles should know when _\bm_\bh_\bc_\bo_\bn_\bf_\bi_\bg has been run and
     force "make clean" behavior.









































MH                INTEGRATED SOLUTIONS 4.2 BSD                 12