⟦7f3bf6c81⟧

TextFile

\chapter {Installing PP}

This is a description of things to do when installing PP. The basic
information is described in \man pp-gen(8), but this section gives the
full details. It is recommended that you read this section before
compiling or installing the software.

\section {Compile Time Configuration}

Most of the definitions that have to be set before compiling PP are
given in \file{Make.defs} in the top level of the source tree, and
\file{config.h} in the \verb+h/+ directory.

\subsection {Make.defs}\label{Make.defs}

A number of \pgm{make} variables can be set. These variables come
in two classes. The first are variables that are truly site
specific. These are listed in Table~\ref{tab:makedefs1}. The second
class are variables that you can probably leave as the defaults.
These are listed in Table~\ref{tab:makedefs2}.  For each entry a
reasonable default is given.

\tagtable[hbpt]{makedefs1}{Make Variables that should be set}{tab:makedefs1}

\tagtable[hbpt]{makedefs2}{Make Variables that can be defaulted}{tab:makedefs2}

A number of these variables are important, so care must be taken when
configuring these variables. A description of each of these variables
is now given, however Table
\ref{tab:makedefs1}~and~\ref{tab:makedefs2} give a good overview of
the variables.

\begin{describe}
\item[\verb|CMDDIR|:]\index{CMDDIR} This is the directory into which
most of the PP core commands are placed. This is usually the directory
that contains subdirectories for channel and formatting programs.

\item[\verb|CHANDIR|:]\index{CHANDIR} This directory is normally a
sub-directory of \verb|CMDDIR|. It contains all the channel programs
that PP knows about.

\item[\verb|FORMDIR|:]\index{FORMDIR} This directory contains the
formatting programs that are run by \pgm{filtercontrol}. These are
either binary executables or shell scripts.

\item[\verb|TOOLDIR|:]\index{TOOLDIR} This directory is where a number
of miscellaneous tools are placed. These are useful programs that aid
in the day to day running of PP but are not usually used by the PP
system.

\item[\verb|LOGDIR|:]\index{LOGDIR} This directory is where the
logging files are written to by default. These logs are used for a
variety of purposes, including debugging and statistics gathering. You
should allow for a reasonable amount of space.

\item[\verb|TAILOR|:]\index{TAILOR} This specifies the location of
the PP tailor file. It is important you get this right. Almost
everything PP variable can be changed in the PP tailor file, but
obviously the location of the PP tailor cannot. If you get this wrong,
you will need to relink all the PP binaries.

\item[\verb|QUEDIR|:]\index{QUEDIR} This is the directory under which
the PP queue is maintained. As all messages sent are queued here, you
should allow enough room to handle all the mail you are likely to
receive. A busy site with just a day or two's network outage can
gather several megabytes of mail.

\item[\verb|TBLDIR|:]\index{TBLDIR} This is the directory in which all
the PP routing tables and similar configuration files are kept.

\item[\verb|LIBSYS|:]\index{LIBSYS} This variable contains all the
external libraries that you may require when building most of the PP
binaries. It should contain at least the \verb|ISODE| library and
possibly other libraries such as the \man dbm(3) library and any
machine specific libraries you may need.

\item[\verb|LIBRESOLV|:]\index{LIBRESOLV} This variable contains the
library for the bind domain name server (or equivalent). It is only
required if you are making use of the DNS (see section~\ref{config.h}).
Leave it empty otherwise.

\item[\verb|USRBINDIR|:]\index{USRBINDIR} This is a directory where
binaries that are used by users are placed. This includes a simple
mail interface, and some delivery time processors.

\item[\verb|OPTIONALCHANS|:]\index{OPTIONALCHANS}
PP requires a certain core set of channels to operate at all, plus a
number which are used in all normal configurations. However there are
a number of protocol and experimental channels which can be included
if required. This variable specifys
which of the optional channels and protocols you wish to support.
Currently this consists of a list made from the following.
\begin{describe}
\item[\verb|822-local|:]	Basic RFC-822 delivery
\item[\verb|list|:]	Support for distribution lists.
\item[\verb|grey|:]	Support for JNT Mail protocol (Grey book).
\item[\verb|shell|:]	Support for delivery to programs.
\item[\verb|slocal|:]	Support for structured local delivery (experimental).
\item[\verb|smtp|:]	Support for the SMTP protocol.
\item[\verb|uucp|:]	Support for the UUCP protocols (primitive).
\item[\verb|x40084|:]	Support for the X.400 P1(1984) protocol.
\item[\verb|x40088|:]	Support for the X.400 P1(1988) protocol.
\item[\verb|dirlist|:]	Experimental X.500 distribution list channel.
\end{describe}

