.TH GUP 8 "25 July 1993"
.\"
.\" Cobbled together by Mark Delany <markd@bushwire.apana.org.au>
.\" who knows virtually zilch about nroff and I bet it shows...
.\"
.SH NAME
gup \- A
.IR G roup
.IR U pdate
.IR P rogram
that accepts commands by mail to edit a newsgroup subscription
file for subsequent use by news systems such as
.I INN
and
.IR C-News .
.SH SYNTAX
.B gup
.RB [ \-hvP ]
.RB \-a
.IR active_path
.RB [ \-d
.IR home_directory ]
.RB [ \-l
.IR log_path ]
.if n .ti +.6i
.RB [ \-m
.IR reply_headers ]
.RB [ \-n
.IR newsgroups_path ]
.if n .ti +.6i
.RB [ \-s
.IR  sites_directory ]
.RB [ \-M
.IR Mail_command ]
.SH DESCRIPTION
.PP
The sole purpose of
.I gup
is to automate the tedious process of editing group
selection patterns defined in the news configuration 
files (eg:
``newsfeeds'' for
.I INN
and ``sys'' for
.IR C-News ).
.PP
.I 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
.I gup
is installed,
it is quite likely that manual edits of
your ``newsfeeds'' or ``sys'' file will
become a thing of the past.
.PP
.I Gup
is designed to be installed as a mail-server program
that is fed an inbound mail via stdin.
.I Gup
is usually
invoked from a .forward file. Eg:
.PP
.nf
	"|/.../bin/gup \-options...."
.fi
.PP
Each site has an
entry in the ``config'' file containing password
and mail address details
and a group selection file called ``groups'',
see
.BR CONFIG ,
and
.BR GROUPS
for more details.
.PP
The
news administrator of each
site mails commands to
.IR gup .
There are commands to include and exclude group patterns, list the
current patterns for that site and list the available
newsgroups; see
.BR COMMANDS ,
for more details.
.PP
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
.BR PROCESSING ,
for further details.
.PP
.I 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).
.PP
Since each site has to be specifically configured in
.IR gup 's
``config'' file,
access can be restricted to administrator's capable of managing
their own group patterns.
.SH OPTIONS
.PP
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
.I gup
changes directories as it processes a mail (the possible exception
here is the Sites_directory).
.PP
.TP
.BI \-a " active_path"
The path of the active file for your news system.
Before accepting any newsgroup identified in a command,
.I gup
validates the group against the active file. The command is
rejected if no match is found.
.TP
.BI \-d " home_directory"
Defines
.IR gup 's
home directory.
.I Gup
changes to this directory as soon as possible after
starting up. If this option is not present, the current directory
is used.
.I Gup
looks for the ``config'' file in it's home directory.
.TP
.BI \-h
Print out a help message showing the command line options, then
exit.
.TP
.BI \-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
.IR gup 's
home directory; see the \-d option).
.I Gup
must be able to write to this file.
If the
.BI \-l
option is not used, then
.I gup
uses stderr. This is useful for testing purposes, but
is unlikely to be of use in a .forward file.
.TP
.BI \-m " reply_headers"
When
.I 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
.IR gup .
If this path is not an absolute path, then it will be treated as
relative to
.IR gup 's
home directory (see the \-d option).
.TP
.BI \-M " Mail_command"
.I Gup
pipes the rfc822 headers and the body of the mail to the nominated mail
program. Normally, this is configured when
.I 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.
.TP
.BI \-n " newsgroups_path"
If present, the newsgroups file is used to try and find a matching
description of newsgroup when listed.
.TP
.B \-P
Do
.I not
prune superfluous patterns from a site's ``groups'' file. Before
writing the updated ``groups'' file,
.I 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.
.TP
.BI \-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
.IR gup 's
home directory (see the \-d option).
.I Gup
will try and create this directory if it does not exist.
.TP
.B \-v
Print out the version number and various compile-time variables,
then exit.
.SH COMMANDS
.PP
.I 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
.B wildmat (3)
).
In fact,
.I Gup
purposely uses the
.B wildmat
routine from INN to ensure that the pattern matching characteristics
are identical.
.PP
Valid commands are:
.TP
.BI site " sitename password"
This
.I must
be the first command in the mail.
.I sitename
and
.I password
must match an entry in the ``config'' file.
Only one
.I site
command is allowed per mail. Aliases: "open" and "host".
.TP
.B quit
This command stops
.I 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".
.TP
.BI include " pattern"
The
.I pattern
is checked against the active file. If it matches at
least one newsgroup, the
.I pattern
is placed at the end of the site's
``group'' file as an
.I include
entry.
Only one
.I pattern
per
.I include
command is allowed. If the pattern matches anything in the
site's exclusion list (see
.BR EXCLUSIONS )
then the include will fail.
Aliases: "+" and "inc".
.TP
.BI exclude " pattern"
The
.I pattern
is checked against the active file. If it matches at
least one newsgroup, the
.I pattern
is placed at the end of the site's
``group'' file as an
.I exclude
entry.
Only one
.I pattern
per
.I exclude
command is allowed.
Aliases: "\-" and "exc".
.TP
.BI poison " pattern"
If the
.I pattern
matches at least one crossposted newsgroup the article will not be accepted
even if allowed by an
.I include
statement.
Only one
.I pattern
per
.I poison
command is allowed.
.TP
.B 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".
.TP
.B list
list all of the
current
.I include
and
.I exclude
patterns in the sites ``groups'' file.
The
output is in a format suitable for feeding back into
.I gup
at a later stage if need be.
Alias: "l".
.TP
.BI delete " pattern"
Delete all
.IR include ,
.I exclude
and
.I poison
patterns in the site's ``groups'' file
that match the
.IR pattern .
``delete *'' is an effective way
of clearing all current patterns.
.TP
.BI newsgroups " pattern"
This command lists out all available newsgroups from the
active file that match the
.IR 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
.I pattern
per
.I newsgroups
command is allowed.
Alias: "news".
.SH PROCESSING
.PP
.I 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,
.I gup
sets the tentative reply-to mail address to the ``backstop'' mail
address
defined when 
.I gup
was compiled (typically the local news
administrator).
.PP
The next stage consists of scanning the inbound mail, noting
.I 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.
.PP
After all the headers have been processed, the body of the mail
is examined for commands. The first command
.B must
be the
.I site
command. Any other data results
in an error mail sent to the tentative reply-to mail address.
If the 
.I 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.
.PP
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
.IR gup 's
initial processing.
.PP
Once a valid
.I site
command has been accepted,
.I 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:
.nf

	$HOME/sites/$site

