SUP(1)

📦 in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

SUP(1) 💖 sup — General Commands Manual — software upgrade protocol ✨

NAME 🎀

sup — software upgrade protocol

SYNOPSIS ✨

sup [ flags ] [ supfile ] [ collection ...]

DESCRIPTION 💅

okay bestie, gather round, because Sup is literally the program you use for upgrading collections of files from other machines to your machine. You run sup, the client program, and it talks over the network using IP/TCP to a file server process. That file server process cooperates with sup to figure out which files of the collection need to be upgraded on your machine. no cap.

Sup collections can have multiple releases. One use for such releases is to provide different versions of the same files. At CMU, for example, system binaries have alpha, beta and default release corresponding to different staging levels of the software. We also use release names default and minimal to provide complete releases or subset releases. In both of these cases, it only makes sense to sup one release of the collections. Releases have also been used in private or external sups to provide subsets of collections where it makes sense to pick up several of the releases. For example the Mach 3.0 kernel sources has a default release of machine independent sources and separate releases of machine dependent sources for each supported platform. periodt.

In performing an upgrade, the file server constructs a list of files included in the specified release of the collection. The list is sent to your machine, which determines which files are needed. Those files are then sent from the file server. It will be most useful to run sup as a daemon each night so you will continually have the latest version of the files in the needed collections. main character energy tbh.

The only required argument to sup is the name of a supfile. It must either be given explicitly on the command line, or the -s flag must be specified. If the -s flag is given, the system supfile will be used and a supfile command argument should not be specified. The list of collections is optional and if specified will be the only collections upgraded. The following flags affect all collections specified:

  • -s — as described above. 💅
  • -t — when this flag is given, sup will print the time that each collection was last upgraded, rather than performing actual upgrades.
  • -u — when this flag is given, sup will not try to restore the user access and modified times of files in the collections from the server.
  • -S — operate silently printing messages only on errors.
  • -N — Sup will trace network messages sent and received that implement the sup network protocol.
  • -P — Sup will use a set of non-privileged network ports reserved for debugging purposes.

The remaining flags affect all collections unless an explicit list of collections are given with the flags. Multiple flags may be specified together that affect the same collections. For the sake of convenience, any flags that always affect all collections can be specified with flags that affect only some collections. For example, sup -sde=coll1,coll2 would perform a system upgrade, and the first two collections would allow both file deletions and command executions. Note that this is not the same command as sup -sde=coll1 coll2, which would perform a system upgrade of just the coll2 collection and would ignore the flags given for the coll1 collection. iykyk.

  • -a — all files in the collection will be copied from the repository, regardless of their status on the current machine. Because of this, it is a very expensive operation and should only be done for small collections if data corruption is suspected and has been confirmed. In most cases, the -o flag should be sufficient.
  • -b — if the -b flag is given, or the backup supfile option is specified, the contents of regular files on the local system will be saved before they are overwritten with new data. The file collection maintainer can designate specific files to be worthy of backing up whenever they are upgraded. However, such backup will only take place if you specify this flag or the backup option to allow backups for a file collection on your machine. The backup mechanism will create a copy of the current version of a file immediately before a new copy is received from the file server; the copy is given the same name as the original file but is put into a directory called BACKUP within the directory containing the original file. For example, /usr/sas/src/foo.c would have a backup copy called /usr/sas/src/BACKUP/foo.c. There is no provision for automatically maintaining multiple old versions of files; you would have to do this yourself. 🫶
  • -B — the -B flag overrides and disables the -b flag and the backup supfile option.
  • -d — files that are no longer in the collection on the repository will be deleted if present on the local machine and were put there by a previous sup. This may also be specified in a supfile with the delete option.
  • -D — the -D flag overrides and disables the -d flag and the delete supfile option.
  • -e — Sup will execute commands sent from the repository that should be run when a file is upgraded. If the -e flag is omitted, Sup will print a message that specifies the command to execute. This may also be specified in a supfile with the execute option.
  • -E — the -E flag overrides and disables the -e flag and the execute supfile option.
  • -f — a list-only upgrade will be performed. Messages will be printed that indicate what would happen if an actual upgrade were done.
  • -k — Sup will check the modification times of files on the local disk before updating them. Only files which are newer on the repository than on the local disk will be updated; files that are newer on the local disk will be kept as they are. This may also be specified in a supfile with the keep option.
  • -K — the -K flag overrides and disables the -k flag and the keep supfile option.
  • -l — normally, sup will not upgrade a collection if the repository is on the same machine. This allows users to run upgrades on all machines without having to make special checks for the repository machine. If the -l flag is specified, collections will be upgraded even if the repository is local.
  • -m — normally, sup uses standard output for messages. If the -m flag is given, sup will send mail to the user running sup, or a user specified with the notify supfile option, that contains messages printed by sup.
  • -M <user> — like -m but send mail to the specified user.
  • -o — Sup will normally only upgrade files that have changed on the repository since the last time an upgrade was performed. That is, if the file in the repository is newer than the date stored in the when file on the client. The -o flag, or the old supfile option, will cause sup to check all files in the collection for changes instead of just the new ones.
  • -O — the -O flag overrides and disables the -o flag and the old supfile option.
  • -z — normally sup transfers files directly without any other processing, but with the -z flag, or the compress supfile option, sup will compress the file before sending it across the network and uncompress it and restore all the correct file attributes at the receiving end.
  • -Z — the -Z flag overrides and disables the -z flag and the compress supfile option.
  • -v — normally, sup will only print messages if there are problems. This flag causes sup to also print messages during normal progress showing what sup is doing.

