NAME¶
gup - A
Group
Update
Program that accepts commands by mail
to edit a newsgroup subscription file for subsequent use by news systems such
as
INN and
C-News.
SYNTAX¶
gup [
-hvP] -a
active_path [
-d home_directory]
[
-l log_path] [
-m reply_headers] [
-n
newsgroups_path] [
-s sites_directory] [
-M
Mail_command]
DESCRIPTION¶
The sole purpose of
gup is to automate the tedious process of editing
group selection patterns defined in the news configuration files (eg:
``newsfeeds'' for
INN and ``sys'' for
C-News).
Gup is of use to news administrators who spend an inordinate amount of
time editing their news config files at the behest of the sites they feed. In
fact, once
gup is installed, it is quite likely that manual edits of
your ``newsfeeds'' or ``sys'' file will become a thing of the past.
Gup is designed to be installed as a mail-server program that is fed an
inbound mail via stdin.
Gup is usually invoked from a .forward file.
Eg:
"|/.../bin/gup -options...."
Each site has an entry in the ``config'' file containing password and mail
address details and a group selection file called ``groups'', see
CONFIG, and
GROUPS for more details.
The news administrator of each site mails commands to
gup. There are
commands to include and exclude group patterns, list the current patterns for
that site and list the available newsgroups; see
COMMANDS, for more
details.
The results are normally mailed back to the site's configured administrator.
However under some circumstances, the results are mailed to the originator or
the local administrator; see
PROCESSING, for further details.
Gup does not directly change the news system's control files (eg,
``newsfeeds'' for INN). Instead a trivial shell script must be run to
concatenate all of the changed ``groups'' files together into an appropriately
formatted file for your particular news system. (One is provided in the source
kit for INN).
Since each site has to be specifically configured in
gup's ``config''
file, access can be restricted to administrator's capable of managing their
own group patterns.
OPTIONS¶
Options can appear in any order on the command line. The most important point to
note is that all of the paths and directories defined will normally be
absolute paths unless you are intimately familiar with the way in which
gup changes directories as it processes a mail (the possible exception
here is the Sites_directory).
- -a active_path
- The path of the active file for your news system. Before accepting any
newsgroup identified in a command, gup validates the group against
the active file. The command is rejected if no match is found.
- -d home_directory
- Defines gup's home directory. Gup changes to this directory
as soon as possible after starting up. If this option is not present, the
current directory is used. Gup looks for the ``config'' file in
it's home directory.
- -h
- Print out a help message showing the command line options, then exit.
- -l log_path
- A record of all significant requests are written to this file. If the path
is relative, then it will be relative to gup's home directory; see
the -d option). Gup must be able to write to this file. If the
-l option is not used, then gup uses stderr. This is useful
for testing purposes, but is unlikely to be of use in a .forward
file.
- -m reply_headers
- When gup generates a mail response it only generates the ``To: ''
header line. This option defines the path of a file that contains other
RFC882 conformant header lines that are piped to the mail program (see the
-M option). In fact, if this file contains a body following the headers,
then that will precede any text generated by gup. If this path is
not an absolute path, then it will be treated as relative to gup's
home directory (see the -d option).
- -M Mail_command
- Gup pipes the rfc822 headers and the body of the mail to the
nominated mail program. Normally, this is configured when gup is
installed, but it can be over-ridden with this option. The mail command
must be able to determine the recipient addresses from the rfc822
headers.
- -n newsgroups_path
- If present, the newsgroups file is used to try and find a matching
description of newsgroup when listed.
- -P
- Do not prune superfluous patterns from a site's ``groups'' file.
Before writing the updated ``groups'' file, gup applies a fairly
rigorous test to the patterns, pruning any nonsensical or un-necessary
patterns. This pruning process can be quite CP intensive to the extent
that it may have a deleterious effect on your system - thus the ability to
disable it.
- -s Sites_directory
- Each site's ``groups'' and ``exclude'' file are located in a unique
directory for each site. These site directories are located in the
directory defined with this option. If this is given as a relative path
then it will be relative to gup's home directory (see the -d
option). Gup will try and create this directory if it does not
exist.
- -v
- Print out the version number and various compile-time variables, then
exit.
COMMANDS¶
Gup scans the body of the mail for commands. Blank lines are ignored and
any data after the ``#'' character is considered a comment. No continuation is
allowed. Many of the commands accept a pattern as a parameter. This pattern is
identical to the format of the wildmat() pattern; see
wildmat (3) ). In
fact,
Gup purposely uses the
wildmat routine from INN to ensure
that the pattern matching characteristics are identical.
Valid commands are:
- site sitename password
- This must be the first command in the mail. sitename and
password must match an entry in the ``config'' file. Only one
site command is allowed per mail. Aliases: "open" and
"host".
- quit
- This command stops gup from processing the rest of the mail. This
is useful if your mail User Agent tends to automatically append a
signature file to your mail. Alias: "q".
- include pattern
- The pattern is checked against the active file. If it matches at
least one newsgroup, the pattern is placed at the end of the site's
``group'' file as an include entry. Only one pattern per
include command is allowed. If the pattern matches anything in the
site's exclusion list (see EXCLUSIONS) then the include will fail.
Aliases: "+" and "inc".
- exclude pattern
- The pattern is checked against the active file. If it matches at
least one newsgroup, the pattern is placed at the end of the site's
``group'' file as an exclude entry. Only one pattern per
exclude command is allowed. Aliases: "-" and
"exc".
- poison pattern
- If the pattern matches at least one crossposted newsgroup the
article will not be accepted even if allowed by an include
statement. Only one pattern per poison command is
allowed.
- help
- Generate a small help message that briefly describes each command. There
is an implied quit with the help command so there is no point in placing
commands after the help command. Alias: "h".
- list
- list all of the current include and exclude patterns in the
sites ``groups'' file. The output is in a format suitable for feeding back
into gup at a later stage if need be. Alias: "l".
- delete pattern
- Delete all include, exclude and poison patterns in
the site's ``groups'' file that match the pattern. ``delete *'' is
an effective way of clearing all current patterns.
- newsgroups pattern
- This command lists out all available newsgroups from the active file that
match the pattern. The list includes the description from the
newsgroups file as well as an indication if the site is currently
subscribed to that group. Only one pattern per newsgroups
command is allowed. Alias: "news".
PROCESSING¶
Gup has a number of processing stages. The initialization stage consists
of changing to the home directory (see the -d option) and opening the logfile
(see the -l option). At this time,
gup sets the tentative reply-to mail
address to the ``backstop'' mail address defined when
gup was compiled
(typically the local news administrator).
The next stage consists of scanning the inbound mail, noting
interesting
mail headers. The most interesting ones are "To:" and
"Reply-To:". When a "To:" header is found it becomes the
tentative reply-to mail address. If a "Reply-To:" header is found it
over-rides any "To:" address to become the new tentative reply-to
mail address. A few others are noted and logged to help track changes.
After all the headers have been processed, the body of the mail is examined for
commands. The first command
must be the
site command. Any other
data results in an error mail sent to the tentative reply-to mail address. If
the
site command contains a name that matches an entry in the
``config'' file, then the tentative reply-to mail address is replaced with the
mail address in the ``config'' file.
The reason for these contortions with tentative reply-to mail addresses is
simply to deal with the problem of working out who to send a mail to in the
event of an error. Ideally they should all go back to the mail address in the
``config'' file, but that information is not known for quite a significant
part of
gup's initial processing.
Once a valid
site command has been accepted,
gup changes to that
site's directory in Sites_directory (see the -s option) making the
Sites_directory and site's directory as necessary. The site's directory name
is the same as the site's name. In the absence of the -s option this will be:
$HOME/sites/$site
Where $HOME is
gup's home directory and $site is the name of the site
being processed.
Gup locks the site then loads the site's current
``groups'' file and any xclusion list if present (see
EXCLUSIONS for
more details).
From this point on
gup accepts any command in any order until either the
end of the mail, a quit command a help command or a serious error during
processing. After all commands have been processed,
gup update's the
site's ``groups'' file if changes have been made. This update includes pruning
any superfluous patterns (unless the -P option is used).
Gup writes the
new patterns to ``groups.new''. It then renames ``groups'' to ``group.old''
and finally renames ``groups.new'' to ``groups''. The result of all this
processing is mailed to the site administrator defined in the ``config'' file.
CONFIG¶
Access to
gup is controlled by the ``config'' file in
gup's home
directory (see the -d option). This file contains one line per site. Each line
contains three white-space separated tokens. The site's name, password and
mail address of the administrator. Blank lines are allowed and comments follow
the ``#'' character.
Gup uses a very simple tokenizer, thus no quoting
or continuation is allow in this file.
The site name and password are used to check an inbound
site command. The
password can be crypted or in
plain-text so permissions should be
carefully set to restrict access. Here's an example of a ``config'' file.
werple Fert5566a__$1 andrew@werple.apana.org.au
torps 34fkr_&&11)Zz zaph@torps.apana.org.au
uunet R_S_1@@*(A-\ news@uunet.uu.net
.test flapper markd
Hopefully this is intuitively obvious...
GROUPS¶
Each site has it's own file of patterns. This file is called ``groups'' and is
located in the site's own directory below the Sites_directory (see the -s
option). This file contains one pattern per line. Exclusion lists have a
preceding ``!'' character. Here's an example:
apana.*
!apana.lists.*
!apana.fido.*
!apana.vortex.*
alt.bbs.waffle
alt.cult-movies
alt.galactic-guide
alt.sport.bowling
aus.*
!aus.ai
!aus.religion
!aus.radio
!aus.stats.s
...
Normally this file should only be changed by
gup, but assuming you cater
for locking, there is no reason why some other process cannot change it too.
Whenever
gup has to apply changes, it renames this file to
``groups.old'' prior to re-writing the ``groups'' file. This gives you some
measure of recovery.
EXCLUSIONS¶
For whatever reason, you may wish to exclude particular groups from a site's
selection list. You can do this by creating the file ``exclude'' in the site's
directory. This file contains newsgroup patterns, one per line, that are used
to filter the ``active'' file when verifying group patterns. The effect of
this is that
gup believes that such groups do not really exist,
therefore a site cannot possibly include them.
DIAGNOSTICS¶
All error conditions are record in the log file and possibly the resultant mail
- depending on the nature of the error. A particular problem that is hard to
detect is when the .forward file invokes
gup incorrectly. If
gup
is not invoked due to such an error, then notification depends on the mailer.
This should only be a problem to watch out for when first installing
gup.
RESTRICTIONS¶
Gup does not understand ``Distribution patterns''. Any such patterns must
be generated and maintained independently of
gup.
BUGS¶
Gup does not know when the
popen(1) fails when
Mail_command
is invoked. This is a limitation of
popen(1). If the
Mail_command is bogus, then the error will be pretty obscure and
dependent on your mailer. stderr is redirected to the logfile prior to
invoking the
Mail_Command so hopefully /bin/sh (used by popen) has
generated an appropriate message.
HISTORY¶
Gup Version 0.3, dated 26 July, 1993.
Initially created by Mark Delany <markd@bushwire.apana.org.au>.
Numerous enhancements and optimizations by Andrew Herbert
<andrew@werple.apana.org.au>.
Currently maintained by Marco d'Itri <md@linux.it>.
The wildmat.c is taken directly from the INN sources, written by Rich Salz
<rsalz@osf.org>.
The rfc822.[ch] parsing routines are taken directly from the newsgates sources,
also written by Rich Salz <rsalz@osf.org>.
SEE ALSO¶
newsfeeds(5),
sendmail(8)