1 .\" This file is automatically generated. Do not edit!
2 .\" @(#)$Id: ADMIN.rf,v 2.17 1995/12/06 22:42:25 jromine Exp $
4 .de $c \" Major Heading printer
6 .b "\\s12\\n+(ch.\\ \\$1\\s0" \" 12 Point Bold Header
9 \ \ \ \\n(ch.\\ \\ \\$1
11 .sp 45p \" 45 point space or about 1/2 inch
13 \".nr xs .15v \" Put index entries closer together
18 .de $0 \" Sub-Heading macro called AFTER printing the heading
25 .de $s \" Macro to print footnote separator
26 \"\l'2i' \" No line drawn
28 . sp 1.3 \" But extra space to make up for it.
30 .fc ^ ~ \" The characters ^ and ~ CANNOT BE USED
31 \" throughout this document except as field
32 \" delimiter & pad indicator!
34 .ll 32P \" 32 Picas or about 5+1/3 inch Line Length
35 .if n .ll 72m \" Use 72 ems for nroff
36 .nr ss 30p \" 30 point space before section titles
37 .nr fm 5v \" RAND likes bigger than normal [3v] bottom margins
39 .ds . \\fB.\\fP\\h'-(1m/3)' \" Bold period to stand out.
40 .ds << <\\h!-(\\w'<'/2)!<
41 .ds >> >\\h!-(\\w'>'/2)!>
42 .ds ** \v'-3p'\s+1*\s0\v'+3p'
46 \fIdiscard this page\fR
61 .uh "Scope of this document"
63 This is the Administrator's Guide to \fIMH\fR.
64 If you don't maintain an \fIMH\fR system,
66 the information is entirely too technical.
67 If you are a maintainer,
68 then read this guide until you understand it,
69 follow the advice it gives,
70 and then forget about the guide.
72 Before continuing, I'll point out two facts:
75 \fIThis document will never contain all the information
76 you need to maintain MH.
78 Furthermore, this document will never contain everything
79 I know about maintaining MH.\fR
83 and mailsystems in general,
84 are more complex than most people realize.
85 A combination of experience, intuition, and tenacity is required to maintain
87 This document can provide only guidelines for bringing up an \fIMH\fR system
89 There is a sufficient amount of customization possible that not all events or
90 problems can be forseen.
94 During \fIMH\fR generation,
95 you specify several configuration constants to the \fImhconfig\fR program.
96 These directives take into consideration such issues as hardware and
97 operating system dependencies in the source code.
98 They also factor out some major mailsystem administrative decisions
99 that are likely to be made consistantly at sites with more than one host.
100 The manual entry \fImh\-gen\fR\0(8) describes all the static configuration
104 when you install \fIMH\fR you may wish to make some site\-specific
105 or host\-specific changes which aren't hardware or even software related.
106 Rather, they are administrative decisions.
107 That's what this guide is for: it describes all of the dynamically tailorable
110 Usually, after installing \fIMH\fR, you'll want to edit the
111 \fB/opt/mh-6.8.5/lib/mtstailor\fR file.
112 This file fine-tunes the way \fIMH\fR interacts with the message transport
114 Section 2 talks about the MTS interface and MTS tailoring.
116 After that, if you're running the UCI BBoards facility,
118 you'll need to know how to maintain those systems.
119 Sections 3 and 4 talk about these.
122 you're not running an MTS that can handle both Internet and \fIUUCP\fR traffic,
123 you should read\-up on mail filtering in Section 5.
124 Although this is considered \*(lqold technology\*(rq now,
125 the mechanisms described in Section 5 were really quite useful when
126 first introduced way back in 1981.
128 Finally, you may want to know how to modify the \fIMH\fR source tree.
129 Section 6 talks (a little bit) about that.
131 The last two sections describe a few hidden features in \fIMH\fR,
132 and the configuration options that were in effect when this guide was
135 After \fIMH\fR is installed, you should define the address \*(lqBug\-MH\*(rq
136 to map to either you or the \fIPostMaster\fR at your site.
139 if you want to tailor the behavior of \fIMH\fR for new users,
140 you can create and edit the file \fB/opt/mh-6.8.5/lib/mh.profile\fR.
141 When the \fIinstall-mh\fR program is run for a user,
142 if this file exists, it will copy it into the user's \&.mh\(ruprofile
145 .\" macros for the .me/.man files
147 .he '\\$1(\\$2)'-%-'\\$1(\\$2)'
169 .b \\s-2DESCRIPTION\\s0
186 .b "\\s-2Helpful Hints\\s0"
195 .ta \w'/opt/mh-6.8.5/lib/ExtraBigFileName 'u
200 .ta \w'ExtraBigProfileName 'u
202 .b "\\s-2Profile Components\\s0"
212 .b "\\s-2See Also\\s0"
250 .+c "THE MTS INTERFACE"
252 The file \fB/opt/mh-6.8.5/lib/mtstailor\fR customizes
253 certain host\-specific parameters of \fIMH\fR
254 related primarily to interactions with the transport system.
255 The parameters in this file override the compiled\-in defaults given during
256 \fIMH\fR configuration.
257 Rather than recompiling \fIMH\fR on each host to make minor customizations,
258 it is easier simply to modify the \fBmtstailor\fR file.
259 All hosts at a given site normally use the same \fBmtstailor\fR file,
260 though this need not be the case.
262 It is a good idea to run the \fIconflict\fR\0(8) program each morning
264 The following line usually suffices:
267 00 05 * * * /opt/mh-6.8.5/lib/conflict -mail PostMaster
273 .fo '[mh.6]'MH.6.8'UCI version'
288 The UCI BBoards facility has two aspects: message reading, and
289 message delivery. The configuration directives applicable to
290 BBoards are \*(lqbboards: on/off/pop/nntp\*(rq and
291 \*(lqbbdelivery: on/off\*(rq.
292 .uh "BBoard Delivery"
294 If you enabled BBoards delivery (\*(lqbbdelivery: on\*(rq)
295 during configuration,
296 then the initial environment for bboards delivery
297 was set\-up during installation.
298 A BBoard called \*(lqsystem\*(rq is established,
299 which is the BBoard for general discussion.
301 To add more BBoards, become the \*(lqbboards\*(rq user,
302 and edit the \fB/usr/spool/bboards/BBoards\fR file.
303 The file \fBsupport/bboards/Example\fR is a copy of the
304 \fB/usr/spool/bboards/BBoards\fR file that we use at UCI.
305 When you add a BBoard,
306 you don't have to create the files associated with it,
307 the BBoards delivery system will do that automatically.
309 Private BBoards may be created.
310 To add the fictitious private BBoard \*(lqhacks\*(rq,
311 add the appropriate entry to the BBoards file,
312 create the empty file \fB/usr/spool/bboards/hacks.mbox\fR (or whatever),
313 change the mode of this file to 0640,
314 and change the group of the file to be the groupid of the people that you
315 want to be able to read it.
316 Also be sure to add the \*(lqbboards\*(rq user to this group
317 (in \fB/etc/group\fR),
318 so the archives can be owned correctly.
320 By using the special INVIS flag for a BBoard,
321 special purpose BBoards may be set\-up which are invisible to the \fIMH\fR
324 if a site distributes a BBoard both locally to a number of machines and to a
325 number of distant machines.
326 It might be useful to have two distribution lists:
327 one for all machines on the list, and the other for local machines only.
328 This is actually very simple to do.
330 put the standard entry of information in the \fB/usr/spool/bboards/BBoards\fR file,
331 with the complete distribution list.
332 For the local machines list,
333 and add a similar entry to the \fB/usr/spool/bboards/BBoards\fR file.
334 All the fields should be the same except three:
335 the BBoard name should reflect a local designation (e.g., \*(lql\-hacks\*(rq),
336 the distribution list should contain only machines at the local site,
337 and the flags field should contain the INVIS flag.
338 Since the two entries share the same primary and archive files,
339 messages sent to either list are read by local users,
340 while only thoses messages sent to the main list are read by all users.
342 Two automatic facilities for dealing with BBoards exist:
343 automatic archiving and automatic aliasing.
344 The file \fBsupport/bboards/crontab\fR contains some entries that you
345 should add to your \fB/usr/lib/crontab\fR file to run the specified programs
346 at times that are convenient for you.
347 The \fBbboards.daily\fR file is run once a day and generates an alias file
349 By using this file, users of \fIMH\fR can use, for example,
350 \*(lqunix\-wizards\*(rq instead of \*(lqunix\-wizards@brl\-vgr\*(rq
351 when they want to send a message to the \*(lqunix\-wizards\*(rq
353 This is a major win, since you just have to know the name of the group,
354 not the address where it's located.
356 The \fBbboards.weekly\fR file is run once a week and handles old
357 messages (those received more than 12 days ago) in the BBoards area.
359 those BBoards which are marked for automatic archiving
360 will have their old messages placed in the \fB/usr/spool/bboards/archive/\fR area,
361 or have their old messages removed.
362 Not only does this make BBoards faster to read,
363 but it conveniently partitions the new messages from the old messages
364 so you can easily put the old messages on tape and then remove them.
365 It turns out that this automatic archiving capability is also a major
369 our policy is to save archived messages on tape (every two months or so).
370 We use a program called \fIbbtar\fR to implement our particular policy.
371 Since some BBoards are private (see above),
372 we save the archives on two tapes:
373 one containing the world\-readable archives
374 (this tape is read-only accessible to all users by calling the operator),
375 and the other containing the non\-world\-readable ones
376 (this tape is kept locked\-up somewhere).
377 .uh "BBoards with the POP"
379 If you configured \fIMH\fP with \*(lqbboards: pop\*(rq and \*(lqpop: on\*(rq,
380 then the \fIMH\fR user is allowed to read BBoards on a server machine
381 instead of the local host (thus saving disk space).
382 For completely transparent behavior,
383 the administrator may set certain variables in the \fBmtstailor\fR file
385 The variable \*(lqpopbbhost\*(rq indicates the host where BBoards are
387 (it doesn't have to be the POP service host,
388 but this host must run both a POP server and the BBoards system).
389 The variable \*(lqpopbbuser\*(rq indicates the guest account on this host
391 This username should not be either the POP user or the BBoards user.
392 Usually the anonymous FTP user (ftp) is the best choice.
393 Finally, the variable \*(lqpopbblist\*(rq indicates the name of a file which
394 contains a list of hosts (one to a line, official host names only) which
395 should be allowed to use the POP facility to access BBoards via the guest
397 (If the file is not present, then no check is made.)
399 The \*(lqpopbbuser\*(rq variable should be set on both the client and service
401 The \*(lqpopbbhost\*(rq variable need be set only on the client host
402 (the value, of course, is the name of the service host).
403 The \*(lqpopbblist\*(rq variable need be set only on the service host.
407 if a POP service host is not explicitly given by the user
408 (i.e., \*(lqpopbbhost\*(rq is implicitly used),
409 then \fIbbc\fR will explicitly check the local host prior to contacting
411 This allows each POP client host to have a few local BBoards
412 (e.g., each host could have one called \*(lqsystem\*(rq),
413 and then have the POP service host used for all the rest
414 (a site\-wide BBoard might be known as \*(lqgeneral\*(rq).
415 .uh "BBoards with the NNTP"
417 If you configured \fIMH\fP with \*(lqbboards: nntp\*(rq and \*(lqpop: on\*(rq,
419 the \fIMH\fR user is allowed to read the Network News on a
420 server machine using the standard \fIbbc\fR command.
421 For completely transparent behavior,
422 the administrator may set the \*(lqnntphost\*(rq variable in the
423 \fBmtstailor\fR file to indicate the host where the Network News is kept.
424 The \*(lqnntphost\*(rq variable should be set only on the client host
427 if an NNTP service host is not explicitly given by the user
428 (i.e., \*(lqnntphost\*(rq is implicitly used),
429 then \fIbbc\fR will explicitly check the local host prior to contacting
431 This allows each NNTP client host to have a few local BBoards
432 (e.g., each host could have one called \*(lqsystem\*(rq),
433 and then have the NNTP service host used for to read the Network News.
435 Reading BBoards via the POP and via the NNTP are mutually exclusive.
440 .fo '[mh.6]'MH.6.8'UCI version'
458 For POP (Post Office Protocol) client hosts,
459 you need to edit the \fB/opt/mh-6.8.5/lib/mtstailor\fR file to know about two
461 the SMTP service host and the POP service host.
462 Normally, these are the same.
463 Change the \*(lqlocalname\*(rq field of the \fBmtstailor\fR file
464 of \fIMH\fR in the file to be the name of the POP service host.
465 This makes replies to mail generated on the POP client host possible,
466 since \fIMH\fR will consider use the hostname of the POP service host as the
467 local hostname for outgoing mail.
468 Also set the value of \*(lqpophost\*(rq to this value.
469 This tells \fIinc\fR and \fImsgchk\fR to use POP instead of looking for mail
472 make sure the value of \*(lqservers\*(rq includes the name of the SMTP
474 The recommended value for \*(lqservers\*(rq is:
477 servers:\ SMTP\-service\-host localhost \\01localnet
479 If you want more information on the Post Office Protocol used by \fIMH\fR,
480 consult the files \fBsupport/pop/rfc1081.txt\fP and
481 \fBsupport/pop/rfc1082.txt\fP which describe the \fIMH\fP version of
484 For POP service hosts,
485 you need to run a daemon, \fIpopd\fR\0(8).
486 The daemon should start at multi\-user boot time,
491 if [ \-f /etc/popd ]; then
492 /etc/popd & echo \-n ' pop' >/dev/console
497 to the \fB/etc/rc.local\fR file is sufficient.
499 The port assigned to the POP3 protocol is \*(lq110\*(rq.
500 For historical reasons, many sites are using port \*(lq109\*(rq
501 which is the port assigned to the \*(lqPOP\*(rq (version 1 and 2) protocol.
502 The configuration option \*(lqPOPSERVICE\*(rq is the name of the
503 port number that \fIMH\fP POP will try to use, and defaults to the
506 To generate \fIMH\fP to use newer assigned port number,
507 in your \fIMH\fP config file, add:
510 options POPSERVICE='\*(lqpop3\*(rq'
512 And on both the POP client and service hosts,
513 you need to define the port that the POP service uses.
522 to the \fB/etc/services\fR file (if it's not already there).
524 There are two ways to administer POP:
525 In \*(lqnaive\*(rq mode,
526 each user-id in the \fIpasswd\fR\0(5) file is considered a POP subscriber.
527 No changes are required for the mailsystem on the POP service host.
529 this method requires that each POP subscriber have an entry in the password
531 The POP server will fetch the user's mail from wherever maildrops are kept on
532 the POP service host.
533 This means that if maildrops are kept in the user's home directory,
534 then each POP subscriber must have a home directory.
536 In \*(lqsmart\*(rq mode
537 (enabled via \*(lqDPOP\*(rq being given as a configuration option),
538 the list of POP subscribers and the list of
539 login users are completely separate name spaces.
540 A separate database (simple file similar to the \fIBBoards\fR\0(5) file)
541 is used to record information about each POP subscriber.
543 the local mailsystem must be changed to reflect this.
544 This requires two changes (both of which are simple):
546 the aliasing mechanism is augmented so that POP subscriber addresses
547 are diverted to a special delivery mechanism.
548 \fIMH\fR comes with a program, \fIpopaka\fR\0(8),
549 which generates the additional information to be put in the mailsystem's
552 a special POP channel (for MMDF-II) or POP mailer (for SendMail)
553 performs the actual delivery (\fImh.6\fR supplies both).
554 All it really does is just place the mail in the POP spool area.
556 These two different philosophies are not compatible on the same POP service
557 host: one or the other, but not both may be run.
558 Clever mailsystem people will note that
559 the POP mechanism is really a special case of the more general
562 In addition, there is one user-visible difference,
563 which the administrator controls the availability of.
564 The difference is whether the POP subscriber must supply a password to the POP
566 The first method uses the standard ARPA technique of sending a username and a
568 The appropriate programs (\fIinc\fR, \fImsgchk\fR, and possibly \fIbbc\fR\0)
569 will prompt the user for this information.
572 (which is enabled via \*(lqRPOP\*(rq being given as a configuration option)
573 uses the Berkeley UNIX reserved port method for authentication.
574 This requires that the two or three mentioned above programs be
575 \fIsetuid\fR to root.
576 (There are no known holes in any of these programs.)
578 To add a POP subscriber,
579 for the first method, one simply follows the usual procedures for adding a
580 new user, which eventually results in adding a line to the \fIpasswd\fR\0(5)
582 for the second method, one must edit the POP database file
583 (kept in the home directory of the POP user),
584 and then run the \fIpopaka\fR program.
585 The output of this program is placed in the aliases file for the transport
586 system (e.g., \fB/usr/lib/aliases\fR for SendMail).
588 Authentication for POP subscribers differs
589 depending on the two methods.
590 When the user supplies a password for the POP session:
591 under the first method,
592 the contents of the password field for the user's entry in the
593 \fIpasswd\fR\0(5) is consulted;
594 under the second method,
595 the contents of the password field for the subscriber's entry in the
596 \fIpop\fR\0(5) file is consulted.
597 (To set this field, the \fIpopwrd\fR\0(8) program is used.)
599 If you are allowing RPOP,
600 under the first method,
601 the user's \fI\&.rhosts\fR file is consulted;
602 under the second method,
603 the contents of the network address field for the subscriber's entry
604 in the \fIpop\fR\0(5) file is consulted.
607 a third authentication scheme is available.
608 When the APOP configuration option is given,
612 options APOP='\*(lq/etc/pop.auth\*(rq'
615 the server also allows a client to supply authentication
616 credentials to provide for origin authentication and reply protection,
617 but which do not involve sending a password in the clear over the network.
618 A POP authorization DB,
619 having as its name the value of APOP configuration option,
620 is used to keep track of this information.
621 This file is created and manipulated by the \fIpopauth\fR\0(8) program.
622 Because this file contains secret information,
623 it must be protected mode 0600 and owned by the super-user.
625 your first step after installing the software is to issue
630 which creates and initalizes the POP authorization DB.
635 .fo '[mh.6]'MH.6.8'UCI version'
654 There was a time when users on a UNIX host might have had two maildrops:
655 one from \fIMMDF\fR and the other from \fIUUCP\fR.
656 This was really a bad problem since it prevented using a single
657 user\-interface on all of your mail.
659 if you wanted to send a message to addresses on different mailsystems,
660 you couldn't send just one message.
661 To solve all these problems,
662 the notion of \fImail filtering\fR was developed that allowed sophisticated
663 munging and relaying between the two pseudo\-domains.
665 \fIMH\fR will perform mail filtering, transparently, if given the MF
666 configuration option.
668 with the advent of \fISendMail\fR and further maturation of \fIMMDF\fR,
669 \fIMH\fR doesn't really need to do this anymore,
670 since these message transport agents handle it.
672 The mail\-filtering stuff is too complicated.
673 It should be simpler, but, protocol translation really \fIis\fR difficult.
678 .fo '[mh.6]'MH.6.8'UCI version'
693 Finally, here's a little information on modifying the \fIMH\fR sources.
694 A word of advice however:
700 If you really want new \fIMH\fR capabilities,
701 write a shell script instead.
703 that's what UNIX is all about, isn't it?
705 Here's the organization of the \fIMH\fR source tree.
709 .ta \w'miscellany/ 'u +\w'sendmail/ 'u
710 conf/ configurator tree
711 config/ compiled configuration constants
715 miscellany/ various sundries
716 mts/ MTS\-specific areas
717 mh/ standalone delivery
718 mmdf/ MMDF\-I, MMDF\-II
719 sendmail/ SendMail, SMTP
720 papers/ papers about \fIMH\fR
722 support/ support programs and files
723 bboards/ UCI BBoards facility
726 tma/ Trusted Mail Agent (not present in all distributions)
728 zotnet/ MTS\-independent areas
729 bboards/ UCI BBoards facility
740 .fo '[mh.6]'MH.6.8'UCI version'
752 .+c "HIDDEN FEATURES"
754 The capabilities discussed here should not be used on a production basis,
755 as they are either experimental, are useful for debugging \fIMH\fR, or
756 are otherwise not recommended.
758 .uh "Debug Facilities"
760 The \fImark\fR command has a `\-debug' switch which essentially prints out
761 all the internal \fIMH\fR data structures for the folder you're looking at.
763 The \fIpost\fR command has a `\-debug' switch which does everything but
764 actually post the message for you.
765 Instead of posting the draft, it sends it to the standard output.
767 \fIsend\fR has a `\-debug' switch which gets passed to \fIpost\fR.
769 Some \fIMH\fR commands look at envariables to determine debug\-mode operation
770 of certain new facilities.
771 The current list of envariables is:
775 .ta \w'MHLPOPDEBUG 'u
776 ^MHFDEBUG~^OVERHEAD facility
779 ^MHPOPDEBUG~^POP transactions
780 ^MHVDEBUG~^window management transactions
781 ^MHWDEBUG~^alternate\-mailboxes
786 .uh "Forwarding Mail"
788 The \fIforw\fR and \fImhl\fR commands have two switches,
789 `\-dashmunging' and `\-nodashmunging' which enable or disable
790 the prepending of `\-\ ' in forwarded messages. To use
791 `\-nodashmunging', you must use an \fImhl\fR filter file.
795 The \fIsend\fR command has two switches, `\-unique' and `\-nounique',
796 which are useful to certain individuals who, for obscure reasons,
797 do not use draft\-folders.
799 \*(lqDistribution Carbon Copy\*(rq addresses may be specified in
800 the \fIDcc:\fR header.
801 This header is removed before posting the message,and a copy of the message
802 is distributed to each listed address.
803 This could be considered a form of Blind
804 Carbon Copy which is best used for sending to an address which
805 would never reply (such as an auto\-archiver).
809 If you're running a version of \fIMH\fR which talks directly to an
810 \fISMTP\fR server (or perhaps an advanced \fIMMDF\fR submit process),
811 there are lots of interesting switches for your amusement which \fIsend\fR
812 and \fIpost\fR understand:
815 .ta \w'-server host 'u
816 ^-mail~^Use the \fIMAIL\fR command (default)
817 ^-saml~^Use the \fISAML\fR command
818 ^-send~^Use the \fISEND\fR command
819 ^-soml~^Use the \fISOML\fR command
820 ^-snoop~^Watch the \fISMTP\fR transaction
821 ^-client host~^Claim to be \*(lqhost\*(rq when posting mail
822 ^-server host~^Post mail with \*(lqhost\*(rq
827 The last switch is to be useful when \fIMH\fR resides on small
828 workstations (or PC:s) in a network\-\-they can post their outgoing mail with
830 and reduce the load on the local system.
832 the `\-server\ host' switch is defaulted appropriately using the SMTP
833 search\-list mechanism.
834 The \fIwhom\fR command understands the last three switches.
836 .+c "CONFIGURATION OPTIONS"
838 This manual was generated with the following configuration options in
844 .ta \w'BBoards Home Directory 'u
845 ^Generation Date~^\*(td
846 ^Primary Directory~^/opt/mh-6.8.5/bin/
847 ^Secondary Directory~^/opt/mh-6.8.5/lib/
848 ^Maildrop Location~^/var/spool/mail/$USER
849 ^Transport System~^SendMail \*(SM
854 .\" table of contents
864 .\" And now the COVER sheet
877 ADMINISTRATOR'S GUIDE
892 \s-2(Not to be confused with a well\-known soft drink)\s+2
projects / mmh / blob