✨ SETTING UP UPGRADES ✨

okay bestie, listen up, this is the part where you actually set things up 💖

Every single file collection you wanna upgrade needs a base directory, and inside that base directory there's gotta be a subdirectory called sup that the sup program itself is gonna use. Don't stress about making it — it'll get created automatically if you don't. Sup will just yeet subdirectories and files in there as needed, no biggie. 🎀

Sup goes looking for a subdirectory with the same name as the collection inside the sup subdirectory of the base directory. If that thing exists, it can contain any of these files:

  • when.<rel-suffix> — this one gets auto-updated by sup whenever a collection gets successfully upgraded 🌸. It holds the time that the file server (or maybe supscan, who knows) created the list of files in the upgrade list. Sup sends that time to the file server so it can generate the list of files that changed on the repository machine.
  • refuse — a list of files and directories, one per line, that the client literally does not care about and doesn't want upgraded 🙅♀️
  • lock — sup uses this to lock a collection while it's being upgraded. It grabs exclusive access to the lock file using flock(2), which stops more than one sup from upgrading the same collection at the same time. no fighting, one at a time, periodt 💅
  • last.<rel-suffix> — a list of files and directories, one per line, that sup has upgraded in the past 👑. This is the receipts it checks when the delete option, or the -d flag, is used to find files that were previously upgraded but aren't in the collection anymore and should be deleted.

Every file collection also has to be described in one or more supfiles. When sup runs, it reads the supfile you told it about to figure out which file collections and releases to upgrade. Each collection-release set is one single line of text in the supfile, and that line must have the name of the collection, plus maybe one or more options separated by spaces. Here are the options, bestie:

  • release=releasename — if a collection has multiple releases, you gotta say which one you want. You can only specify one release per line, so if you want multiple releases from the same collection, you're gonna write that collection more than once 🙈. In that case, use the use-rel-suffix option in the supfile to keep the last and when files for the two releases separate.
  • base=directory — the usual default name of the base directory for a collection is described below (peep FILES). If you want a different directory name, use this option and give it the directory you want.
  • prefix=directory — each collection can also have an associated prefix directory, which gets used instead of the base directory to decide where files inside the collection get placed.
  • host=hostname
  • hostbase=directory — system collections are supported by the system maintainers, and sup will automatically figure out the host machine's name and the base directory on that machine. But you can also upgrade private collections — you just use these options to specify the hostname of the machine holding the files, and the directory used as the base directory for the file server on that machine. Details on setting up a file collection are in the section below. 🦋
  • login=accountid
  • password=password
  • crypt=key — files on the file server might be protected, and network transmissions might be encrypted. This stops unauthorized access to files via sup 🔒. When files aren't accessible to the default account (like, say, the anon anonymous account), you can specify an alternative accountid and password for the file server to use on the repository host. Network transmission of the password will always be encrypted. You can also have the actual file data encrypted by specifying a key — the file collection on the repository has to specify the same key, or else sup will not be able to upgrade files from that collection, full stop. In this case, the default account used by the file server on the repository machine will be the owner of the encryption key file (see FILES) instead of the anon anonymous account.
  • notify=address — if you use the -m option to get log messages by mail, you can have that mail sent to a different user, possibly on another host, than the user running the sup program 📬. Messages go to the address you specify, which can be any legal netmail address. In particular, a project maintainer can be designated to receive mail for that project's file collection from all users running sup to upgrade that collection.
  • backup — as described above under the -b flag.
  • delete — as described above under the -d flag.
  • execute — as described above under the -e flag.
  • keep — as described above under the -k flag.
  • old — as described above under the -o flag.
  • use-rel-suffix — causes the release name to be used as a suffix to the last and when files 💫. This is necessary whenever you're supping more than one release in the same collection.

