358 lines
9.6 KiB
Groff
358 lines
9.6 KiB
Groff
.TH digest 1
|
|
.SH NAME
|
|
digest \- receive a file for a digest, or create and mail a digest
|
|
.LP
|
|
.SH SYNOPSIS
|
|
.B digest \-r|R|m|p \-C \-l
|
|
.I majordomo-listname recipient
|
|
.LP
|
|
.B digest \-r|R|m|p
|
|
[
|
|
.B \-c
|
|
.I configuration-file
|
|
]
|
|
.LP
|
|
.SH AVAILABILITY
|
|
Provided with distributions of Majordomo.
|
|
.LP
|
|
.SH DESCRIPTION
|
|
The digest script is a perl script which automates the
|
|
management of digests of electronic mail. It can be
|
|
run in a standalone configuration or as part of Majordomo.
|
|
.LP
|
|
It requires two directories: a work directory and an
|
|
archive directory. Incoming email messages are held
|
|
in the work directory until they are collected into a
|
|
digest. The digests are created and stored
|
|
in the archive directory.
|
|
.LP
|
|
Incoming email messages are given
|
|
numerical names starting with ``001'' and are numbered in
|
|
order of arrival. The digests are named according to volume
|
|
and number. For example, the filename ``v01.n028'' indicates
|
|
volume 1, number 28 of the digest.
|
|
.LP
|
|
It should be noted that digest needs a configuration file
|
|
to define all of its operating parameters. If no such
|
|
file is specified, digest will use the
|
|
.SB $HOME/.digestrc
|
|
file.
|
|
.LP
|
|
Several aspects of digest configuration determine how and
|
|
when a digest is created. A digest can be created at
|
|
regular intervals (as long as there are incoming messages)
|
|
or whenever certain configurable conditions are met. These
|
|
conditions are: how large the digest can be (in characters),
|
|
how long the digest can be (in lines), and how old the messages
|
|
in the digest can be (in days).
|
|
.LP
|
|
.SH OPTIONS
|
|
.TP 10
|
|
.B \-r
|
|
Receive an email message via standard input
|
|
and place the file into the working directory.
|
|
If any one of the conditions for digest creation
|
|
are met, create and mail a digest. These conditions
|
|
are the same as those described under option
|
|
.BR \-p.
|
|
.TP
|
|
.B \-R
|
|
Similar to
|
|
.BR \-r,
|
|
except that it will not create a digest. It simply
|
|
places the message in the work directory and stops.
|
|
.TP
|
|
.B \-m
|
|
If there are any numbered files in the working
|
|
directory, create and mail a digest. Store the
|
|
digest in the archive directory. This is the
|
|
option used by majordomo's mkdigest command.
|
|
.TP
|
|
.B \-p
|
|
Conditionally creates a digest. If any one of the
|
|
conditions for digest creation are met, the digest
|
|
is created and sent. There are three conditions,
|
|
which are connected to three limits: the digest
|
|
size in characters, the digest length in lines, and
|
|
the age of the oldest message in days. If one of the
|
|
files is older than the age limit, a digest is created.
|
|
If the sum of the messages exceeds either of the size
|
|
limits, a digest is created. The size limit in characters
|
|
must be configured; the other two limits are optional.
|
|
.TP
|
|
.B \-c configuration-file
|
|
Use the parameters defined in
|
|
.IR configuration-file.
|
|
.TP
|
|
.B \-C
|
|
Read the majordomo configuration file
|
|
(either /etc/majordomo.cf or ~majordomo/majordomo.cf)
|
|
and the configuration file for the Majordomo list specified in the
|
|
.BR \-l
|
|
option to define operational parameters. If both
|
|
.BR \-C
|
|
and
|
|
.BR \-c
|
|
options are specified (not recommended) only the
|
|
.BR \-C
|
|
option will be used.
|
|
.TP
|
|
.B \-l majordomo-listname
|
|
This option is ignored if used without the
|
|
.BR \-C
|
|
option. Specifies the Majordomo email list.
|
|
.LP
|
|
.SH OPERANDS
|
|
.TP 10
|
|
.B recipient
|
|
Email recipient of the digest. This operand is ignored if used
|
|
without the
|
|
.BR \-C
|
|
option. It specifies one of the system mail
|
|
aliases created for the Majordomo list named in the
|
|
.BR \-l
|
|
option.
|
|
.LP
|
|
.SH MAJORDOMO DIGEST CONFIGURATION
|
|
When used as a part of Majordomo, digest takes these parameters
|
|
from
|
|
.B majordomo.cf
|
|
(either /etc/majordomo.cf or ~majordomo/majordomo.cf):
|
|
.LP
|
|
.PD 0
|
|
.B $listdir
|
|
\- the location of the mailing lists
|
|
.LP
|
|
.B $digest_work_dir
|
|
\- parent directory for the digests' work directories
|
|
.LP
|
|
.B $filedir
|
|
\- parent directory for archive directories
|
|
.LP
|
|
.B $filedir_suffix
|
|
\- an optional identifier (may be the null string)
|
|
.PD
|
|
.LP
|
|
Incoming messages for
|
|
.B $listname-digest
|
|
will be held in
|
|
.B $digest_work_dir/$listname-digest.
|
|
.LP
|
|
Digests will be stored in
|
|
.B $filedir/$listname-digest$filedir_suffix.
|
|
.LP
|
|
The list's configuration file will be
|
|
.B $listdir/$listname-digest.config.
|
|
.LP
|
|
Examples of these values are given in
|
|
.SB EXAMPLES,
|
|
below.
|
|
.LP
|
|
The list's configuration file contains several digest parameters that
|
|
are not yet implemented and/or should NOT be changed from their defaults
|
|
(blank):
|
|
.B digest_archive, digest_rm_footer, digest_rm_fronter, digest_work_dir.
|
|
.LP
|
|
The parameters which specifically deal with digest creation
|
|
and maintenance are:
|
|
.LP
|
|
.PD 0
|
|
.B digest_name
|
|
\- the title of the digest
|
|
.LP
|
|
.B digest_volume
|
|
\- volume number
|
|
.LP
|
|
.B digest_issue
|
|
\- issue number
|
|
.LP
|
|
.B digest_maxdays
|
|
\- age limit in days for oldest message in the digest
|
|
.LP
|
|
.B digest_maxlines
|
|
\- maximum number of lines in a digest
|
|
.LP
|
|
.B maxlength
|
|
\- maximum number of characters in a digest
|
|
.LP
|
|
.B message_fronter
|
|
\- text prepended to the digest
|
|
.LP
|
|
.B message_footer
|
|
\- text appended to the digest
|
|
.PD
|
|
.LP
|
|
The last three parameters are also used in the configuration of
|
|
an ordinary (non-digest) Majordomo list.
|
|
.LP
|
|
Each digest begins with the a line containing the
|
|
.B digest_name, current date, digest_volume and digest_issue.
|
|
. The digest script will update the issue number in the configuration file.
|
|
.LP
|
|
A blank line follows, and then the text from the
|
|
.B message_fronter,
|
|
if any. The message fronter may contain the
|
|
.SB _SUBJECT_
|
|
token, which will be replaced by the subject lines from the messages
|
|
in the digest.
|
|
.LP
|
|
The text in the
|
|
.B message_footer,
|
|
if any, will be appended to the digest.
|
|
.LP
|
|
To embed a blank line in the
|
|
.B message_footer
|
|
or
|
|
.B message_fronter,
|
|
put a `-' as the first and ONLY character on the line. To
|
|
preserve whitespace at the beginning of a line, put a `-'
|
|
on the line before the whitespace to be preserved. To put
|
|
a literal `-' at the beginning of a line, double it.
|
|
.LP
|
|
Both message_footer and message_fronter may also use the tokens
|
|
.SB $LIST, $SENDER,
|
|
and
|
|
.SB $VERSION,
|
|
which will be expanded to,
|
|
respectively: the name of the current list, the sender as taken
|
|
from the from line, and the current version of Majordomo.
|
|
.LP
|
|
Examples of the aliases usually used with the digest are
|
|
given in
|
|
.SB EXAMPLES,
|
|
below.
|
|
.LP
|
|
The list owner can prompt Majordomo to build a digest by
|
|
sending the command
|
|
.LP
|
|
mkdigest
|
|
.I digest-name
|
|
[
|
|
.I outgoing-address
|
|
]
|
|
.I digest-password
|
|
.LP
|
|
to majordomo either via email or from cron. The cron
|
|
command has the format:
|
|
.LP
|
|
echo mkdigest
|
|
.I digest-name
|
|
[
|
|
.I outgoing-address
|
|
]
|
|
.I digest-password
|
|
| mail majordomo@domain.com
|
|
.LP
|
|
.SH STANDALONE DIGEST CONFIGURATION
|
|
The Majordomo distribution comes with a ``digest'' subdirectory.
|
|
The sample configuration file is called firewalls-digest.cf.
|
|
A file in this format must be used if digest is invoked in
|
|
standalone configuration.
|
|
.LP
|
|
If no configuration file is specified when digest is invoked,
|
|
it looks for a file named
|
|
.SB $HOME/.digestrc
|
|
that must be in the same format as the example file.
|
|
.LP
|
|
The configuration file defines the email addresses of the
|
|
sender and recipient of the digest. It also locates the
|
|
work and archive directories, the digest's size limit,
|
|
and the names of the files that contain the digest's volume,
|
|
number, header and footer.
|
|
.LP
|
|
The easiest way to configure a standalone digest is to copy
|
|
the five files (firewalls-digest.*) and edit them to taste.
|
|
.LP
|
|
Incoming mail is piped to digest with the
|
|
.B \-r
|
|
option. This can be done from some mail-reading programs, through
|
|
the command line, or via mail aliases similar to those
|
|
found in
|
|
.SB EXAMPLES,
|
|
below.
|
|
.LP
|
|
.SH EXAMPLES
|
|
.LP
|
|
1. Example values from
|
|
.B /etc/majordomo.cf:
|
|
.LP
|
|
.PD 0
|
|
.B $listdir = ``usr/local/mail/lists'';
|
|
.LP
|
|
.B $digest_work_dir = ``usr/local/mail/digest'';
|
|
.LP
|
|
.B $filedir = ``listdir'';
|
|
.LP
|
|
.B $filedir_suffix ``archive'';
|
|
.PD
|
|
.LP
|
|
If our digest's name is banjo-digest, the work directory will
|
|
be /usr/local/mail/digest/banjo-digest; the archive directory
|
|
will be /usr/local/mail/lists/banjo-digest.archive. Note
|
|
that these are names of directories, not files.
|
|
.LP
|
|
2. Typical aliases for Majordomo digests:
|
|
.LP
|
|
Usually a Majordomo digest is associated to a regular (non-digest)
|
|
list. The digest's name is the regular listname plus ``-digest''.
|
|
The list ``banjo'' will have the digest ``banjo-digest''.
|
|
.LP
|
|
.PD 0
|
|
.B banjo-digest-approval: kevink
|
|
.LP
|
|
.B banjo-digest-outgoing: :include:/usr/local/lists/banjo-digest
|
|
.LP
|
|
.B owner-banjo-digest-outgoing: kevink
|
|
.LP
|
|
.B banjo-digestify: ``|usr/majordomo/wrapper digest \-r
|
|
.B \-C \-l banjo-digest banjo-digest-outgoing''
|
|
.LP
|
|
.B banjo-digest: banjo
|
|
.PD
|
|
.LP
|
|
Note that mail to ``banjo-digest'' is routed to the regular list.
|
|
The ``digestify'' alias must be added to the regular list's outgoing
|
|
alias:
|
|
.LP
|
|
.B banjo-outgoing: :include:/usr/local/lists/banjo,banjo-digestify
|
|
.LP
|
|
.SH NOTES
|
|
The volume number does not change automatically; it must be
|
|
incremented manually.
|
|
.LP
|
|
For testing/debugging purposes there is a ``hidden'' option
|
|
.B -d
|
|
that creates the digest as /tmp/testdigest.nnn
|
|
(where
|
|
.I nnn
|
|
is the current digest number). Since it is for testing and
|
|
debugging purposes, it does not mail the digest, it does not
|
|
place the digest in the archive directory, and it does not
|
|
update the digest number.
|
|
.LP
|
|
.SH EXIT STATUS
|
|
The following exit values are returned:
|
|
.TP 10
|
|
.B 0
|
|
Successful completion.
|
|
.TP
|
|
.B >0
|
|
An error occurred.
|
|
.LP
|
|
.SH FILES
|
|
.PD 0
|
|
.TP 20
|
|
.B /etc/aliases
|
|
.TP
|
|
.B /etc/majordomo.cf
|
|
.PD
|
|
.LP
|
|
.SH SEE ALSO
|
|
.B majordomo(8)
|
|
.LP
|
|
.SH AUTHOR
|
|
The digest script was written by Brent Chapman <brent@GreatCircle.COM>.
|
|
It is available with distributions of Majordomo via anonymous FTP
|
|
from FTP.GreatCircle.COM, in the directory pub/majordomo. This
|
|
man page was written by Kevin Kelleher <fury@world.std.com>.
|