Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
GUP(1)			    General Commands Manual			GUP(1)

       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  pat-
       terns  for  that	 site and list the available newsgroups; see COMMANDS,
       for more	details.

       The results are normally	mailed back to the site's configured  adminis-
       trator.	 However  under	 some circumstances, the results are mailed to
       the originator or the local administrator; see PROCESSING, for  further

       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	appro-
       priately	formatted file for your	particular news	system.	(One  is  pro-
       vided 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	possi-
       ble exception here is the Sites_directory).

       -a active_path
	      The  path	 of  the active	file for your news system.  Before ac-
	      cepting 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	direc-
	      tory (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	match-
	      ing 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  in-
	      tensive  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 lo-
	      cated 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 di-
	      rectory 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 con-
       tinuation is allowed. Many of the commands accept a pattern as a	param-
       eter.   This  pattern  is identical to the format of the	wildmat() pat-
       tern; see wildmat (3) ).	 In fact, Gup purposely	uses the wildmat  rou-
       tine  from  INN to ensure that the pattern matching characteristics are

       Valid commands are:

       site sitename password
	      This must	be the first command in	the mail.  sitename and	 pass-
	      word  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".

       help   Generate a small help message that briefly describes  each  com-
	      mand.   There  is	an implied quit	with the help command so there
	      is no point in placing commands after the	help command.	Alias:

       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 and exclude 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	 news-
	      groups command is	allowed.  Alias: "news".

       Gup  has	 a  number of processing stages. The initialization stage con-
       sists 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 interest-
       ing mail	headers. The most interesting ones are "TO:" and  "REPLY-TO:".
       When a "TO:" header is found it becomes the tentative reply-to mail ad-
       dress. 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  ex-
       amined  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  re-
       placed 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_di-
       rectory 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


       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  up-
       date's  the site's ``groups'' file if changes have been made.  This up-
       date 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	direc-
       tory  (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 al-
       lowed 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 is in plain-text so	permissions should be carefully	set to
       restrict	access.	Here's an example of a ``config'' file.

	    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.	Exclu-
       sion 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	resul-
       tant mail - depending on	the nature of the error. A particular  problem
       that  is	 hard  to  detect is when the .forward file invokes gup	incor-
       rectly. If is not invoked due to	such an	error, then  notification  de-
       pends  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 <andrew@wer->.

       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				GUP(1)


Want to link to this manual page? Use this URL:

home | help