.\"	This file is automatically generated.  Do not edit!
.po +.75i
.de $c                          \" Major Heading printer
.ce
.b "\\s12\\n+(ch.\\ \\$1\\s0"   \" 12 Point Bold Header
.(x

\ \ \ \\n(ch.\\ \\ \\$1
.)x
.sp 45p         \" 45 point space or about 1/2 inch
..
\".nr xs .15v     \" Put index entries closer together
.(x

Section
.)x _
.de $0          \" Sub-Heading macro called AFTER printing the heading
.(x
.sp .3v
.ti .5i
\\$1
.)x
..
.de $s          \" Macro to print footnote separator
\"\l'2i'        \" No line drawn
.if n \
.       sp 1.3  \" But extra space to make up for it.
..
.fc ^ ~         \" The characters ^ and ~ CANNOT BE USED
\"                 throughout this document except as field
\"                 delimiter & pad indicator!
.he ''-%-''
.ll 32P         \" 32 Picas or about 5+1/3 inch Line Length
.if n .ll 72m   \" Use 72 ems for nroff
.nr ss 30p      \" 30 point space before section titles
.nr fm 5v       \" Rand likes bigger than normal [3v] bottom margins
.nr bm 7v       \"   ditto
.ds . \\fB.\\fP\\h'-(1m/3)' \" Bold period to stand out.
.ds << <\\h!-(\\w'<'/2)!<
.ds >> >\\h!-(\\w'>'/2)!>
.ds ** \v'-3p'\s+1*\s0\v'+3p'
.so version.rf
.tp
.(l C
\fIdiscard this page\fR
.sp 4
The Rand \fIMH\fR
Message Handling
System:
Administrator's Guide
.sp
UCI Version
.sp 2
\*(td
\*(MH
.)l
.++ C
.+c INTRODUCTION

.uh "Scope of this document"
.pp
This is the Administrator's Guide to \fIMH\fR.
If you don't maintain an \fIMH\fR system,
don't read this;
the information is entirely too technical.
If you are a maintainer,
then read this guide until you understand it,
follow the advice it gives,
and then forget about the guide.
.pp
Before continuing, I'll point out two facts:
.sp 2
.(l C
\fIThis document will never contain all the information
you need to maintain MH.
.sp
Furthermore, this document will never contain everything
I know about maintaining MH.\fR
.)l
.sp 2
\fIMH\fR,
and mailsystems in general,
are more complex than most people realize.
A combination of experience, intuition, and tenacity is required to maintain
\fIMH\fR properly.
This document can provide only guidelines for bringing up an \fIMH\fR system
and maintaining it.
There is a sufficient amount of customization possible that not all events or
problems can be forseen.

.uh "Summary"
.pp
During \fIMH\fR generation,
you specify several configuration constants to the \fImhconfig\fR program.
These directives take into consideration such issues as hardware and
operating system dependencies in the source code.
They also factor out some major mailsystem administrative decisions
that are likely to be made consistantly at sites with more than one host.
The manual entry \fImh\-gen\fR\0(8) describes all the static configuration
directives.
.pp
However,
when you install \fIMH\fR you may wish to make some site\-specific
or host\-specific changes which aren't hardware or even software related.
Rather, they are administrative decisions.
That's what this guide is for: it describes all of the dynamically tailorable
directives.
.pp
Usually, after installing \fIMH\fR, you'll want to edit the
\fB/usr/new/lib/mh/mtstailor\fR file.
This file fine-tunes the way \fIMH\fR interacts with the message transport
system (MTS).
Section 2 talks about the MTS interface and MTS tailoring.
.pp
After that, if you're running the UCI BBoards facility,
or the POP facility,
you'll need to know how to maintain those systems.
Sections 3 and 4 talk about these.
.pp
If for some reason
you're not running an MTS that can handle both Internet and \fIUUCP\fR traffic,
you should read\-up on mail filtering in Section 5.
Although this is considered \*(lqold technology\*(rq now,
the mechanisms described in Section 5 were really quite useful when
first introduced way back in 1981.
.pp
Finally, you may want to know how to modify the \fIMH\fR source tree.
Section 6 talks (a little bit) about that.
.pp
The last two sections describe a few hidden features in \fIMH\fR,
and the configuration options that were in effect when this guide was
generated.
.pp
After \fIMH\fR is installed, you should define the address \*(lqBug\-MH\*(rq
to map to either you or the \fIPostMaster\fR at your site.
.pp
In addition,
if you want to tailor the behavior of \fIMH\fR for new users,
you can create and edit the file \fB/usr/new/lib/mh/mh.profile\fR.
When the \fIinstall-mh\fR program is run for a user,
if this file exists, it will copy it into the user's \&.mh\(ruprofile
file.

.\" macros for the .me/.man files
.de SC
.he '\\$1(\\$2)'-%-'\\$1(\\$2)'
.bp
.(x
.ti .8i
\\$1
.)x
..
.de NA
.b \\s-2NAME\\s0
.ti .5i
..
.de SY
.sp
.b \\s-2SYNOPSIS\\s0
.in 1i
.ti .5i
.na
..
.de DE
.ad
.sp
.in 0
.b  \\s-2DESCRIPTION\\s0
.sp
.fi
.in .5i
..
.de Hh
.ad
.sp
.in 0
.b "\\s-2Helpful Hints\\s0"
.sp
.fi
.in .5i
..
.de Fi
.(b L
.ti 0
.b \\s-2Files\\s0
.ta \w'/usr/new/lib/mh/ExtraBigFileName  'u
..
.de Pr
.)b
.(b L F
.ta \w'ExtraBigProfileName  'u
.ti 0
.b "\\s-2Profile Components\\s0"
.ti .5i
..
.de Ps
.ti .5i
..
.de Sa
.)b
.(b L F
.ti 0
.b "\\s-2See Also\\s0"
.br
..
.de De
.)b
.(b L
.in .5i
.ti 0
.b \\s-2Defaults\\s0
..
.de Ds
..
.de Co
.)b
.(b L F
.ti 0
.b \\s-2Context\\s0
.br
..
.de Hi
.)b
.(b L F
.ti 0
.b \\s-2History\\s0
.br
..
.de Bu
.)b
.(b L F
.ti 0
.b \\s-2Bugs\\s0
.br
..
.de En
.)b
.in 0
..

.+c "THE MTS INTERFACE"
.pp
The file \fB/usr/new/lib/mh/mtstailor\fR customizes
certain host\-specific parameters of \fIMH\fR
related primarily to interactions with the transport system.
The parameters in this file override the compiled\-in defaults given during
\fIMH\fR configuration.
Rather than recompiling \fIMH\fR on each host to make minor customizations,
it is easier simply to modify the \fBmtstailor\fR file.
All hosts at a given site normally use the same \fBmtstailor\fR file,
though this need not be the case.
.pp
It is a good idea to run the \fIconflict\fR\0(8) program each morning
under \fIcron\fR.
The following line usually suffices:

.ti +.5i
00 05 * * * /usr/uci/lib/mh/conflict -mail PostMaster

.if t \{
.ll 6.5i
.lt 6.5i
\}
.fo '[mh.6]'MH'UCI version'
.po -.50i
.so mh-tailor.me
.so mh-mts.me
.po +.50i
.he ''-%-''
.fo ''''
.br
.if t \{
.ll 32P
.lt 32P
\}

.+c "BBOARDS"
.pp
If you enable the UCI BBoards facility during configuration,
then the initial environment for bboards
was set\-up during installation.
A BBoard called \*(lqsystem\*(rq is established,
which is the BBoard for general discussion.
.pp
To add more BBoards, become the \*(lqbboards\*(rq user,
and edit the \fB/usr/spool/bboards/BBoards\fR file.
The file \fBsupport/bboards/Example\fR is a copy of the
\fB/usr/spool/bboards/BBoards\fR file that we use at UCI.
When you add a BBoard,
you don't have to create the files associated with it,
the BBoards delivery system will do that automatically.
.pp
Private BBoards may be created.
To add the fictitious private BBoard \*(lqhacks\*(rq,
add the appropriate entry to the BBoards file,
create the empty file \fB/usr/spool/bboards/hacks.mbox\fR (or whatever),
change the mode of this file to 0640,
and change the group of the file to be the groupid of the people that you
want to be able to read it.
Also be sure to add the \*(lqbboards\*(rq user to this group
(in \fB/etc/group\fR),
so the archives can be owned correctly.
.pp
By using the special INVIS flag for a BBoard,
special purpose BBoards may be set\-up which are invisible to the \fIMH\fR
user.
For example,
if a site distributes a BBoard both locally to a number of machines and to a
number of distant machines.
It might be useful to have two distribution lists:
one for all machines on the list, and the other for local machines only.
This is actually very simple to do.
For the main list,
put the standard entry of information in the \fB/usr/spool/bboards/BBoards\fR file,
with the complete distribution list.
For the local machines list,
and add a similar entry to the \fB/usr/spool/bboards/BBoards\fR file.
All the fields should be the same except three:
the BBoard name should reflect a local designation (e.g., \*(lql\-hacks\*(rq),
the distribution list should contain only machines at the local site,
and the flags field should contain the INVIS flag.
Since the two entries share the same primary and archive files,
messages sent to either list are read by local users,
while only thoses messages sent to the main list are read by all users.
.pp
Two automatic facilities for dealing with BBoards exist:
automatic archiving and automatic aliasing.
The file \fBsupport/bboards/crontab\fR contains some entries that you
should add to your \fB/etc/crontab\fR file to run the specified programs
at times that are convenient for you.
The \fBbboards.daily\fR file is run once a day and generates an alias file
for \fIMH\fR.
By using this file, users of \fIMH\fR can use, for example,
\*(lqunix\-wizards\*(rq instead of \*(lqunix\-wizards@brl\-vgr\*(rq
when they want to send a message to the \*(lqunix\-wizards\*(rq
discussion group.
This is a major win, since you just have to know the name of the group,
not the address where it's located.
.pp
The \fBbboards.weekly\fR file is run once a week and handles old
messages (those received more than 12 days ago) in the BBoards area.
In short,
those BBoards which are marked for automatic archiving
will have their old messages placed in the \fB/usr/spool/bboards/archive/\fR area,
or have their old messages removed.
Not only does this make BBoards faster to read,
but it conveniently partitions the new messages from the old messages
so you can easily put the old messages on tape and then remove them.
It turns out that this automatic archiving capability is also a major
win.
.pp
At UCI,
our policy is to save archived messages on tape (every two months or so).
We use a program called \fIbbtar\fR to implement our particular policy.
Since some BBoards are private (see above),
we save the archives on two tapes:
one containing the world\-readable archives
(this tape is read-only accessible to all users by calling the operator),
and the other containing the non\-world\-readable ones
(this tape is kept locked\-up somewhere).
.pp
If POP is enabled with BBoards,
a third directive, POPBBoards, may be enabled.
This allows the \fIMH\fR user to read BBoards on a server machine
instead of the local host (thus saving disk space).
For completely transparent behavior,
the administrator may set certain variables in the \fBmtstailor\fR file
on the client host.
The variable \*(lqbbpophost\*(rq indicates the host where BBoards are
kept
(it doesn't have to be the POP service host,
but this host must run both a POP server and the BBoards system).
The variable \*(lqbbpopuser\*(rq indicates the guest account on this host
for BBoards.
This username should not be either the POP user or the BBoards user.
Usually the anonymous FTP user (ftp) is the best choice.
Finally, the variable \*(lqpopbblist\*(rq indicates the name of a file which
contains a list of hosts (one to a line, official host names only) which
should be allowed to use the POP facility to access BBoards via the guest
account.
(If the file is not present, then no check is made.)
.pp
The \*(lqpopbbuser\*(rq variable should be set on both the client and service
host.
The \*(lqpopbbhost\*(rq variable need be set only on the client host
(the value, of course, is the name of the service host).
The \*(lqpopbblist\*(rq variable need be set only on the service host.
.if t \{
.ll 6.5i
.lt 6.5i
\}
.fo '[mh.6]'MH'UCI version'
.po -.50i
.so bboards5.me
.so bbaka.me
.so bbexp.me
.so bboards8.me
.so bbtar.me
.po +.50i
.he ''-%-''
.fo ''''
.br
.if t \{
.ll 32P
.lt 32P
\}

.+c "POP"
.pp
For POP (Post Office Protocol) client hosts,
you need to edit the \fB/usr/new/lib/mh/mtstailor\fR file to know about two
hosts:
the SMTP service host and the POP service host.
Normally, these are the same.
Change the \*(lqlocalname\*(rq field of the \fBmtstailor\fR file
of \fIMH\fR in the file to be the name of the POP service host.
Also set the value of \*(lqpophost\*(rq to this value.
Finally,
make sure the value of \*(lqservers\*(rq includes the name of the SMTP
service host.
The recommended value for \*(lqservers\*(rq is:

.ti +.5i
servers:\ SMTP\-service\-host localhost \\01localnet
.pp
If you want more information on the Post Office Protocol used by \fIMH\fR,
consult the file \fBsupport/pop/pop.rfc\fR,
which is the \fIMH\fR revision to RFC918.
.pp
For POP service hosts,
you need to run a daemon, \fIpopd\fR\0(8).
The daemon should start at multi\-user boot time,
so adding the lines:
.sp
.nf
.in +.5i
if [ \-f /usr/libexec/popd ]; then
    /usr/libexec/popd & echo \-n ' pop'			>/dev/console
fi
.in \-.5i
.fi
to the \fB/etc/rc.local\fR file is sufficient.
In addition,
on both the POP client and service hosts,
you need to define the port that the POP service uses.
Add the line
.nf
.in +.5i
pop		109/tcp		# experimental
.in \-.5i
.fi
to the \fB/etc/services\fR file (if it's not already there).
.pp
There are two ways to administer POP:
In \*(lqnaive\*(rq mode,
each user-id in the \fIpasswd\fR\0(5) file is considered a POP subscriber.
No changes are required for the mailsystem on the POP service host.
However,
this method requires that each POP subscriber have an entry in the password
file.
The POP server will fetch the user's mail from wherever maildrops are kept on
the POP service host.
This means that if maildrops are kept in the user's home directory,
then each POP subscriber must have a home directory.

In \*(lqsmart\*(rq mode
(enabled via \*(lqDPOP\*(rq being given as a configuration option),
the list of POP subscribers and the list of
login users are completely separate name spaces.
A separate database (simple file similar to the \fIBBoards\fR\0(5) file)
is used to record information about each POP subscriber.
Unfortunately,
the local mailsystem must be changed to reflect this.
This requires two changes (both of which are simple):
First,
the aliasing mechanism is augmented so that POP subscriber addresses
are diverted to a special delivery mechanism.
\fIMH\fR comes with a program, \fIpopaka\fR\0(8),
which generates the additional information to be put in the mailsystem's
alias file.
Second,
a special POP channel (for MMDF-II) or POP mailer (for SendMail)
performs the actual delivery (\fImh.6\fR supplies both).
All it really does is just place the mail in the POP spool area.
.pp
These two different philosophies are not compatible on the same POP service
host: one or the other, but not both may be run.
Clever mailsystem people will note that
the POP mechanism is really a special case of the more general
BBoards mechanism.
.pp
In addition, there is one user-visible difference,
which the administrator controls the availability of.
The difference is whether the POP subscriber must supply a password to the POP
server:
The first method uses the standard ARPA technique of sending a username and a
password.
The appropriate programs (\fIinc\fR, \fImsgchk\fR, and possibly \fIbbc\fR\0)
will prompt the user for this information.
.pp
The second method
(which is enabled via \*(lqRPOP\*(rq being given as a configuration option)
uses the Berkeley UNIX reserved port method for authentication.
This requires that the two or three mentioned above programs be
\fIsetuid\fR to root.
(There are no known holes in any of these programs.)
.pp
These two different philosophies are compatible on the same POP service host:
to selectively disable RPOP for hosts which aren't trusted,
either modify the \fI\&.rhosts\fR file in the case of POP subscribers being
UNIX logins,
or zero the contents of network address field of the \fIpop\fR\0(5) file for
the desired POP subscribers.
.if t \{
.ll 6.5i
.lt 6.5i
\}
.fo '[mh.6]'MH'UCI version'
.po -.50i
.so pop5.me
.so pop8.me
.so popaka.me
.so popd.me
.so popwrd.me
.po +.50i
.he ''-%-''
.fo ''''
.br
.if t \{
.ll 32P
.lt 32P
\}

.+c "MAIL FILTERING"
.pp
There was a time when users on a UNIX host might have had two maildrops:
one from \fIMMDF\fR and the other from \fIUUCP\fR.
This was really a bad problem since it prevented using a single
user\-interface on all of your mail.
Furthermore,
if you wanted to send a message to addresses on different mailsystems,
you couldn't send just one message.
To solve all these problems,
the notion of \fImail filtering\fR was developed that allowed sophisticated
munging and relaying between the two pseudo\-domains.
.pp
\fIMH\fR will perform mail filtering, transparently, if given the MF
configuration option.
However,
with the advent of \fISendMail\fR and further maturation of \fIMMDF\fR,
\fIMH\fR doesn't really need to do this anymore,
since these message transport agents handle it.
.pp
The mail\-filtering stuff is too complicated.
It should be simpler, but, protocol translation really \fIis\fR difficult.
.if t \{
.ll 6.5i
.lt 6.5i
\}
.fo '[mh.6]'MH'UCI version'
.po -.50i
.so mf.me
.so rmail.me
.po +.50i
.he ''-%-''
.fo ''''
.br
.if t \{
.ll 32P
.lt 32P
\}

.+c "MH HACKING"
.pp
Finally, here's a little information on modifying the \fIMH\fR sources.
A word of advice however:
.sp 2
.ce
.b \s+4DON'T\s0
.sp 2
.lp
If you really want new \fIMH\fR capabilities,
write a shell script instead.
After all, 
that's what UNIX is all about, isn't it?
.pp
Here's the organization of the \fIMH\fR source tree.
.sp
.nf
.in +.5i
.ta \w'miscellany/  'u +\w'sendmail/  'u
conf/	configurator tree
config/	compiled configuration constants
dist/	distributor
doc/	manual entries
h/	include files
mts/	MTS\-specific areas
	mh/	standalone delivery
	mmdf/	MMDF\-I, MMDF\-II
	sendmail/	SendMail, SMTP
miscellany/	various sundries
papers/	papers about \fIMH\fR
sbr/	subroutines
support/	support programs and files
	bboards/	UCI BBoards facility
	general/	templates
	pop/	POP facility
uip/	programs
zotnet/	MTS\-independent areas
	bboards/	UCI BBoards facility
	mf/	Mail Filtering
	mts/	MTS constants
	tws/	date routines
.re
.in -.5i
.fi
.if t \{
.ll 6.5i
.lt 6.5i
\}
.fo '[mh.6]'MH'UCI version'
.po -.50i
.so mh-hack.me
.po +.50i
.he ''-%-''
.fo ''''
.br
.if t \{
.ll 32P
.lt 32P
\}

.+c "HIDDEN FEATURES"
.pp
The capabilities discussed here should not be used on a production basis,
as they are either experimental or are useful for debugging \fIMH\fR.

.uh "Debug Facilities"
.pp
The \fImark\fR command has a `\-debug' switch which essentially prints out
all the internal \fIMH\fR data structures for the folder you're looking at.
.pp
The \fIpost\fR command has a `\-debug' switch which does everything but
actually post the message for you.
Instead of posting the draft, it sends it to the standard output.
Similarly,
\fIsend\fR has a `\-debug' switch which gets passed to \fIpost\fR.
.pp
Some \fIMH\fR commands look at environment variables to determine debug\-mode operation
of certain new facilities.
The current list of environment variables is:
.sp
.nf
.in +.5i
.ta \w'MHLPOPDEBUG  'u
^MHFDEBUG~^OVERHEAD facility
^MHLDEBUG~^mhl
^MHPDEBUG~^pick
^MHPOPDEBUG~^POP transactions
^MHVDEBUG~^window management transactions
^MHWDEBUG~^alternate\-mailboxes
.re
.in -.5i
.fi

.uh "Send"
.pp
The \fIsend\fR command has two switches, `\-unique' and `\-nounique',
which are useful to certain individuals who, for obscure reasons,
do not use draft\-folders.

.uh "Posting Mail"
.pp
If you're running a version of \fIMH\fR which talks directly to an
\fISMTP\fR server (or perhaps an advanced \fIMMDF\fR submit process),
there are lots of interesting switches for your amusement which \fIsend\fR
and \fIpost\fR understand:
.nf
.in +.5i
.ta \w'-server host  'u
^-mail~^Use the \fIMAIL\fR command (default)
^-saml~^Use the \fISAML\fR command
^-send~^Use the \fISEND\fR command
^-soml~^Use the \fISOML\fR command
^-snoop~^Watch the \fISMTP\fR transaction
^-client host~^Claim to be \*(lqhost\*(rq when posting mail
^-server host~^Post mail with \*(lqhost\*(rq
.re
.in -.5i
.fi
.pp
The last switch is to be useful when \fIMH\fR resides on small
workstations (or PC:s) in a network\-\-they can post their outgoing mail with
a local relay,
and reduce the load on the local system.
On POP client hosts,
the `\-server\ host' switch is defaulted appropriately using the SMTP
search\-list mechanism.
The \fIwhom\fR command understands the last three switches.

.+c "CONFIGURATION OPTIONS"
.pp
This manual was generated with the following configuration options in
effect:
.sp 2
.hl
.nf
.in +1.25i
.ta \w'BBoards Home Directory      'u
^Generation Date~^\*(td
^Primary Directory~^/usr/new/mh/
^Secondary Directory~^/usr/new/lib/mh/
^Maildrop Location~^/usr/spool/mail/$USER
^Transport System~^SendMail \*(SM
.re
.in -1.5i
.fi
.hl
.\"	table of contents
.he ''''
.fo ''''
.bp
.ce
.b \\s12CONTENTS\\s0
.sp 3
.xp y
.xp x
.bp
.\"	And now the COVER sheet
.po +.325i
.ll 32P
.nf
 
.sp 1.5in
.ps 24
.vs 32
.ft B
.ce 4
THE RAND MH
MESSAGE HANDLING
SYSTEM:
ADMINISTRATOR'S GUIDE
.ft R
.sp .8i
.ps 20
.vs 24
.ce
UCI Version
.sp 0.7i
.ce 2
Marshall T. Rose
.sp 0.5i
.ft I
.ce 3
First Edition:
MH Classic
\s-2(Not to be confused with a well\-known soft drink)\s+2
.ft R
.vs
.sp 1i
.ps 18
.vs 22
.ce 2
\*(td
\*(MH
