--- name: "gup" section: "8" platform: "linux" package: "gup" version: "0.5.17" release: "Debian 12 (Bookworm)" platforms: ["linux"] url: "https://new.carta.tech/gup/8" --- # gup(8) 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. ## NAME gup - A *G*roup *U*pdate *P*rogram 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 \. 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 \. ## SEE ALSO [*newsfeeds*(5)](/newsfeeds/5.md), [*sendmail*(8)](/sendmail/8.md)