⟦04254838e⟧

TextFile

\chapter {Configuring PP}\label{tailoring}

This chapter is principally concerned with the \file{tailor} file and
how it is configured.  The \file{tailor} file contains the runtime MTA
configuration information.  This chapter describes how to construct
this information.

The information in the \file{tailor} may duplicate that in the
\file{Make.defs} in some cases. In these cases, the tailor file
settings will override the \file{Make.defs} settings. 

There are four basic types of entries in the \file{tailor} file
\begin{itemize}
\item	variable entries,
\item	logging entries,
\item	table entries,
\item	and channel entries.
\end{itemize}
The following sections describe how to construct these entries.
Appendix~\ref{app:tailor} contains a complete example \file{tailor} file.

Since the construction of the information is complex, it is {\em
strongly } recommended to use \man ckconfig (8).
\pgm{ckconfig} applies several sanity checks to the information
contained in the \file{tailor} file and generally ensures that the
information represents a logically correct configuration.
\pgm{ckconfig} is described in section~\ref{sect:ckconfig}.

\section	{The general syntax of tailor file entries.}

A comment starts with an unescaped hash (\#) and finishes at the end
of the line.  Other lines are split into components separated by white
space or commas (or both). A line may be extended onto the next line
by starting that next line with some white space. A field may be enclosed
by quote marks (\verb+"<field>"+); this disables special characters such as
field delimiters.

\section	{Variable Tailor File Entries.}\index{tailoring, variables}

Variable entries take the form of a keyword and its value, 
separated by white
space. Each key/value pair should be on a separate line and start in
the first column. For example:
\begin{quote}\small\begin{verbatim}
cmddir   /usr/pp/cmds
tbldir   /usr/pp/tables
\end{verbatim}\end{quote}

There are a finite number of tailoring variables that can be
referenced in the tailor file.
These tailoring variables are divided into two types, mandatory
tailoring variables and
optional tailoring variables.
They are listed and described in the sections below.

\subsection{Mandatory tailoring variables}\index{tailoring, simple}
The following tailoring variables {\em must} be included in the tailor file.

\begin{description}
\item[\verb+cmddir+:]\index{cmddir}
This is a directory and is the default place to find all the main PP
commands. It should be a fully qualified pathname - i.e. starting with
a forward slash.

\item[\verb+tbldir+:]\index{tbldir}
This is the directory where all the table files are located and should
be a fully qualified pathname; it is used by
\verb+dbmbuild+\index{dbmbuild} to generate the hashed database and
for address lookups when tables are defined in
\verb+linear+\index{linear} mode.

\item[\verb+quedir+:]\index{quedir}
This is the base directory for the PP queue. It should be a fully qualified
pathname.

\item[\verb+logdir+:]\index{logdir}
This is the directory where log files will be written in by default.

\item[\verb+loc\_dom\_mta+:]\index{loc\_dom\_mta}
This is the full domain name of the local mta. 
It is used for trapping routing loops and so should be globally unique.
For example \verb+sheriff.cs.nott.ac.uk+.

\item[\verb+loc\_dom\_site+:]\index{loc\_dom\_site}
This is the full domain name of the local site. This is used to reference the
site, and may refer to a group of MTAs collectively. For example
\verb+cs.nott.ac.uk+.

\item[\verb+loc\_or+:]\index{loc\_or}
This is the local O/R address defaults given in X.400 RFC1148 encoding form.
For example:
\begin{quote}\begin{verbatim}
"/OU=CS/O=NOTT/PRMD=UK.AC/ADMD=GOLD 400/C=GB/"
\end{verbatim}\end{quote}
Note: If the name contains spaces or other special characters, it must
be quoted as above.

\item[\verb+qmgrhost+]\index{qmgrhost}
This is the name of the machine on which the
\pgm{qmgr} is running.
For example, you could give the output of \man hostname (1) here.

\item[\verb+postmaster+:]\index{postmaster}
This is the address of the local mail system administrator.
Typically of the form:
\verb+Postmaster <postmaster@cs.nott.ac.uk>+.

\item[\verb+bodypart+:]\index{bodypart}\label{tai:bodypart}
This is a list of bodyparts that are recognised by the system. This
line may occur several times in the tailor file, each time appending
its arguments to the list of body parts.

\end{description}

\subsection{Optional tailoring variables}

The tailoring variables in this section are less critical, having
defaults that are normally suitable.

\begin{description}

\item[\verb+pptsapd\_addr+:]\index{pptaspd\_addr}
This is the address that the \pgm{pptsapd} listens on for incoming
connections.  For example the \pgm{qmgr} uses it to connect to channel
processes.  The default value is: \verb%Internet=localhost+20001%.
This indicates that processes can communicate with the \pgm{pptsapd}
daemon via a TCP/IP connection to the local machine on Port 20001.
The address could just as easily be a remote machine name specifying
an X25 address or a real NSAP.

\item[\verb+chandir+:]\index{chandir}
This is the directory where the executable channel programs are found.
It defaults to a directory called \file{chans}
within the \file{cmddir}.
When defined, if it is a relative name, i.e. not starting with a forward 
slash, then it will be assumed to be a sub-directory of the \file{cmddir}.

\item[\verb+formdir+:]\index{formdir}
This is the directory where the simple programs run by the
\pgm{fcontrol} are found. Not usually tailored, it defaults to being
the same as \file{chandir}.  When it is defined, it is taken as
relative to the \file{cmddir} unless a full pathname is given.

\item[\verb+dbm+:]\index{dbm}
This is the name of PP database. It is assumed to be
relative to the \file{tbldir} directory unless a full pathname is
given. The default is \file{ppdbm}. 

\item[\verb+pplogin+:]\index{pplogin}
This is the user id that most of the PP programs will run under. It
defaults to \pgm{pp} and in any case should be a username found in the
\file{/etc/passwd} file.

\item[\verb+mboxname+:]\index{mboxname, mailbox, maildrop}
This is the maildrop file used by the 822-local delivery channel for
delivering local messages into users' home directories.  The default
is \file{.mail}.

\item[\verb+mailfilter+:]\index{mailfilter}
This is the mailfilter file used by the 822-local delivery channel
(see {\em The PP Manual: Volume~3 -- Users Guide}).
The default is \file{.mailfilter}.

\item[\verb+sysmailfilter+:]\index{sysmailfilter}
This is the mailfilter file the 822-local delivery channel uses if the
user does not have one.
The default is \file{/usr/local/lib/mailfilter}.

\item[\verb+delim1+:]\index{delimiters}\index{mailbox}\index{maildrop}
\index{delim1}
This is the message delimiter appended to the maildrop file before
each message.  The default is \verb+"\001\001\001\001\012"+ i.e. four
control-A's and a newline. (Beware, the {\em C} syntax \verb+\n+ does not work (yet)).

\item[\verb+delim2+:]\index{delim2}
This is the message delimiter appended to the maildrop file after
each message.  The default is
\verb+"\001\001\001\001\012"+ i.e. four control-A's and a newline.

\item[\verb+isode+:]\index{isode}
This variable allows the tailoring of any ISODE parameter specified in
the {\man isotailor(5)} file. However -- the ISODE logging levels are
better handled by the \verb+isodelogs+ tailor line.

\item[\verb+authchannel+:]\index{authchannel}
This gives the default policy for channel authorisation -- it is 
in the form of a \file{channel-auth} record (see
section~\ref{sect:auth}). 
The default is
\verb+block+.  This determines the policy for any inbound/outbound
channel pairing not explicitly entered in the channel authorisation
table \file{channel-auth}.

\item[\verb+authloglevel+:]\index{authloglevel}
This sets the level of authorisation logging.  Three levels are defined :

\begin{describe}
\item[\verb+low+:]
One line of statistical information is generated for each recipient, giving
the outbound channel if authorisation succeeds, or the first ( of possibly
several ) channels to be tested which failed.  ( It is anticipated that the
tables will be configured so that channels will be tested in order of ascending
\`cost\'.)

\item[\verb+medium+:]
One line is generated for each potential output channel which fails 
authorisation tests in the cases where no successful channel is found, but only
a single line where authorisation is successful for that recipient.

\item[\verb+high+:]
As for \verb+medium+, but a line is produced for every channel which fails 
authorisation tests, whether or not the recipient is ultimately successful.
\end{describe}

The default is \verb+low+.

\item[\verb+wrndfldir+:]\index{wrndfldir}
This is a directory to hold warning message files which can be
sent automatically to sender or recipients when authorisation fails.
It may be a fully qualified pathname starting with \verb+"/"+, or else
is taken relative to the table directory \verb+tbldfldir+.

The default is \verb+warnings+.

Note: Warnings are not used in this release.

\item[\verb+warninterval+:]\index{warninterval}
This is the time in hours after which to send a warning to the sender
of the message telling him or her that the message is stuck in the MTA.

The default is one day.

Note: Warnings are not used in this release.

\item[\verb+nwarnings+:]\index{nwarnings}
This is the maximum number of warnings to send.

The default is two warnings.

Note: Warnings are not used in this release.

\item[\verb+returntime+:]\index{returntime}
This is the time in hours after which to expire an undelivered
message.  By default, this time is doubled for low priority messages
and halved for high priority messages. However, these other values can
be overriden by specifying two other times in hours after the normal
return time. The first or these being the return time for high
priority messages and the second for low priority messages.

The default normal time out is three days giving about a day for high
priority messages and just less than a week for low priority messages.
Messages that pass through the list channel are set to low priority.

\item[\verb+lockstyle+:]\index{lockstyle}
This is the style of locking to be used when it is necessary to lock a file.
It may be one of the following:

\[\begin{tabular}{| l | l |}
\hline
	\multicolumn{1}{|c|}{\bf Value} &
		\multicolumn{1}{|c|}{\bf Meaning} \\
\hline\hline
	\tt flock&	Use the \man flock (2) system call. \\
	\tt fcntl&	Use the \man fcntl (2) system call. \\
	\tt file&	Use lock files that are created and removed\\
	\tt lockf&	Use the \man lockf (3) library call \\
\hline
\end{tabular}\]

The default style is \verb+flock+ but may be changed if you have
doubts about the interaction of \man flock (2) and nfs.
This is a run time configuration variable, and it will depend on what
platform you are running as to whether all the above will be
supported. The file locking mechanism will always be available though.

\item[\verb+lockdir+:]	If the \verb+file+ style of locking is to be
used, this is the directory to create the files in. It defaults to
\file{/tmp} and should be cleaned out at reboot time. It is ignored
otherwise.
\end{description}

\section{Logging Tailor File Entries.}\index{tailoring, logs}
This section describes how to tailor the logging produced by PP.

There are four main groups of logging, covering normal events, unusual
operational events, authorisation, and ISODE.  By default, each group
will describe in a single file, the appropriate activities of all the
programs that provide logs.  However the tailor file may be used to
separate out logging on a per-program or per-channel basis.  Thus, for
example, all normal activities may be logged in one file, except
submit which may be logged in a different file, and at a different
level.

All logging entries are comprised of a standard set of 
key/value pairs, described below. 
 
\begin{describe}
\item[\verb+file=xxx+:]\index{log, file}
Set the log file to \verb+xxx+. This is either a fully qualified
filename, or more usually just a relative pathname which is taken
relative to the \file{logdir}.

\item[\verb+level=value+:]\index{log, level}
This adds to the logging levels the given value. Legal values are
\begin{describe}
\item[\verb+all+:]	Enable all logging (this fills disks very quickly!).
\item[\verb+fatal+:]	Enable reporting of fatal errors.
\item[\verb+exceptions+:] Report exceptional happenings.
\item[\verb+notice+:]	Report interesting happenings.
\item[\verb+trace+:]	Trace the programs flow (very detailed).
\item[\verb+debug+:]	A full debugging trace.
\item[\verb+pdus+:]	Show protocol data units.
\end{describe}
The last three levels are only available if PP was compiled with
\verb+PP_DEBUG+ defined to a suitable level. The value \verb|all| is
special, in that it sets all values. The other levels only set the
individual values (e.g. \verb+debug+ does not imply settings of any
other values).

The default level is to enable \verb+notice+, \verb+exceptions+ and
\verb+fatal+.

\item[\verb+dlevel=value+:]\index{log, dlevel}
This unsets a logging level. Legal values of this are the same as
the above.

\item[\verb+sflags=value+:]\index{log, sflags}
This sets the logging flags to a given value; the value being one of:
\begin{describe}
\item[\verb+close+:]	Close the log file after each entry is made.
\item[\verb+create+:]	Create the log file if it doesn't already exist.
\item[\verb+zero+:]	Zero the log file when it gets too big.
\item[\verb+tty+:]	Log to the standard error as well as to the
file. This should be used only when debugging.
\end{describe}
The default is \verb|close| and \verb|create|.

\item[\verb+dflags+:]\index{log, dflags}
This unsets one of the above levels for the log.

\item[\verb+size+:]\index{log, size}
Set the maximum size in Kilobytes to which the log should be allowed
to grow. The default is not to limit the log size. What happens when
the logfile reaches the specified maximum is governed by the flags. If
\verb|zero| is not in force, logging will just stop. If \verb|zero| is
in force, then the log will be truncated and restarted.
\end{describe}

There are currently four logging variables that can be specified
although there are several logging structures.  

The logging variables are :-

\begin{describe}
\item[\verb+normlog+:]\index{normlog}
This is the log where the bulk of the logging is done.

\item[\verb+operlog+:]\index{operlog}
This is where urgent messages are logged. In the normal course of
events no entries should be made in this log unless something serious
has happened.

\item[\verb+authlog+:]\index{authlog}
This indicates where authorisation tracing will be logged. 

\item[\verb+isodelog+:]\index{isodelog}
This line allows the tailoring of specific ISODE tracing levels. The
first argument is an ISODE logging level. The rest of
the line is interpreted as a normal log tailoring line.
Valid ISODE logging levels are :-
\begin{describe}
\item[\verb+compatlevel+:]	Compatibility level
\item[\verb+addrlevel+:]	Addressing level
\item[\verb+tsaplevel+:]	Transport level
\item[\verb+ssaplevel+:]	Session level
\item[\verb+psaplevel+:]	Presentation structures
\item[\verb+psap2level+:]	Presentation level
\item[\verb+acsaplevel+:]	Association level
\item[\verb+rtsaplevel+:]	Reliable transfer level
\item[\verb+rosaplevel+:]	Remote operations level
\end{describe}

\end{describe}

By default, all the ISODE logging is directed at the normal log.
An example of logging tailoring is shown in Figure~\ref{example:log}.

Notice that for a given program or channel, the logging information can be
diverted. 
If a logging entry starts with the name of the binary then that
line is specific to that program.
E.g.
\begin{quote}\small\begin{verbatim}
submit	normlog file=submit
\end{verbatim}\end{quote}
makes a submit specific \verb+normlog+ tailoring entry.
Hence all logging from \pgm{submit} directed at the \verb+normlog+ will go
to the file \verb+submit+ instead of the file associated with
\verb+normlog+. The net result is that all the normal logging message
from \pgm{submit} end up in the file \file{submit} in the log directory.

\tagrind[hbtp]{log-examp}{Example Of Log Tailoring}{example:log}

\section{Table Tailor File Entries}\index{tailoring, tables}

This section describes how the tables of aliasing and addressing
information, referenced by submit and the channel programs, are
defined in the tailor file.

Generally each table's entry is comprised of a line with several
key/value pairs.  The line starts with the keyword \verb+tbl+ which is
followed by a string setting the default name for the table and the
plain text file in \file{tbldir}.  Then come the key/value pairs,
described below.
\begin{describe}
\item[\verb+name=value+:]\index{table, name}
Name this table with the given value (to override the default - see
above). This is included only for completeness, it is not normally used.

\item[\verb+file=value+:]\index{table, file}
The tables contents are found in the given file (to override the default).

\item[\verb+show="value"+:]\index{table, show}
A descriptive string used when printing
messages about this table, mainly for logging purposes. 

\item[\verb+flags=value+:]\index{table, flags}
A set of flags that specify how this table
operates. It should be one of the following :-

\begin{describe}
\item[\verb+dbm+:]\index{table, dbm}
This table is stored in the database for fast
access (the default).

\item[\verb+linear+:]\index{table, linear}
This table is searched with a linear pass through the file in
\file{tbldir} (this is slow, but doesn't require rebuilding the
database and changes take immediate effect). Linearly searched files
are still built into the database.

\end{describe}

\end{describe}

An example of table tailoring is shown in Figure~\ref{example:table}.

\tagrind[hbtp]{table-examp}{Example Table Tailoring}{example:table}

\section{Channel Tailor File Entries}\index{tailoring, channels}

Channels are perhaps the most complex aspect of tailoring. There are
several types of channel. Input channels carry messages into the
system. Output channels carry messages out of the system. Reformatting
channels change the message structure in the queue. Finally there are
a few miscellaneous channels that do other jobs such as message deletion.

The channel tailor file entries each consist of the keyword \verb+chan+
followed by 
a value which, by default, names the channel and the program associated
with it; then comes a list of key/value pairs which provides more information
on the channel.  

The key/value pairs consist of the following:-
\begin{describe}
\item[\verb+name=value+:]\index{channel, name}
The name of the channel (overrides the default).
\item[\verb+prog=value+:]\index{channel, prog}
The program associated with this channel, i.e.  the actual binary to
run (overrides the default).

\item[\verb+show="value"+:]\index{channel, show}
A descriptive string used in pretty printing.  If this string starts
with the keywords \verb|with| or \verb|via| then this value is
included in \verb|Received| lines generated for RFC-822 messages.

\item[\verb+type=value+:]\index{channel, type}
This parameter is {\em mandatory} and indicates the type of channel
this is.  This {\em must} be set to one of the values shown below:

\[\begin{tabular}{|l|p{0.6\textwidth}|}
\hline
	\multicolumn{1}{|c|}{\bf Value}&
		\multicolumn{1}{|c|}{\bf Type of Channel}\\
\hline
	\tt in& 	An incoming channel.\\
	\tt out&	An outgoing channel.\\
	\tt both&	Both incoming and outgoing.\\
	\tt shaper&	A reformatter that changes the shape of the message.\\
	\tt warn&	A warning channel.\\
	\tt delete&	A message deletion channel.\\
	\tt qmgrload&	A queue manager loading channel.\\
	\tt debris&	A debris collection channel.\\
	\tt timeout&	A timeout channel.\\
\hline
\end{tabular}\]

\item[\verb+chanout=value+:]\index{channel, chanout}	
The associated channel that should be used to deliver receipt
notifications if required or errors if a message fails.
This setting is mandatory.
It should be set to
\pgm{dr2rfc} if the channel cannot handle X.400 style delivery
reports, or else an outbound channel if it can.

\item[\verb+content-in=value+:]\index{channel, content-in}
The content of this channel if it allows incoming messages. It is
normally either \verb+p2+, \verb+p22+ or \verb+822+. It should be
empty if the message is submitted in structured form.

\item[\verb+content-out=value+:]\index{channel, content-out}
The content of this channel if it allows outgoing messages. Values are
as for \verb|content-in|.

\item[\verb+cost=value+:]\index{channel, cost}
The cost of running this channel. This is used in the reformatting
calculations to decide the best conversion path.  The lowest cost
route will be chosen, all other things being equal. Costs are
relative, a cost of 0, the default, means that this channel
essentially makes no changes to the message. Higher costs make the
channel less favourable.

\item[\verb+sort=value+:]\index{channel, sort}
This value is a series of keys that are used for sorting purposes by
the queue manager. The first key is the primary sort key and must be
either \verb+mta+ or \verb+user+.  The remaining keys are secondary
sort keys and are taken in order.  The values for this field are any
of those shown below:
\[\begin{tabular}{|l|p{0.6\textwidth}|}
\hline
	\multicolumn{1}{|c|}{\bf Value}&
		\multicolumn{1}{|c|}{\bf Meaning}\\
\hline
	\tt mta&	Sort by destination MTA. This is the most common
primary sort key.\\
	\tt user&	Sort by username. This is useful for local
deliveries. \\
	\tt priority&	Sort by the priority of the message.\\
	\tt time&	Sort by queued time.\\
	\tt size&	Sort by the size of the message.\\
\hline
\end{tabular}\]

\item[\verb+info=value+:]\index{channel, info}
This contains channel specific information that can be used for a
variety of purposes.
For example, the \verb+info+ field is used by the simple formatters
to give the real program to run. Typically a simple formatter is a
shell script or similar, with \pgm{fcontrol} indicated as the program.
In such cases the \pgm{fcontrol} program is then responsible for queue
manager interaction and it runs the program in the info field as a
sub-process.

\item[\verb+adr=value+:]\index{channel, adr}
The type of addressing used by this channel.  The value is
one of those below:
\[\begin{tabular}{|l|l|}
\hline
	\multicolumn{1}{|c|}{\bf Value} &
		\multicolumn{1}{|c|}{\bf Meaning}\\
\hline
	\tt	x400&	X.400 addressing\\
	\tt	822&	rfc822 addressing\\
%%%	\tt	any&	any of the above two types\\
\hline
\end{tabular}\]

\item[\verb+subadr=value+:]\index{channel, subadr}
The type of subaddressing used by an outbound channel, if appropriate.
Currently this is only relevant in conjunction with a definition of
\verb+addr=822+. The value is one of those below:
\[\begin{tabular}{|l|l|}
\hline
	\multicolumn{1}{|c|}{\bf Value} &
		\multicolumn{1}{|c|}{\bf Meaning}\\
\hline
	\tt	real.rfc822&	normal rfc822 style addressing \\
	\tt	real.rfc733&	rfc733 style addressing \\
	\tt	jnt&		JNT style addressing \\
\hline
\end{tabular}\]
This list will change in the next release.

\item[\verb+adr-order=value+:]\index{channel, adr-order}
The ordering of addresses on this
inbound channel. This is one of the following :-
\[\begin{tabular}{|l|p{0.6\textwidth}|}
\hline
	\multicolumn{1}{|c|}{\bf Value} &
		\multicolumn{1}{|c|}{\bf Meaning}\\
\hline
	\tt usa&	Internet style addressing is insisted upon.\\
	\tt uk&		JNT style addressing is insisted upon.\\
	\tt usapref&	Internet style addressing is preferred but both
types will be tried.\\
	\tt ukpref&	JNT style is preferred but both types will be
tried. \\
\hline
\end{tabular}\]
The default value is \verb|usa|. Normally only UK sites will need to
modify this variable.

\item[\verb+bptin=value+:]\index{channel, bptin}
A list of body parts that the channel accepts as input. Volume 3 of
this document provides more information.  This must be one of the
types defined in the \verb|bodypart| tailoring item defined in
Section~\ref{tai:bodypart} on page~\pageref{tai:bodypart}.

\item[\verb+bptout=value+:]\index{channel, bpout}
A list of body parts that the channel will output.  The possible
values are the same as for those for bptin.

\item[\verb+table=value+:]\index{channel, table}
A table associated with this channel.

\item[\verb+mta=value+:]\index{channel, mta}
A destination MTA for this channel. If this is set, all messages will
be delivered to this MTA regardless of the destination MTA given in
the message. This is useful for relaying all messages for a given
channel via another mta.

\item[\verb+access=value+:]\index{channel, access}
The type of access this channel requires; only applicable to inbound
channel. The value is either \verb+mta+, in which case the channel
must be run by a trusted user-id, or else
\verb+mts+ in which case authentication of messages is enabled. The
default is \verb|mta|.

\item[\verb+domain-norm=value+:]\index{channel, domain-norm}
The amount of domain normalisation of MTS addresses on inbound
channels.  The value is one of those below (the default is
\verb+partial+):
\[\begin{tabular}{|l|l|}
\hline
	\multicolumn{1}{|c|}{\bf Value} &
		\multicolumn{1}{|c|}{\bf Meaning}\\
\hline
	\tt	full&		all domains in an MTS address are normalised\\
	\tt	partial&	only the next hop of an MTS address is normalised\\
\hline
\end{tabular}\]

\item[\verb+maxproc=value+:]\index{channel, maxproc}
This is the maximum number of instances of the channel the qmgr is
allowed to run at any time.
A value of \verb+0+ indicates that there is no maximum to the number
of instances the qmgr can run.
The default is \verb+0+.

\item[\verb+auth-table=value+:]\index{channel, auth-table}
This is a table which contains the authentication data for the channel
if it is an \verb+mts+ submission channel. The format is described in
Section~\ref{sect:authen} on page~\pageref{sect:authen}.

\item[\verb|conv|:]\index{channel, conv}
This variable specifies what affect the channel has on a message. This
is used to check on conversion restrictions. In particular the X.400
and RFC1148 conversion semantics. It may take one of the following
values:
\[\begin{tabular}{|l|l|}
\hline
	\multicolumn{1}{|c|}{\bf Value} &
		\multicolumn{1}{|c|}{\bf Meaning}\\
\hline
	\tt	none&	channel does no conversion\\
	\tt	1148&	channel does RFC1148/987 header mappings\\
	\tt	conv&	channel does conversion \\
	\tt	loss&	channel does conversion with loss\\
\hline
\end{tabular}\]
The default value is \verb|none|. Channels that do mapping of P2 to
RFC822 {\em headers} and the reverse should use the value \verb|1148|
to indicate that conversion can be carried out even in the presence of
the conversion-prohibited flag of X.400. This will allow messages with
header mappings and no body part conversions to go through and
RFC1148/987 gateway. 

Channels that change formats without loosing information (except
rfc987/1148 channels) should be marked as \verb|conv|. Channels which
loose data (such as, say, G3Fax to Ia5) should be marked as loss (they
should also be given a high cost).


\item[\verb|probe|:]\index{channel, probe}
This variable states whether this channel can support X.400 style
probe messages. It has values \verb|y| and \verb|n|. The default is
\verb|n|. This should be set for X.400 channels. If submit determines
the channel cannot support probes it will return a delivery report.

\end{describe}

An example of a channel tailoring is shown in
Figure~\ref{example:chan} and will help to make things a little clearer.
The descriptions above can be used to determine exactly what each
channel does.

\tagrind[hbtp]{chan-examp}{Example Channel Tailor Entry}{example:chan}
\clearpage

\section {ISODE runtime tailoring}

\subsection{Queue manager tailoring}
Information relating to the MTA, its \pgm{qmgr}, and their
addresses are obtained from the \file{/etc/isoentities} and take the form:
\begin{quote}\small\begin{verbatim}
vs2 "pp qmgr" 1.17.6.2.1 #1001/Internet=vs2+18000
\end{verbatim}\end{quote}

The first field is the designator of the machine that the \pgm{qmgr}
is running on. It most usually the name of the machine. The second is
the qmgr service; this should not be changed.  The same goes for the
other fields, except for the last one. This specifies the transport
selector that the qmgr listens on (1001 in this case) and the NSAP
address. In this case it is in internet form, with hostname \verb|vs2|
and TCP port number \verb|18000|.

\subsection{X.400 tailoring}
If the X.400 is going to be used, then a definition of this must be
placed in the file \file{/etc/isoservices}. A suitable definition
might look like this:
\begin{quote}\small\begin{verbatim}
"tsap/p1"  "591"   /usr/lib/pp/chans/x400in84
\end{verbatim}\end{quote}

This shows the service name \verb|tsap/p1|, the transport selector
\verb+"591"+ and indicates the location of the program. You should use
a numeric IA5 form of TSEL for X.400(1984) compliance.

For more details of the formats of these files, see {\em The ISO
Development Environment: Users Manual}.

\section {Tailoring of Common Channels}\index{channel}

Channels perform operations on messages.  The following terms are
applied to channels which are endpoints.  Intermediate channels for
reformatting and other manipulation are considered later.  The
following terms apply to endpoint channels:

\begin {description}
\item[outbound]  A channel which delivers messages out of PP.

\item[inbound]  A channel which passes message into PP (through submit).

\item[active] A channel which is initiated by the QMGR

\item[passive] A channel which is not initiated by the QMGR (typically by a
user or server).

\end {description}

The most common types of channel are passive inbound and active outbound.
\subsection	{Protocol channels}

Protocol channels are channels that talk to the outside world. There
are a number of these supplied with PP.  Those that have special
requirements or are optional are described here.

\subsubsection	{SMTP channel}\label{sect:smtp}
The \pgm{smtp} channel comes in two parts, the outbound part and the
inbound daemon. The inbound daemon can have a number of arguments to
it, and can be run either under the control of \man inetd (8) or under
the standalone server \pgm{smtpd}. To configure it to run under
\pgm{inetd} the following entry in the file \file{/etc/inetd.conf}
might be appropriate (but see \man inetd.conf (5) for more details).

\begin{quote}\small\begin{verbatim}
smtp stream tcp nowait pp /usr/lib/pp/cmds/chans/smtpsrvr smtp
\end{verbatim}\end{quote}

If however you prefer to run a standalone smtp server, the command is
something like this (usually included in \file{pp.start}).

\begin{quote}\small\begin{verbatim}
/usr/lib/pp/cmds/smtpd /usr/lib/pp/cmds/smtpsrvr smtp
\end{verbatim}\end{quote}

The following arguments are supported by the \pgm{smtpd} program.
\begin{describe}

\item[\verb|-p port|:]	Specify a different tcp port to listen on when
running standalone.

\item[\verb|-i maxcon|:] Set the maximum number of simultaneous smtp
connections that are supported. Only obeyed when running standalone.

\item[\verb|-t timeout|:]	Set a default timeout for use with the
nameserver. This is only used if the server is compiled with nameserver
support included.

\end{describe}
The two mandatory arguments for \pgm{smtpd} are the name of a server
program to interpret the smtp protocol, and the name of a channel that
incoming messages will arrive on.

Finally, the smtp server makes use of one additional tailoring
variable in the channel specification. If the \verb|info| element of
the channel tailoring entry contains the string
\verb|sloppy|\index{sloppy} then any connection will be allowed. If
this is not the case, connections are only supported from hosts that
can be reversed translated (e.g. the IP number can be converted to a
host name).

The smtp outbound channel has only one special option. It can be
given a flag \verb|-p port| to tell it to connect to a different tcp
port other than the default. This can be set up by setting the tailor
entry to something like the following.

\begin{quote}\small\begin{verbatim}
chan smtp-odd pgm="smtp -p 2001",show="Odd smtp"...
\end{verbatim}\end{quote}


\subsubsection	{X.400 inbound channel}

The X.400 (1984) inbound channel (\pgm{x400in84}) takes note of the
\verb|info| part of the tailoring information. If this is set to the
string \verb|sloppy| then no checking of mta name and password is done
for any connection incoming on that channel. Also, if the NSAP cannot
be looked up in the channel table the connection is still allowed.

X.400 inbound also has an optional flag, this is as follows:
\begin{describe}
\item[\verb|-c channelname|:]	Claim to be the given channel name on
input. You may have a number of x400 inbound channels, selected
initially by T-Selector or network address. If you wish to split up
traffic in this way, possibly for authorisation reasons, you should
set the channel name in this way in the isoservices file. By default
the channel is assumed to be the name of the program itself.
\end{describe}

\subsubsection	{UUCP channel}\index{channel, uucp}

The uucp channel interfaces to the UUCP system. It uses the \verb|info|
string of the channel to tailor the interface. This string is a key
value pair that can set various parameters. The key/value pairs are
separated by a comma. The possible keys are:
\begin{describe}
\item[\verb|uux|:]	Set the \verb|uux| pathname and arguments.
This parameter must be present.

\item[\verb|host|:]	When constructing the uucp from line, use this
value as the host name.
\end{describe}
An example configuration might be:
\begin{quote}\small\begin{verbatim}
chan uucp-out prog=uucp-out,show="UUCP outbound channel",type=out,
    adr=822,adr-order=ukpref,table=uucp
    chanout=dr2rfc,
    info="uux=/usr/bin/uux - -r,host=nott-cs"
\end{verbatim}\end{quote}


\subsubsection	{822-local channel}\index{channel, 822-local}

The \pgm{822-local} channel has only one tailoring feature. If the
\verb|info| string is set to \verb|resticted| then the
\file{.mailfilter} file processing is reduced in functionality as
follows:
\begin{itemize}
\item	The user is not allowed to set the variable PATH to search
other directories for programs. (Actually this variable can be set, it
is just ignored.)
\item	The processes executed by the \verb|pipe| command bust be in
the \verb|USRBINDIR|\index{USRBINDIR} defined in the \file{Make.defs} file.
\item	The processes executed by the \verb|pipe| command must be
executable by the system call \man exec(2). (E.g. redirection and
shell syntax will not be obeyed).
\end{itemize}

\subsection	{Filter Control and Common Filters} \index{filter control}

Filters can be called via a special channel called \pgm{fcontrol}.
The channel can be used in a variety of guises to run various filters
on messages and, in particular, on the body parts within the messages.
It should only be used for filters where there is a one-to-one mapping
between incoming body parts and outgoing body parts; i.e. the contents
of the body parts, and possibly their names, may be altered by a
filter, but the structure of the message will remain the same.

A filter reads an incoming body part from the standard input, does the
required filtering, and writes the outgoing body part to the standard
output.  Any error or logging messages produced by the filter should
be written onto the standard error. \pgm{fcontrol} logs these messages
at the \verb+LLOG_NOTICE+ level. The filter should exit with a value
of \verb|0| to indicate success. Any other exit value is taken as
failure.

To create a channel which runs a given filter, an entry has to be made
in the tailor file.  The entry should be constructed in the normal way
with the following provisos:

\begin{describe}

\item[\verb+prog+:] This should contain the filename of the
filter controller, \pgm{fcontrol}.

\item[\verb+info+:] The pathname of the filter's executable program should be
placed in the \verb+info+ field, followed by any arguments that are to
be passed to the filter.  If the given name is not a fully qualified
pathname, the filter controller assumes the executable to be under the
\file{formdir} directory.  Arguments of the form \verb+$(key)+ will be
expanded to the entities described in Table~\ref{tab:expansions}.  The
key is case independent.

\item[\verb+bptin+/\verb+bptout+] 
Filters should not change the structure of the message. \verb+bptin+
should only contain one type of bodypart.  This type is the bodypart
type that the filter converts. \verb+bptout+ should also only contain
one type of bodypart.  This bodypart type is the result of the
filter's conversion.
i.e. the filter converts bodypart \verb+bptin+ into bodypart
\verb+bptout+.

\item[\verb+type+] The type should be set to \verb|shaper|.

\end{describe}

\tagtable{info_expan}{Filter Control Expansion Macros}{tab:expansions}

Example tailor file entries of filters running inconjunction with
\pgm{fcontrol} are shown in Figure~\ref{example:fcontrol}.

\tagrind[hbtp]{filt-examp}{Example Filter Control Tailoring}{example:fcontrol}

Trivial filters such as voice to ia5 mappings can be done by a simple
shell script of the type shown in Figure~\ref{example:shellfilt}.

\tagrind[hbtp]{shelfilt}{Simple shell script filter}{example:shellfilt}

Here are descriptions of some common filters run inconjunction with
\pgm{fcontrol}:

\subsubsection {RFC 822 Filter}\index{rfc822norm}

The RFC 822 filter \pgm{rfc822norm} is used in conjunction with the
general filter controller \pgm{fcontrol}, for dealing with RFC 822 and
related headers.  It takes a generic RFC 822 header as input, and
outputs a ``normalised'' form.  A normalised header is one in which
all address are fully qualified and are in the correct order.  For
this reason, the \verb+bptin+ and {\verb+bptout+} fields in any
associated tailor file entry should be some extended version of
{\verb+hdr.822+}, e.g \verb+hdr.822+, {\verb+hdr.822-uk+} etc.

The filter affects the following fields of the RFC 822 header:

\begin{itemize}
\item All of the addressing fields in RFC 822
\item The Acknowledge-To field (JNT Mail)
\end{itemize}

The filter's behaviour may be altered by specifying various options.
These options are passed through \pgm{fcontrol} to the filter
by use of the info element of the channel structure.
One possible info element is as follows :
\begin{quote}\small\begin{verbatim}
rfc822norm -822 -striptrace -jntsender $(822sender)
\end{verbatim}\end{quote}

The RFC 822 filter can be used in a variety of guises.
For example, in appendix~\ref{app:tailor} the combination of
\pgm{fcontrol} and \pgm{rfc822norm} appears twice, so
providing two different channels, \pgm{822touk} and \pgm{822tous}.

The filter takes the following options:

\begin{describe}

\item[\verb+-822+:] Format source routes according to RFC 822.

\item[\verb+-733+:] Format source routes with a ``\%'' notation (default).

\item[\verb+-bigend+:] Format domains big--endian.

\item[\verb+-littleend+:] Format domains little--endian (default).

\item[\verb+-jnt+:] A combination of the \verb+-bigend+ option and the
\verb+-733+ option.

\item[\verb+-striproutes+:] Removes any source routes (733 or 822)
from the \\
header. This removal starts after the first valid domain in each address.

\item[\verb+-stripdomain <domain>+:] Like -striproutes, except that only the
specified domain is stripped.

\item[\verb+-striptrace+:] Remove all trace fields from the header.

\item[\verb+-jntsender <sender>+:] This applies the rules of mailgroup note 15,
to ensure that the JNT Mail return path correctly identifies the P1 originator.
Typically, this will involve adding a Sender Field to the message, and
possibly modifying existing trace fields.

\item[\verb+-msgid+:] This flag ensures the presence of a message id in
the message.
If there is no message id, the RFC 822 filter will create one and
append it to the header.

\item[\verb+-percent+:] This flag indicates that the \verb+%+
character should be treated as a \verb+@+ character when parsing
addresses.  This flag also indicates that all domains in addresses
should be normalised.  By default, only the next hop of an address is
normalised.

\item[\verb+-hidelocal <pattern>+:] Apply a host hiding heuristic to
'clean-up' mail sent from other hosts on site which is going off-site.
Pattern can be a simple domain or a domain with wildcard subdomains.
e.g. \verb+*.icl.stc.co.uk+ or \verb+stl.stc.co.uk+ but not
\verb+frodo.*.co.uk+.
WARNING: this flag should be used with care and should not normally be
required.

\item[\verb+-fold <number>+:] This indicates the length for displaying 
RFC 822 header fields. 
The default value is 79; alternately with a value of -1 there will be 
no folding. Whatever the value, folding will only occur at higher level
breaks, and not within an address. 

\end{describe}

\subsubsection	{Body part deleting filters}

In the \file{formdir} directory there is a general shell script that
can be run as a filter to remove body parts. It ignores it's input and
writes out a short message indicating that the body part has been
removed. This can be used as a trivial filter in say, \verb|fax| to
\verb|ia5|, to indicate that a fax body part has been deleted.
The info string for such a channel might be
\begin{quote}\small\begin{verbatim}
info='removebp "Group 3 Fax"'
\end{verbatim}\end{quote}
An example tailor file entry for such a filter is shown in
figure~\ref{example:fcontrol}.

\subsubsection	{ODIF filters}
There exist some filters that will convert between BBN Slate format
and ODIF. These filters are not publically available as they were
developed under an ESPRIT PODA project. However, anyone interested in
these filters should contact Prof. Peter Kirstein
(P.Kirstein@cs.ucl.ac.uk).

\subsection	{The List Channel}\index{list}

This channel should be tailored in a content independent fashion.
This means that the following fields should \verb+NOT+ be set:
\begin{describe}
\item[\verb+content-in+]
\item[\verb+content-out+]
\item[\verb+bptin+]
\item[\verb+bptout+]
\item[\verb+adr+]
\item[\verb+subadr+]
\item[\verb+adr-order+]
\end{describe}
A valid content independent entry for the list channel is as follows:
\begin{quote}\small\begin{verbatim}
chan list prog=list,show="List channel",type=both,
          table=list,chanout=dr2rfc
\end{verbatim}\end{quote}

Note that the \pgm{list} channel can expand sublists of a list.
This will improve performance if there is a number of nested lists
{\em BUT} may cause problems with the sender field.
If a sublist is expanded, it will be submitted with the sender
relating to the main list and not relating to the sublist.
By default, the expansion of sublists is disabled. 
To enable it, the \verb+info+ field
should be set to the string \verb+dosublists+.

\subsection 	{Shaping Channels}

Shaping channels alter the structure of the message.
This section describes tailoring requirements of the common shaping
channels. 

\subsubsection	{RFC 934 Channel}\index{rfc934}

The \pgm{rfc934} channel flattens an RFC 822 style message as
specified by RFC 934.  The tailor file entry for such a channel should
be constructed with the following provisos:
\begin{describe}

\item[\verb+type+] This field should be set to \verb+shaper+ as the
channel alters the shape of the message.

\item[\verb+content-out+] This field should contain the value
\verb+822+ to indicate that it converts contents to RFC-822 format.
\end{describe}
Note that the \pgm{rfc934} channel only recognises three types of
bodyparts: RFC 822 headers which it recognises as starting with the
string \verb+hdr.822+; text bodyparts which it recognises as being of
the form \verb+n.ia5+ where \verb+n+ is a number; and forwarded
messages which it recognises as being subdirectories.
If there is a bodypart in the message that it doesn't recognise, the
\pgm{rfc934} channel will fail.
The key strings \verb+hdr.822+ and \verb+ia5+ are hardwired into PP.
They can be changed by editing the relevant entries in the file
\file{Lib/pp/static.c} within the source tree.

\subsubsection	{P2flatten Channel}\index{p2flatten}

The \pgm{p2flatten} channel combines all the separate components of a
message into one file of \verb+p2+ or \verb+p22+, depending on how the
channel is tailored.  The tailor file entry for such a channel should
be constructed with the following provisos:
\begin{describe}

\item[\verb+type+] This field should be set to \verb+shaper+ as the
channel alters the shape of the message.

\item[\verb+content-out+] This field should contain the content
that the channel outputs. 
It should be either \verb+p2+ or \verb+p22+.
If it is set to \verb+p2+ \pgm{p2flatten} will output a file of \verb+p2+
(i.e. a message suitable for transfer via X.400 (84)).
If it is set to \verb+p22+ \pgm{p2flatten} will output a file of
\verb+p22+ (i.e. a message suitable for transfer via X.400 (88)).

\end{describe}

\subsubsection	{P2explode Channel}\index{p2explode}

The \pgm{p2explode} channel explodes a \verb|p2| or \verb|p22| message into its
separate component bodyparts.  The tailor file entry for such a
channel should be constructed with the following provisos:
\begin{describe}

\item[\verb+type+] This field should be set to \verb+shaper+ as the
channel alters the shape of the message.

\item[\verb+content-in+] This field should contain the inbound
content, either \verb+p2+ or \verb+p22+.

\end{describe}

\subsection      	{Miscellaneous Channels}

Miscellaneous channels groups together the ``special'' channels
required by PP.  This section describes tailoring requirements of
these ``special'' channels.

\subsubsection	{Qmgrload Channel}\index{qmgrload}

The \pgm{qmgrload} channel is used to refresh the \pgm{qmgr} model of
the queue by reading the model stored on disc.  The only proviso for
the tailor file entry of this channel is that the
\verb+type+ is set to \verb+qmgrload+.

\subsubsection	{Msg-Clean Channel}\index{msg-clean}

The \pgm{msg-clean} channel is used by the \pgm{qmgr} to free the
storage associated with a message once all activity to do with that
message has finished.  For the tailor file entry of this channel,
\verb+type+ is set to \verb+delete+.

\subsubsection	{Debris Channel}\index{debris}

The debris channel is used by the \pgm{qmgr} to free any storage which
no longer is of interest to the mail system.
The tailor file entry of this channel should have \verb+type+ set to
\verb+debris+.

\subsubsection	{Timeout Channel}\index{timeout}

The timeout channel is used to time messages out once they have been
around for a given time.
The tailor file entry of this channel should have \verb+type+ set to
\verb+timeout+.

\section{How channels work}\label{chan-op}

A channel is called by the \pgm{qmgr}, and initialised.  Then it is told to 
process a given message and a set of recipients.  All of the identified
recipients will be on the same MTA, or require the same conversion.
The channel will then attempt to do the work.  After this it will update
the Queue  in the following way for each recipient:

\begin {itemize}
\item  If a conversion suceeded, increment the reformat counter
\item If a delivery suceeded, set the status to DONE or DR, dependent on
whether a positive Delivery Report is needed.
\item If the operation failed, set the status to DR.
\end {itemize}

If the status is set to DR, the DR should be generated before updating
the queue status.  When the queue is updated, the \pgm{qmgr} should be
informed of the final status of each recipient.  The \pgm{qmgr} will
then give the channel more work, or close it down.  Connections to
MTAs should be kept open --- the \pgm{qmgr} will attempt to sort the
queue by MTA.

This section describes the tailoring requirements of some of the
common channels.
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦04254838e⟧ TextFile

Derivation

TextFile