.fi
Where $HOME is
.IR gup 's
home directory and $site is the name of the site being processed.
.I Gup
locks the site
then loads the site's current ``groups'' file and any
xclusion list if
present (see
.BR EXCLUSIONS
for more details).
.PP
From this point on
.I 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,
.I 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).
.I 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.
.SH CONFIG
.PP
Access to
.I gup
is controlled by the ``config'' file in
.IR 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.
.I Gup
uses a very simple tokenizer, thus no quoting or continuation is allow
in this file.
.PP
The site name and password are used to check an inbound
.I site
command. The password can be crypted or in
.I plain-text
so permissions should be carefully set to restrict access. Here's an
example of a ``config'' file.
.nf

	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

.fi
Hopefully this is intuitively obvious...
.SH GROUPS
.PP
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:
.nf

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
\|.\|.\|.

.fi
Normally this file should only be changed by
.IR gup ,
but assuming you cater for locking, there is no reason why
some other process cannot change it too. Whenever
.I 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.
.SH EXCLUSIONS
.PP
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
.I gup
believes that such groups do not really exist, therefore a site
cannot possibly include them.
.SH DIAGNOSTICS
.PP
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
.I gup
incorrectly. If
.I 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
.IR gup .
.SH RESTRICTIONS
.PP
.I Gup
does not understand ``Distribution patterns''. Any such patterns
must be generated and maintained independently
of
.IR gup .
.SH BUGS
.PP
.I Gup
does not know when the
.IR popen (1)
fails when
.I Mail_command
is invoked. This is a limitation of
.IR popen (1).
If the
.I 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
.I Mail_Command
so hopefully /bin/sh (used by popen) has
generated an appropriate message.
.SH HISTORY
.PP
.I Gup
Version 0.3, dated 26 July, 1993.
.PP
Initially created by 
Mark Delany
<markd@bushwire.apana.org.au>.
.PP
Numerous enhancements and optimizations by Andrew Herbert
<andrew@werple.apana.org.au>.
.PP
Currently maintained by Marco d'Itri <md@linux.it>.
.PP
The wildmat.c is taken directly from the INN sources, written
by Rich Salz <rsalz@osf.org>.
.PP
The rfc822.[ch] parsing routines are taken directly from the
newsgates sources, also written by Rich Salz <rsalz@osf.org>.
.SH "SEE ALSO"
.IR newsfeeds (5),
.IR sendmail (8)