Provided by: gup_0.5.15build1_amd64 
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)
25 July 1993 GUP(1)