\begindata{text,539047252} \textdsversion{12} \template{default} \define{global } \define{t } \define{footnote attr:[Flags OverBar Int Set] attr:[FontSize PreviousFontSize Point -2]} \chapter{Installing an AMS Bulletin Board System} \section{About AMS Bulletin Boards} The Andrew Message System is capable of integrating mail and bulletin board reading and storage into one system. A conceptual description of such a system is in the Bulletin Board overview and the Message Server document. There are a number of services associated with an AMS bulletin board system, some of which you may find useful, some of which you may not. They are described in the section on pobbconf.h, which is the file that is used to turn on various Bulletin Board services. \section{Non-AMS Bulletin Boards} If you want to set Messages up to read a non-AMS based bulletin board system, you can try using the experimental ".amsalien" mechanism. To do this, you put a file called ".amsalien" in the root of a AMS folder tree (i.e. in an MSPath element), then everything under that folder root will be considered to be non-AMS format. What this means, basically, is that there is no automatic generation of .MS_MsgDir files and no AMS-style file names. This mode is intended to make it possible to use AMS interfaces to read MH and netnews databases. It is still somewhat experimental, and neither widely-used nor well-tested. If you use something like a netnews database, you need to set up a "cui scavenge" daemon to periodically update the index files. \section{About this document} This document describes how to build and install an AMS based Bulletin Board System. It assumes that you are familiar with the concepts presented in the Bulletin Board and Message Server documents. This document is only one piece in the process of building a full-blown Andrew Message system from scratch; it assumes that you have already built the AMS user interfaces, the MessageServer, a Delivery System, and now want to add a bulletin board system. If you are using EZ to read this document, you can open an interactive Table of Contents window by choosing \bold{Table of Contents} from the \italic{Page} menu card. Clicking on a heading in the Table of Contents window that appears scrolls this document to bring the heading into view. \begindata{bp,539671048} \enddata{bp,539671048} \view{bpv,539671048,1469,0,0} \section{Instructions} This section is intended as a overview of the the tasks you will perform in the installation procedure. There is a more detailed discussion of the steps following this overview. The tasks should be performed in the order presented. \leftindent{Create and install an AMS MessagesDatabase "forest" for bulletin boards. This step entails created one or more .MESSAGES trees for bulletin board storage, and creating and installing the appropriate system files. Configure AMS software to recognize the message forest. Create and install the scripts that run on dedicated "Post Office" or "Bulletin Board" machines. These scripts drive the posting daemons, perform maintenance tasks on the bulletin board tree, and perform a number of tasks all related to maintaining a stable configuration on the local disks of the dedicated machines. This is done via the pobbconf mechanism.} \begindata{bp,539671752} \enddata{bp,539671752} \view{bpv,539671752,1470,0,0} \section{Prerequisites} In order to install a bulletin board system you need the following software and hardware. \subsection{Hardware} An AMS bulletin board system requires daemon processes to be running continuously. In a single-machine environment this setup can be achieved in any number of ways. In an AFS environment, the typical way to ensure that the daemon processes run is to dedicate some number of workstations to run them. A site's Bulletin Board machines must meet the following criteria: \leftindent{Every Bulletin Board machine must be a workstation type that supports AFS. All Bulletin Board machines must be listed in the IP host tables.} \subsection{Dedicated users} Because bboard processing runs continuously, you probably want to dedicate a userid to performing those tasks. \subsection{Software} As mentioned above, you need to have Andrew software installed and running. \subsection{Netnews} Netnews posts are stored on the local server disk for processing. Thus, it is necessary to allocate a sizable portion of space on the local disk. This can be a large directory, or a partition on the local disk. If you plan on receiving several netnews trees, it may be useful to dedicate an entire disk to netnews storage. There also needs to be a machine that you can poll to obtain netnews posts., and where outgoing posts from your site may be sent. This machine need not be at your site (and probably won't be). You should make arrangements with the mail administrator for the machine you want to poll before you start NNTP processing at your site. \begindata{bp,539690184} \enddata{bp,539690184} \view{bpv,539690184,1471,0,0} \section{Creating the Initial Message Database } AMS was designed so that a user's personal mail tree and a bulletin board tree are essentially identical. Both are rooted in a .MESSAGES subdirectory, containing message folders. Messages are delivered to a Mailbox, and are transferred from the Mailbox to the messages folders, where they can be read. The two main differences between a user's personal mail tree and a bulletin board tree is that a bulletin board tree is usually much bigger than a user's personal mail tree, and a bulletin board tree is usually publically readable. There are some special files associated with the bulletin board tree to allow easier, or quicker access, and to facilitate posting: \leftindent{.AMS.flames file - The .AMS.flames file is used to sort and process mail as it is moved from the user's Mailbox to his or her personal mail folders. Every bboard root must contain an .AMS.flames file. For instructions on how to create flames files consult the Flames Programmers Manual (Flames.pgr). .MS.DirectPost files - The .MS.DirectPost file serves two purposes. First, it allows users to post to bulletin boards by using the bulletin board name (foo.bar.baz form). Second it allows the administrator to control whether or not sub-bboards may be freely created. Every bboard root must contain at least one .MS.DirectPost file. .SubscriptionMap files - The .SubscriptionMap file is a list of every folder contained in a bulletin board tree. The .SubscriptionMap file for a tree is created automatically the first time a folder is created in that tree. Changed Subscription files - The changed subscription file is used by the messageserver to keep track of changes in the .SubscriptionMap files. When bboards are moved, or renamed, the changes are listed here. The next time a user tries to read the changed bboard he is prompted to change his subscription. Master Update files - The Master Update file facilitates checking for updates. It is not necessary to the operation of a bboard tree. However, if the bulletin board trees are large (more than about 15 branches), it is strongly advised that a Master Update file be created for that tree. .MS_intro.txt files - The .MS_intro.txt file provides a description of a particular bulletin board. It is not necessary, but can be nice to have. Each .MS_intro.txt is created by hand, and copied into the target directory. }\subsection{MS.DirectPost files} Each bulletin board tree must have an .MS.DirectPost file at its root. Other .MS.DirectPost files may be located in the branches of a bulletin board tree. There is no program that creates and installs an .MS.DirectPost file; they are written by hand, and copied into the target directory. Each .MS.DirectPost file consists of two lines. The first line always specifies whether or not users can freely create sub-bboards. It can also be used to determine whether the portion of the bboard tree above the.MS.DirectPost file is read-only, and whether the.MS.DirectPost file may be used for address validation of subfolders. The second line always contains a mailing address. When a user addresses a message using a bboard name, AMS uses the second line of the appropriate direct post file to try to form a valid mailing address for that message. For more information on writing .MS.DirectPost files, see the Bulletin Board Administration document. \subsection{The Master Update Mechanism } The Master Update file contains a list of each bboard in its tree. Each listing in the file has a timestamp that indicates when the bboard last received new messages. The AMS user interfaces use the Master Update file to determine whether or not a bboard has received new messages since the last time a user read bboards. When no Master Update file exists, the user interface must check each folder that the user is subscribed to to see whether there are new messages. For large bboard trees (more than 15 branches) this operation is costly in both time and resources. \begindata{bp,538930120} \enddata{bp,538930120} \view{bpv,538930120,1472,0,0} \section{Configuration} There are many things to be configured in the process of installing a bulletin board system. There are three broad configuration tasks to perform: defining variables to configure programs, selecting machine services in pobbconf.h, and supporting the service decisions in pobbconf.c. \subsection{Programs} There are several variables that relate to the way AMS programs interact with the Bulletin Board system. They are listed here in the following format: \italic{AndrewSetUpVariableName}: type \leftindent{Definition of the variable. Example: example Source Location: mailconf.c refers to the source directory andrew/overhead/mail/lib/mailconf.c Source Equivalent: variable name in mailconf.c} Each variable described below is one of the following data types: \bold{integer}, \bold{boolean}, \bold{string}, \bold{list-of-strings}. Booleans may be specified as yes/1/true, or no/0/false. Strings should be enclosed in quotation marks (""). Each element in a list-of-strings should be enclosed in quotation marks (""), and elements in a list should be separated by a comma. \paragraph{Basics} \italic{\index{LocalBboardRoot}}:string \leftindent{This variable specifies the pathname for the .MESSAGES root of the local bboard tree. Example: /afs/toaster.com/usr/bb/.MESSAGES Source Location :mailconf.c Source Equivalent:LOCALSEARCHPATHTEMPLATE} \italic{\index{ExternalBboardRoot}:} string \leftindent{This variable specifies the pathname for the .MESSAGES root of the external bboard tree. Example:/afs/toaster.com/usr/extbb/.MESSAGES Source Location:mailconf.c Source Equivalent:EXTERNALSEARCHPATHTEMPLATE } \italic{\index{OfficialBboardRoot}}: string \leftindent{This variables specifies the pathname for the .MESSAGES root of the official bboard tree. Example:/afs/toaster.com/usr/offbb/.MESSAGES Source Location:mailconf.c Source Equivalent:OFFICIALSEARCHPATHTEMPLATE} \italic{\index{DefaultMSPath}}: string \leftindent{This variable specifies the set of bboard roots that a user will be able to see, and the order in which these roots will be presented to the user. Users can override this with their *.mspath preference. Example:$MAIL:$OFFICIAL$:$LOCAL:$EXTERNAL Source Location: mailconf.c Source Equivalent:DEFAULTSEARCHPATHTEMPLATE } \italic{\index{RequiredSubsFile}}:string \leftindent{This variable specifies the pathname to a file that contains a list of bboards to which all users must subscribe. Example:/usr/local/lib/RequiredSubscriptions Source Location: mailconf.c Source Equivalent:GlobalRequiredSubsFile} \italic{\index{ChangedSubsFile}}: string \leftindent{This variables specifies the pathname to the file where changes to the location of bboards are listed. Example:/usr/postman/ChangedSubscriptions Source Location:mailconf.c Source Equivalent:GlobalChangeSubsFile }\paragraph{Netnews} If you are going to receive and send Netnews postings, you need to configure the following variables. \italic{\index{NNTPhost}}: string \leftindent{This variable specifies the fully qualified domain name of the machine that the NNTP polling daemon will poll for incoming netnews posts. Example : bboards.toaster.com Source Location : mailconf.c Source Equivalent : NNTPhost} \italic{ \index{NNTPuser}}: string \leftindent{This variable specifies the default poster of netnews for your site. Example : postmaster Source Location : mailconf.c Source Equivalent : NNTPuser} \italic{\index{Organization}}: string \leftindent{This variable specifies the string that will be inserted in the Organization header of outgoing netnews posts. Example : Toaster Corporation, Pittsburgh, PA Source Location : mailconf.c Source Equivalent : Organization}\italic{ } \italic{\index{nntpxmit}}: string \leftindent{This variable specifies the full path location of the nntpxmit program. Example : /afs/toaster.com/usr/toaster/etc/nntpxmit Source Location : mailconf.c Source Equivalent : nntpxmit} \subsection{pobbconf.h} The files in andrew/overhead/pobbconf provide an easy way to configure and maintain the scripts and files for the disk maintenance on the Post Office machines that AMDS relies heavily on to do its day-to-day operations. Maintaining the disks of the Post Office machines also requires scripts. For example, the package program determines what should be on the local disk by reading a package script. The large-grain decisions that define what types of services to be run are expressed by editing the pobbconf.h file and supporting decisions are made by editing pobbconf.c. All options in pobbconf.h are set to a value of TRUE or FALSE. Options whose value is TRUE will be defined during the installation process, while options whose value is FALSE will not be defined. The following options pertain to an AMS bulletin board system: \italic{\index{pobb_\index{AutoPost}}} \leftindent{Defining \italic{pobb_AutoPost} allows the installation of a bulletin board system. The system will process messages through the AMS delivery. }\italic{\index{pobb_NNTPIn }}\leftindent{Prerequisites: pobb_AutoPost TRUE Allows the processing of incoming netnews messages. Note that if you are going to do netnews processing you need to configure the AMS binaries to know where the processing programs are.} \italic{\index{pobb_NNTPOut}} \leftindent{Prerequisites: pobb_AutoPost TRUE Allows the processing of outgoing netnews messages. } \italic{\index{pobb_\index{UnDigest }}}\leftindent{Prerequisites: pobb_AutoPost TRUE Allows the "undigesting" mechanism to take effect. All mailing lists that are to be undigestified should be sent to the \italic{UnDigestUser}+\italic{foldername}, rather than to their former address.} \italic{\index{pobb_GetListOfLists}}: boolean \leftindent{Prerequisites: pobb_AutoPost TRUE Whether to retrieve the Arpanet List-of-lists periodically. } \italic{\index{pobb_TakeHelpStats}}: boolean \leftindent{Prerequisites: pobb_AutoPost TRUE Whether to probe for Help-system statistics. BBD, the maintenance script, weekly looks through /usr/*/help/HelpFlaws for "Missing" files that are placed there when users request help on a topic for which no file exists. The directory is cleaned out and results are mailed to bb+andrew.daemons.help@andrew.cmu.edu. } \italic{\index{pobb_CaptureAddresses}}: boolean \leftindent{Prerequisites: pobb_RunMachines TRUE Whether to capture From: addresses as they fly by. } \subsection{pobbconf.c} Site-dependent variables for scripts and other text files related to bulletin board systems and services defined in pobbconf.h are set in andrew/overhead/pobbconf/pobbconf.c. Each variable in pobbconf.c has a value of type \bold{integer}, \bold{string}, or \bold{list-of-strings}. Strings are enclosed in quotation marks (""). A list-of-strings is an array of strings. Each element in a list-of-strings, except the NULL element, should be enclosed in quotation marks (""). \paragraph{\index{AutoPost}} \italic{\index{PossibleBBs}}: list-of-strings \leftindent{This variable is the list of all machines that may, at some time, be used as Bulletin Board servers. All machines listed as \italic{PossibleBBs} must be listed in /etc/hosts.} \italic{\index{PossibleBBAddrs}}: list-of-strings \leftindent{This variable is the list of internet addresses for all \italic{PossibleBBs}. The order of addresses in this list should correspond to the order of machines in \italic{PossibleBBs}.} \italic{\index{PossibleBBCapas}}: list-of-strings \leftindent{This variable is the list of capability weighings for all \italic{PossibleBBs}. The capability weighings are used to determine what jobs are run on what Bulletin Board servers. The order of capabilities in the list should correspond to the order of machines in \italic{PossibleBBs}.} \italic{\index{PossibleBBHDSizes}}: list-of-strings \leftindent{This variable is a list of the hard drive sizes for all \italic{PossibleBBs}. The order of hard drive sizes in this list should correspond to the order of machines in \italic{PossibleBBs}.} \italic{\index{DeployedBBs}}: list-of-strings \leftindent{This variable is a list of all Bulletin Board servers that are actually deployed. This list is a subset of \italic{PossibleBBs}.} \italic{\index{NetBBUser}}: string \leftindent{This variable specifies the user id for the account where external (network) bulletin boards are delivered and stored.} \italic{\index{NetBBHome}}: string \leftindent{This variable specifies the full path location of \italic{NetBBUser}.} \italic{\index{CUIExtBoxes}}: string or list-of-strings \leftindent{This variable is the list of all Mailbox directories that are polled by the script msdaemon.extnonetnews. The msdaemon.extnonetnews script posts messages for all external bboards that are not Netnews bboards.} \italic{\index{CUILocalHighBoxes}}: string or list-of-strings \leftindent{This variable is the list of all Mailbox directories that are polled by the script msdaemon.localhigh. The msdaemon.localhigh script posts messages for most high volume local bulletin boards, and for local bulletin boards where posting may be time critical. } \italic{\index{CUILocalLowBoxes}}: string or list-of-strings \leftindent{This variable is the list of all Mailbox directories that are polled by the script msdaemon.locallow. This msdaemon.locallow script posts messages for most low volume local bulletin boards, and for local bulletin boards where posting is not time critical, (For example, an opinion bulletin board).} \italic{\index{ViceCUILogsDir}}: string \leftindent{This variable specifies the directory that is used for long-term storage of logs generated by the CUI posting daemons. } \italic{\index{BBDaemonDir}}: string \leftindent{This variable specifies the directory where BBD , a maintenance script, is stored.} \italic{\index{PostedVolumeRoots}}: list-of-strings \leftindent{This variable specifies the list of directories that are associated with the bulletin board volumes. These directories will be monitored by the \typewriter{bbquota} task of the BBD script.} \italic{\index{PurgingCommandsNightly}}: list-of-strings \leftindent{This variable specifies the list of directories on which old messages are to be deleted every night (with CUI's \typewriter{epoch} command), along with the age limit on messages in those directories. These old messages will be deleted by the \typewriter{nightpurge} task of the BBD script.} \italic{\index{PurgingCommandsWeekly}}: list-of-strings \leftindent{This variable specifies the list of directories on which old messages are to be deleted every week (in the wee hours of Friday morning, with CUI's \typewriter{epoch} command), along with the age limit on messages in those directories. These old messages will be deleted by the \typewriter{weekpurge} task of the BBD script.} \italic{\index{PurgingCommandsMonthly}}: list-of-strings \leftindent{This variable specifies the list of directories on which old messages are to be deleted every month (on the first day of the month, with CUI's \typewriter{epoch} command), along with the age limit on messages in those directories. These old messages will be deleted by the \typewriter{monthpurge} task of the BBD script.} \italic{\index{PurgingCommandsSemiAnnually}}: list-of-strings \leftindent{This variable specifies the list of directories on which old messages are to be deleted twice a year (on January 1 and July 1, with CUI's \typewriter{epoch} command), along with the age limit on messages in those directories. These old messages will be deleted by the \typewriter{semi-annualpurge} task of the BBD script.} \paragraph{\index{Netnews}} The variables described below are used to configure the scripts and daemons that processing incoming and outgoing netnews messages: \italic{\index{NNTPPollHome}}: string \leftindent{This variable specifies the full path location of the directory out of which the NNTP polling daemon runs. In particular, it specifies the home of the .AMS.flames file that will be used in processing those incoming netnews messages (with CUI) that ``nns'' is unable to handle.} \italic{\index{NNTPPollSleepTime}}: integer \leftindent{This variable specifies the length of time in seconds that the NNTP polling daemon will sleep between runs. } \italic{\index{NNTPGroups}}: list-of-strings \leftindent{This variables specifies the list of NNTP groups that the NNTP polling daemon will request from the polling host.} \italic{\index{NNTPDists}}: list-of-strings \leftindent{This variable specifies the distributions that the NNTP polling daemon will request from the polling host.} \italic{\index{NNTPKeepLen}}: string \leftindent{This variable specifies the length of time to keep entries in the duplicates database for NNTP messages. For example, to keep entries for 5 days, the value of \italic{NNTPKeepLen} would be 5d. } \italic{\index{NetDatabaseRoot}}: string \leftindent{This variable specifies the full path name of the directory on the local server disk where incoming netnews posts are stored for processing.} \italic{\index{CUINNSleepTime}}: integer \leftindent{This variable specifies the length of time that the netnews-processing daemon (usually post-netnews) sleeps between runs.} \italic{\index{CUINetnewsBoxes}}: list-of-strings \leftindent{This variable specifies the list of directories that the netnews posting daemon should process.} \italic{\index{PostedNetnewsRoot}} : string \leftindent{This variable specifies the full path location of the root of the netnews bboard tree. The folders for all netnews distribution groups (such as alt or rec) are subdirectories of this root. } \italic{\index{NetnewsRoot}}: string \leftindent{This variable specifies the name of the message folder that is at the root of the netnews bboard tree.} \italic{\index{PostedNetnewsVolRoots}}: list-of-strings \leftindent{This variable specifies the list of directories in the netnews bboard tree in which the AFS volumes that contain the various trees are mounted.} \italic{\index{OutnewsID}}: string \leftindent{This variable specifies the user id of the account where outgoing netnews messages are sent for processing. } \italic{\index{OutnewsHome}}: string \leftindent{This variable specifies the full path location for \italic{OutnewsID}.} \paragraph{\index{Undigest}} \italic{\index{UnDigestUser}}: string \leftindent{This variable specifies the login-id for the account where digested bulletin boards are processed, and where the undigested messages are written for posting. This should NOT be the same account that receives digested bulletin boards that you do not intend to undigest. } \italic{\index{UnDigestHome}}: string \leftindent{This variable specifies the full path location for \italic{UnDigestUser}.} \italic{\index{UnDigestSleepTime}}: integer \leftindent{This variable specifies the length of time in seconds that the undigest daemon sleeps between runs. }\paragraph{\index{Take Help Stats}} \italic{\index{BBDHelpPrefix}}: string \leftindent{default: "/afs/andrew.cmu.edu/common/usr" Prerequisites: pobb_RunMachines TRUE, pobb_TakeHelpStats TRUE} \italic{\index{BBDHelpSuffix}}: string \leftindent{default: "help/HelpFlaws" Prerequisites: pobb_RunMachines TRUE, pobb_TakeHelpStats TRUE} \paragraph{\index{Capture Addresses}} \italic{\index{AFSCaptureProcess}}: string \leftindent{default: "/afs/andrew.cmu.edu/usr0/postman" Prerequisites: pobb_CaptureAddresses TRUE Under which captured addresses are gathered and processed.} \italic{\index{CaptureLifetime}}: integer \leftindent{default: 100 * 24 * 60 * 60 Prerequisites: pobb_CaptureAddresses TRUE How many seconds to keep addresses.} \subsection{Installation} \paragraph{\index{pobbconf make install}} Once the appropriate variables have been set in pobbconf.h and pobbconf.c, the scripts and files in the pobbconf directory can be built and installed. To do this, type: \typewriter{make install} in andrew/overhead/pobbconfig. The "make install" command will build the \index{pobbscpt} macro processor, make all the target *.msh and *.csh files by running them through that processor, and then execute the generated pobb-install.msh script, which will check for the existence of target directories, and create any that do not already exist, and, finally, install the compiled scripts into the target directories. \paragraph{\index{PackageHome make install}} Performing a "make install" in andrew/overhead/pobbconf does not create complete \index{package} scripts for the machines. Instead, it creates source files for these package scripts, which then need to be compiled to create the completed package scripts. To compile and install the package scripts for the bulletin board servers, move to \italic{PackageHome}/src, and type: \typewriter{make install} This command builds the \index{package} scripts for the machines from the script sources, checks for the appropriate target directories and creates any that do not already exist, and installs the completed scripts in the appropriate directories. \paragraph{Reboot} You should make sure the machines reboot and re-package correctly. This means that the file /.package must point to the appropriate package file for that machine. The text of this file should be the line \italic{PackageHome}/etc/\italic{hostname}, where \italic{hostname} is the fully qualified domain name of the machine. \paragraph{Files on the local machines} To allow the daemon processes to authenticate, the following file must be written: \leftindent{ The file \italic{WPPasswordFile} must contain the unencrypted password for \italic{PostmasterName}. } \paragraph{Reboot} When this file has been installed on the local disk of each machine, the machines should be rebooted. As each one comes up, the appropriate daemons should be running. \begindata{bp,537558784} \enddata{bp,537558784} \view{bpv,537558784,1474,0,0} Copyright 1992 Carnegie Mellon University and IBM. All rights reserved. \smaller{\smaller{$Disclaimer: Permission to use, copy, modify, and distribute this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice, this permission notice, and the following disclaimer appear in supporting documentation, and that the names of IBM, Carnegie Mellon University, and other copyright holders, not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. $ }}\enddata{text,539047252}