Provided by: gup_0.5.15build1_amd64 bug

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)