✨ PREPARING A FILE COLLECTION REPOSITORY ✨

okay bestie, plot twist time: somebody has to actually build the thing first. 💖 A set of files residing on a repository must be prepared before sup client processes can upgrade those files. no prep, no slay, that's just how it is.

So here's the vibe check on what a collection needs:

  • The collection must be given a name and a base directory. 🎀
  • If it is a private collection, client users must be told the name of the collection, repository host, and base directory — these will be specified in the supfile via the host and hostbase options.
  • For a system-maintained file collection, entries must be placed into the host list file and directory list file as described in supservers(8).

Then, within the base directory, a subdirectory must be created called sup. 🌸 Within this directory there must be a subdirectory for each collection using that base directory, whose name is the name of the collection. Within each of these directories will be a list file and possibly a prefix file, a host file, an encryption key file, a log file and a scan file. The filenames are listed under FILES below. (Yes we get there. patience, queen. 💅)

prefix 🦋

Normally, all files in the collection are relative to the base directory. This file contains a single line which is the name of a directory to be used in place of the base directory for file references. literally one line, that's it, iconic behaviour.

host 🌈

Normally, all remote host machines are allowed access to a file collection. If you wish to restrict access to specific remote hosts for this collection, put each allowed hostname on a separate line of text in this file. If a host has more than one name, only one of its names needs to be listed. The name LOCAL can be used to grant access to all hosts on the local network. The host name may be a numeric network address or a network name. If a crypt appears on the same line as the host name, that crypt will be used for that host. Otherwise, the crypt appearing in the crypt file, if any, will be used. iykyk. 👑

crypt 🔐

If you wish to use the sup data encryption mechanism, create an encryption file containing, on a single line of text, the desired encryption key. Client processes must then specify the same key with the crypt option in the supfile or they will be denied access to the files. 🚫 In addition, actual network transmission of file contents and filenames will be encrypted. very much the locked-girlies-only door.

list 📝

This file describes the actual list of files to be included in this file collection, in a format described below. (it's the main character of this whole section, fr fr.)

releases 🗂️

This file describes any releases that the collection may have. Each line starts with the release name and then may specify any of the following files:

  • prefix=<dirname> to use a different parent directory for the files in this release.
  • list=<listname> to specify the list of files in the release.
  • scan=<scanfile> must be used in multi-release collections that are scanned to keep the scan files for the different releases separate.
  • host=<hostfile> to allow different host restrictions for this release.
  • next=<release> used to chain releases together. This has the effect of making one release be a combination of several other releases. If the same file appears in more than one chained release, the first one found will be used.

If these files are not specified for a release the default names: prefix,list,scan and host will be used.

scan 🔍

This file, created by supscan, is the list of filenames that correspond to the instructions in the list file. The scan file is only used for frequently updated file collections; it makes the file server run much faster. See supservers(8) for more information.

lock 🔒

As previously mentioned, this file is used to indicate that the collection should be locked while upgrades are in progress. All file servers will try to get shared access to the lock file with flock(2).

logfile 📜

If a log file exists in the collection directory, the file server will append the last time an upgrade was successfully completed, the time the last upgrade started and finished, and the name of the host requesting the upgrade. receipts, basically.

It should be noted that sup allows several different named collections to use the same base directory. Separate encryption, remote host access, and file lists are used for each collection, since these files reside in subdirectories <basedir>/sup/<coll.name>. sharing a house, keeping separate bedrooms. 💅

The list file is a text file with one command on each line. Each command contains a keyword and a number of operands separated by spaces. All filenames in the list file are evaluated on the repository machine relative to the host's base directory, or prefix directory if one is specified, and on your machine with respect to the base, or prefix, directory for the client. The filenames below (except exec-command) may all include wild-cards and meta-characters as used by csh(1) including *, ?, [...], and {...}. The commands are:

upgrade filename ...

The specified file(s) (or directories) will be included in the list of files to be upgraded. If a directory name is given, it recursively includes all subdirectories and files within that directory. 🫶

always filename ...

The always command is identical to upgrade, except that omit and omitany commands do not affect filenames specified with the always command. it said what it said and it's not taking it back.

omit filename ...

The specified file(s) (or directories) will be excluded from the list of files to be upgraded. For example, by specifying upgrade /usr/vision and omit /usr/vision/exp, the generated list of files would include all subdirectories and files of /usr/vision except /usr/vision/exp (and its subdirectories and files). not me gatekeeping /usr/vision/exp. 🙈

omitany pattern ...

The specified patterns are compared against the files in the upgrade list. If a pattern matches, the file is omitted. The omitany command currently supports all wild-card patterns except {...}. Also, the pattern must match the entire filename, so a leading */, or a trailing /*, may be necessary in the pattern. lowkey picky but we respect it.

backup filename ...

The specified file(s) are marked for backup; if they are upgraded and the client has specified the backup option in the corresponding line of the supfile, then backup copies will be created as described above. Directories may not be specified, and no recursive filename construction is performed; you must specify the names of the specific files to be backed up before upgrading. one by one, bestie. no shortcuts.

noaccount filename ...

The accounting information of the specified file(s) will not be preserved by sup. Accounting information consists of the owner, group, mode and modified time of a file.

The specified file(s) are to be treated as symbolic links and will be transferred as such and not followed. By default, sup will follow symbolic links. 🧚

All symbolic links in the specified directory and its subdirectories are to be treated as symbolic links. That is, the links will be transferred and not the files to which they point. the whole tree, links only, periodt.

execute exec-command (filename ...)

The exec-command you specified will be executed on the client process whenever any of the files listed in parentheses are upgraded. A special token, %s, may be specified in the exec-command and will be replaced by the name of the file that was upgraded. For example, if you say execute ranlib %s (libc.a), then whenever libc.a is upgraded, the client machine will execute ranlib libc.a. As described above, the client must invoke sup with the -e flag to allow the automatic execution of command files. 🔥

include listfile ...

The specified listfiles will be read at this point. This is useful when one collection subsumes other collections; the larger collection can simply specify the listfiles for the smaller collections contained within it. nesting doll energy. 🎀

The order in which the command lines appear in the list file does not matter. Blank lines may appear freely in the list file. breathe, babe, it's not that serious.

📁 FILES 📁

Files on the client machine for sup:

  • /etc/supfiles/coll.list — supfile used for -s flag
  • /etc/supfiles/coll.what — supfile used for -s flag when -t flag is also specified
  • /etc/supfiles/coll.host — host name list for system collections
  • <base-directory>/sup/<collection>/last<.release> — recorded list of files in collection as of last upgrade
  • <base-directory>/sup/<collection>/lock — file used to lock collection
  • <base-directory>/sup/<collection>/refuse — list of files to refuse in collection
  • <base-directory>/sup/<collection>/when<.release> — recorded time of last upgrade
  • /usr/sup/<collection> — default base directory for file collection

Files needed on each repository machine for the file server:

  • /etc/supfiles/coll.dir — base directory list for system collections
  • <base-directory>/sup/<collection>/crypt — data encryption key for a collection. the owner of this file is the default account used when data encryption is specified
  • <base-directory>/sup/<collection>/host — list of remote hosts allowed to upgrade a collection
  • <base-directory>/sup/<collection>/list — list file for a collection
  • <base-directory>/sup/<collection>/lock — lock file for a collection
  • <base-directory>/sup/<collection>/logfile — log file for a collection
  • <base-directory>/sup/<collection>/prefix — file containing the name of the prefix directory for a collection
  • <base-directory>/sup/<collection>/scan — scan file for a collection
  • /usr/<collection> — default base directory for a file collection

👀 SEE ALSO 👀

  • supservers(8)
  • The SUP Software Upgrade Protocol, S. A. Shafer, CMU Computer Science Department, 1985.

🌈 EXAMPLE 🌈

<example>

💀 BUGS 💀

The encryption mechanism should be strengthened, although it's not trivial. 💀

sup can delete files it should not with the delete option. This is because in the delete pass, it tries to delete all files in the old list that don't exist in the new list. This is a problem when a directory becomes a symlink to a hierarchy that contains the same names. Then sup will cross the symlink and start deleting files and directories from the destination. This is not easily fixed.

bestie. do not use sup with symlink/rsymlink and the delete option at the same time, or be careful! 🚨 like genuinely, this is the one where we stop giggling and start reading.

and that's the whole page, angel 🫶 this lil' page is from 10/01/08 and it lives in section SUP(1) — go forth and sync responsibly. 💖✨

📦 where this page comes from