\item[\verb|MANDIR|:]\index{MANDIR} This is the directory under which
manual pages are placed. The installation process understands about
most layouts of manual pages, so this is usually a base directory.

\item[\verb|MANOPTS|:]\index{MANOPTS} This variable configures the
style of manual pages to be installed. It can take the following
values:
\[\begin{tabular}{|l | l|}
\hline
	\multicolumn{1}{|c|}{\bf Option} & 
		\multicolumn{1}{|c|}{\bf Format}\\
\hline
	\tt -bsd42 & man$<$N$>$/file \\
	\tt -bsd44 & cat$<$N$>$/file.O \\
	\tt -ros & man$<$N$>$/file -- using /etc/install\\
	\tt -sys5 & $<$a\verb+|+p\verb+|+u$>$\_man/man$<$N$>$/file\\
	\tt -local & manl/file.l\\
	\tt -l & man$<$N$>$/file.$<$N$>$l\\
	\tt -hpux & HP manual style\\
\hline
\end{tabular}\]

\item[\verb|NIFTPSRC|/\verb|NIFTPINTERFACE|:] These two variables
control the PP interfacing with the unix-niftp code. These variables
are ignored unless grey book mail is being installed. The variables
should be set to the source directory of the unix-niftp package, and
the particular interface the grey book channel will use. Suitable
interface settings include:
\begin{itemize}
\item sun
\item inet
\item ubc
\item dexpand
\item x25b
\item yorkbox
\end{itemize}


\item[\verb|CC|:]\index{CC} The C compiler to use. The PP system has been
compiled with a number of C compilers. 

{\bf Warning: } If you wish to use the \pgm{gcc} compiler on
\verb|sparc| based system, you must compile files making use of dbm
style routines with \pgm{cc}.  (The compiler will normally warn about
these files).

\item[\verb|CCOPTIONS|:]\index{CCOPTIONS} This contains global C
compiler options. If your include files for \verb|ISODE| are in a non
standard place, a ``\verb|-I|'' flag or two may be necessary here.

\item[\verb|LIBCCOPTIONS|:]\index{LIBCCOPTIONS} This contains global C
compiler options to use when compiling files to place in libraries. In
normal use this will be the same as \verb|CCOPTIONS|.

\item[\verb|LDOPTIONS|:]\index{LDOPTIONS} This variable contains
global loader flags. It is normally empty or just contains the
``\verb|-s|'' flag.

\item[\verb|PEPY|/\verb|POSY|/\verb|ROSY|:]\index{ROSY} \index{POSY}
\index{PEPY} These variables are the
\prm{pepy}, \pgm{posy} and \pgm{rosy} programs. Normally they just
contain those names, but may be full pathnames if they are not in the
standard search path.

\item[\verb|X11|:]\index{X11} If you have X11 then set this variable
to true. Leave it empty and no X-based programs will be used.

\item[\verb|LIBX|:]\index{LIBX} The X11 libraries. This contains a
list of the X libraries necessary to compile the few X based programs
in the distribution. This distribution is aligned to the X11R4
release, it will {\em not} run under earlier versions of X.

\item[\verb|LINT|:]\index{LINT} The man lint(1) command. This is not
normally used unless you are doing development work.

\item[\verb|LINTFLAGS|:]\index{LINTFLAGS} A list of global lint flags.

\item[\verb|PGMPROT|:]\index{PGMPROT} This is the default mode to
install programs as. Some programs need special modes, but these are
handled separately.

\item[\verb|PPUSER|:]\index{PPUSER} This is the username that most PP
programs are installed under. It is usually \verb|pp|, but need not
be.

\item[\verb|ROOTUSER|:]\index{ROOTUSER} The super user.

\item[\verb|CHOWN|:]\index{CHOWN} The \man chown(8) program. This may
need to be a full pathname.

\item[\verb|CHMOD|:]\index{CHMOD} The \man chmod(1) program. This is
normally ok as just \verb|chmod|.

\item[\verb|BACKUP|:]\index{BACKUP} When PP installs a program, it
normally takes a copy of the existing program for safety. If you wish
this behaviour then you should set this variable to \man cp(1). If
not, setting it to something harmless like ``\verb|:|'' or \man echo(1)
will disable this action.

\item[\verb|INSTALL|:]\index{INSTALL} The command used to install a
new binary. This is normally either \man cp(1) or \man install(1).
\end{describe}

\subsection {h/config.h}\label{config.h}

The only other tailoring that should be done before compiling is
setting of \verb+#define+s in the file \file{h/config.h}. These affect the
more global options and there are very few of these.

