GUP(1)

📦 version 0.5.15build1, in ubuntu jammy

🌸 GUP(1) — General Commands Manual 🌸

okay bestie, welcome to gup, section 1 of the General Commands Manual 💖 this is the Group Update Program and she is literally the moment.

✨ 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 👑

okay so 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). no more manual editing era, we're automating it, periodt. 🎀

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. and honestly? once gup is installed, it is quite likely that manual edits of your newsfeeds'' or sys'' file will become a thing of the past. iconic behavior, no cap. ✨

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

⚠️ bestie listen: 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). so like, she does the editing, but you still gotta run the script. iykyk.

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). like, fr fr, just use absolute paths and save yourself the chaos. 💅

-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. bye bestie 👋
-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. slay, who are you really 🪞

🌈 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 ✨

okay bestie so gup does this in stages, like a little ritual, and you're gonna wanna know the order 💅

The initialization stage is: changing to the home directory (that's the -d option, iykyk) and opening the logfile (that's -l). Right at this moment, gup sets the tentative reply-to mail address to the backstop mail address that got defined when gup was compiled — which is typically the local news administrator. very "we don't know who you are yet so we're defaulting to the boss" energy.

Then comes the scanning stage: gup reads the inbound mail and takes notes on the interesting headers 👀 The most interesting ones are To: and Reply-To:. The way it works:

when a To: header shows up, it becomes the tentative reply-to mail address
if a Reply-To: header shows up, it over-rides any To: address and becomes the new tentative reply-to mail address
a few others get noted and logged too, just to help track changes 🦋

Once all the headers are done, gup goes through the body of the mail looking for commands. The first command must be the site command. Any other data = an error mail sent to the tentative reply-to mail address. sad but fair 😭 And if that site command has a name matching an entry in the config file? Then the tentative reply-to mail address gets replaced with the mail address from the config file. slay.

So like, why all these contortions with tentative reply-to addresses?? basically it's the problem of figuring out who to mail when something breaks. Ideally every error would go back to the mail address in the config file, but that info just isn't known for a pretty significant chunk of gup's initial processing. it's giving "we're doing our best" 🫶

Once a valid site command has been accepted, gup changes to that site's directory in Sites_directory (that's the -s option), making the Sites_directory and the 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 (peep EXCLUSIONS for more, bestie).

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. no cap. After all commands have been processed, gup updates the site's groups file if changes have been made. That update includes pruning any superfluous patterns (unless the -P option is used, which is the whole point of -P). Gup writes the new patterns to groups.new. Then it renames groups to group.old and finally renames groups.new to groups. And the result of all this processing gets 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 has one line per site ✨ and each line contains three white-space separated tokens:

the site's name
the password
the mail address of the administrator

Blank lines are allowed, and comments follow the # character. Gup uses a very simple tokenizer, so no quoting and no continuation are allowed in this file — it's not fancy, it's just vibes.

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 — seriously bestie, lock that down 🔒

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... 👑 (that's the manual talking, not me, but honestly? it is)

🎀 GROUPS 🎀

Each site has it's own file of patterns. This file is called groups and it lives in the site's own directory, below the Sites_directory (see the -s option). One pattern per line, no exceptions. 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. That gives you some measure of recovery, which is the closest thing to a safety net you're getting here 🧚

🦋 EXCLUSIONS 🦋

For whatever reason, you may wish to exclude particular groups from a site's selection list. Mood. 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 such groups do not really exist — therefore a site cannot possibly include them. they're gone, deleted, not on the list 💀

🌸 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. so like, watch the first install, then chill 🫶

⭐ RESTRICTIONS ⭐

Gup does not understand Distribution patterns. Any such patterns must be generated and maintained independently of gup. periodt. gup will not be doing that for you, bestie 😭

💀 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. fingers crossed fr fr 🙈

👑 HISTORY 👑

Gup Version 0.3, dated 26 July, 1993. (an icon, honestly)

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)

and that's the whole page bestie 🎀 this one's dated 25 July 1993 and it's the GUP(1) page — a true vintage slay, still serving after all these years 💜✨

📦 where this page comes from

ubuntu jammy: gup 0.5.15build1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms