Man Linux: Main Page and Category List


       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.


       gup [-hvP] -a active_path [-d home_directory] [-l log_path]
             [-m reply_headers] [-n newsgroups_path]
             [-s sites_directory] [-M Mail_command]


       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

       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.

            "|/.../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 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

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


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


       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:


       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 ‘‘’’. It then
       renames ‘‘groups’’ to ‘‘group.old’’ and finally renames  ‘‘’’
       to ‘‘groups’’.  The result of all this processing is mailed to the site
       administrator defined in the ‘‘config’’ file.


       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

       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’’

            werple    Fert5566a__$1
            torps     34fkr_&&11)Zz
            uunet     R_S_1@@*(A-\
            .test     flapper        markd

       Hopefully this is intuitively obvious...


       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:


       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.


       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.


       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.


       Gup does not understand ‘‘Distribution patterns’’.  Any  such  patterns
       must be generated and maintained independently of gup.


       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.


       Gup Version 0.3, dated 26 July, 1993.

       Initially created by Mark Delany <>.

       Numerous   enhancements   and   optimizations   by    Andrew    Herbert

       Currently maintained by Marco d’Itri <>.

       The  wildmat.c  is taken directly from the INN sources, written by Rich
       Salz <>.

       The rfc822.[ch] parsing routines are taken directly from the  newsgates
       sources, also written by Rich Salz <>.


       newsfeeds(5), sendmail(8)

                                 25 July 1993