\begin{describe}
\item[\verb+DBM+/\verb+NDBM+:] One of these values must be defined.
It is {\em STRONGLY} advised that you use \man ndbm (3) if you have it
at all, the \man dbm(3) routines can create havoc if you are using
another package that uses dbm too.  If you are certain you don't have
\man ndbm(3) then use \man dbm(3) and add \verb+-ldbm+ to your
\verb+LIBSYS+ make variable.

\item[\verb+PP\_DEBUG+:] This variable should be set to one of the following:-
\[\begin{tabular}{|l | l|}
\hline
	\multicolumn{1}{|c|}{\bf Level} & \multicolumn{1}{|c|}{\bf Meaning}\\
\hline
	\tt PP\_DEBUG\_ALL&	Include all debugging code\\
	\tt PP\_DEBUG\_SOME&	Include basic debugging code\\
	\tt PP\_DEBUG\_NONE&	Don't include any debugging code\\
\hline
\end{tabular}\]

\item[\verb+NAMESERVER+:] If you wish to make use of the BIND
nameserver for the SMTP channels you should define this.
\end{describe}

\section {Overview of channels}

This is a brief overview of the channels distributed with PP.
The binaries of these channels are installed in the \file{CHANDIR}
directory.

\subsection {Mandatory channels}

The channels under this section must be installed with all
configurations of PP.
They are mostly ``housekeeping'' channels used by the \pgm{qmgr}

\subsubsection	{qmgrload}

The \pgm{qmgr} maintains its own model of the queue, separate to the
master model stored under the \file{quedir} directory.
The \pgm{qmgrload} channel is used to initialise the \pgm{qmgr}'s model
when the \pgm{qmgr} starts up. 
When running, the \pgm{qmgr} periodically uses \prm{qmgrload} to check the
consistency between 
its model and reality.

\subsubsection	{msg-clean}

After all work has been done on a message and that message is no
longer of interest to PP, the \pgm{qmgr} removes the message from the
\file{quedir} directory via the \pgm{delete} channel.

\subsubsection	{trash}

From time to time, the \pgm{qmgr} invokes the \pgm{trash} channel.
This channel hunts around the \file{quedir} directory for files and
directories that are no longer of interest to PP and removes them.

\subsubsection	{timeout}

When a message has been in the queue for too long, the \pgm{qmgr} uses
the \pgm{timeout} channel to send a message back to it's originator,
telling him or her that PP timed out the original message.

\subsubsection {dr2rfc}

The \pgm{dr2rfc} channel constructs delivery receipt notifications or
error messages and then submits them to the \pgm{qmgr} for return to
the sender.

\subsection {Optional channels}

The channels under this section are optional.  To see how they are
combined to produce various configurations see
section~\ref{sect:example_configs}.

\subsubsection {822-local}

The \pgm{822-local} channel is used to deliver messages to local users.
It can deliver in a number of formats. For more details see
Section~\ref{sect:local} on page~\pageref{sect:local} and also {\em The
PP Manual: Volume~3 -- Users Guide}.

\subsubsection {slocal}

The \pgm{slocal} - structured local - channel should be used if local
users are to receive structured messages, that is, if the MTA is to
deliver messages made up of different parts, such as multi-media
messages, which cannot be appended to a single file but which must be
delivered as a directory of files.  The \file{users} table will
indicate, for each user, whether \pgm{slocal} is an optional channel.

\[\fbox{
\begin{tabular}{l p{0.7\textwidth}}
\bf NOTE: & This channel is still experimental and not designed for an
operational configuration.
\end{tabular}
}\]

\subsubsection {X400-84}

Inbound and outbound channels for handing X.400 P1(1984) messages are
available. The channels will run over any media that ISODE can support
transport connections on.

\subsubsection {X400-88}

Inbound and outbound channels for handing X.400 P1(1988) messages are
available. The channels will run over any media that ISODE can support
transport connections on. This software should be considered as {\em
beta test} software in the current release.

\subsubsection {SMTP}

An \pgm{smtp} channel is available for use over TCP/IP. It may be used
over networks such as a local Ethernet or WAN such as the DARPA
Internet.

\subsubsection {JNT Mail}
The JNT mail channel is used over X.25 networks, particularly in the U.K.
The unix-niftp package is used to provide the blue book file transfer
part of this.

\subsubsection{UUCP}
A channel that will interface with the UUCP protocols.

\[\fbox{
\begin{tabular}{l p{0.7\textwidth}}
\bf NOTE: & This channel has not been used very much. It is still
rather unstable as the development sites use UUCP traffic very little.
You have been warned!
\end{tabular}
}\]


\subsubsection	{p2explode}

