|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.|
|Defines gups 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 its home directory.|
|-h||Print out a help message showing the command line options, then exit.|
|A record of all significant requests are written to this file. If the path is relative, then it will be relative to gups 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.|
|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 gups home directory (see the -d option).|
|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.|
|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 sites 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.|
|Each sites 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 gups 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 sites group file as an include entry. Only one pattern per include command is allowed. If the pattern matches anything in the sites 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 sites 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 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 and exclude patterns in the sites 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 gups initial processing.
Once a valid site command has been accepted, gup changes to that sites directory in Sites_directory (see the -s option) making the Sites_directory and sites directory as necessary. The sites directory name is the same as the sites name. In the absence of the -s option this will be:Where $HOME is gups home directory and $site is the name of the site being processed. Gup locks the site then loads the sites 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 updates the sites 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.
Access to gup is controlled by the config file in gups home directory (see the -d option). This file contains one line per site. Each line contains three white-space separated tokens. The sites 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 is in plain-text so permissions should be carefully set to restrict access. Heres an example of a config file.Hopefully this is intuitively obvious...
Each site has its own file of patterns. This file is called groups and is located in the sites own directory below the Sites_directory (see the -s option). This file contains one pattern per line. Exclusion lists have a preceding ! character. Heres 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.
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
For whatever reason, you may wish to exclude particular groups from a sites selection list. You can do this by creating the file exclude in the sites 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 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 <firstname.lastname@example.org>.
Numerous enhancements and optimizations by Andrew Herbert <email@example.com>.
The wildmat.c is taken directly from the INN sources, written by Rich Salz <firstname.lastname@example.org>.
The rfc822.[ch] parsing routines are taken directly from the newsgates sources, also written by Rich Salz <email@example.com>.
|-->||GUP (1)||25 July 1993|