The \pgm{p2explode} channel is a restructuring channel that is used to
explode a general p2 message into its separate component bodyparts. 
Note the same binary can explode p2 (1984) and p22 (1988).
It is used on an incoming x400 message when the mta needs to manipulate the
separate components of that message.  

\subsubsection 	{p2flatten}

The \pgm{p2flatten} channel is a restructuring channel that is used to
combine all the separate components of a message into one p2 file.  It
is the exact inverse of \pgm{p2explode}.

\subsubsection {P2toRFC}

The \pgm{P2toRFC} channel is a reformating channel that is used to
convert an X.400 style header encoded in \verb+p2 (1984)+ or \verb+p2
(1988)+ to an RFC
822 style header.  This conversion is performed according to RFC
1148\cite{RFC1148} .

\subsubsection {RFCtoP2}

The \pgm{RFCtoP2} channel is a reformating channel that is used to
convert an RFC 822 style header to an X.400 style header encoded in
\verb+p2 (1984)+ or \verb+p2 (1988)+.
This conversion is done as described in RFC 1148.

\subsubsection {rfc934}

The \pgm{rfc934} channel flattens an RFC 822 style message which may
contain forwarded messages, into a flat RFC 822 message.  The
flattening is done as described in RFC 934\cite{RFC934}. 

\subsubsection {list}

The \pgm{list} channel expands a distribution list into its component
members. The original message is then sent to each of these members.
The channel uses the associated \file{list} table as described in
section~\ref{sect:list} on page~\pageref{sect:list}.

\subsubsection {dirlist}
The \pgm{dirlist} channel expands a distribution list into its
component members. However, this list channel makes use of the X.500
directory to retrieve the members of the list. This channel is
experimental in this version of PP.

\subsubsection {shell}

The \pgm{shell} channel runs a specific process for the originator of
the message. This allows delivery of a message to a special process
rather than to a user.  The mapping from the address the message is
sent to and the process to run is described by the \file{shell} table,
see section~\ref{sect:shell} on page~\pageref{sect:shell}.

\subsubsection {fcontrol}

The \pgm{fcontrol} channel is used to run various filters on the
bodyparts of the message.
These filters can only affect the contents of the bodyparts and cannot
affect the overall structure of the message.
The filters are usually installed in the \file{FORMDIR} directory.

Here is a brief description of the filters distributed with PP:
\begin{describe}
\item[\verb+rfc822norm+:] The filter is used for conversion between various
styles of RFC 822 headers.
\item[\verb+removebp+:] The filter is used to replace bodyparts that
the MTA cannot support with a simple text message reflecting this fact.
\end{describe}

\section {Example Configurations}\label{sect:example_configs}

This section gives some details about the example configurations
included in the distribution. These configurations should be looked on
as a sample first step to allow a working system to be installed
easily. This should then be evolved to meet local requirements.
To use one of these configurations, do the following.
\begin{enumerate}
\item Change to the \file{examples} directory.
\item Select one of the co0nfigurations shown below, and change into
that directory.
\item read the \file{README} file, and carry out the instrcutions
given in there.
\end{enumerate}

This should give you a very basic working system.

\subsubsection{Local SMTP}
This configuration assumes a simple host doing local deliveries and
passing all other messages to another host. It requires the \pgm{smtp}
channel, the \pgm{822-local} channel and optionally the \pgm{list}
channel.

\subsubsection {SMTP mail}
This configuration assumes a simple host doing SMTP relaying and local
delivery only. It is similar to the above, but can handle Internet
connectivity by use of the domain nameserver.

\subsubsection {JANET mail}
This host is assumed to be on the JANET network and has local smtp
capability. It is a skeleton only as for proper operation NRS data is
necessary to identify the necessary domain and routes.

\section {Configuration of User Agents}

PP is a Message Transport Agent, and does not contain a sophisticated
X.400 user agent. It is hoped that the interface documented in Volume
2 will be useful in the development of new user agents or the
interfacing of existing UA's. The latter should be straightforward
for most RFC 822 based interfaces.

MH\cite{MH6.5} can be used directly
with PP if compiled with the SMTP
transfer interface.

PP provides a \pgm{/bin/mail} emulation. This should be installed in
the normal installation. Also provided is a \man sendmail(8) emulation
program that can be used to intercept those programs that insist on
calling sendmail directly (e.g. \man cron(8)).

\section {Checking the configuration of your system}

Following installation, it is {\em strongly} recommended to use \man
ckconfig (8) to ensure that the PP directory structure is correct and
all the channel programs are correctly in place.
\pgm{ckconfig} is described in section~\ref{sect:ckconfig}.
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦7f3bf6c81⟧ TextFile

Derivation

TextFile
