InfoMagic Source Code 1993 July

home *** CD-ROM | disk | FTP | other *** search

/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / mach / doc / unpublished / sup.1.Z / sup.1

Wrap

Text File | 1992-09-01 | 22.2 KB | 487 lines

SUP(1) UNIX Programmer's Manual SUP(1) NAME sup - software upgrade protocol SYNOPSIS sup [ _f_l_a_g_s ] [ _s_u_p_f_i_l_e ] [ _c_o_l_l_e_c_t_i_o_n ...] DESCRIPTION _S_u_p is a program used for upgrading collections of files from other machines to your machine. You execute _s_u_p, the _c_l_i_e_n_t program, which talks over the network using IP/TCP to a _f_i_l_e _s_e_r_v_e_r and possibly a _n_a_m_e _s_e_r_v_e_r process. The name server process determines appropriate _r_e_p_o_s_i_t_o_r_y machines from which to request upgrades. The file server process cooperates with _s_u_p to determine which files of the collec- tion need to be upgraded on your machine. In performing an upgrade, the file server constructs a list of files included in 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 _s_u_p as a daemon each night so you will continually have the latest version of the files in the needed collections. The only required argument to _s_u_p 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 speci- fied: -s As described above. -t When this flag is given, _s_u_p will print the time that each collection was last upgraded, rather than perform- ing actual upgrades. -N _S_u_p will trace network messages sent and received that implement the _s_u_p 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 expli- cit list of collections are given with the flags. Multiple flags may be specified together that affect the same collec- tions. For the sake of convience, 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. -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 been confirmed. In most cases, the -o flag should be sufficient. -b If the -b flag if 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 repo- sitory will be deleted if present on the local machine. 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 _l_i_s_t-_o_n_l_y upgrade will be performed. Messages will be printed that indicate what would happen if an actual upgrade were done. -l Normally, _s_u_p 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, _s_u_p used standard output for messages. If the -m flag if given, _s_u_p will send mail to the user running _s_u_p, or a user specified with the notify sup- file option, that contains messages printed by _s_u_p. -o _S_u_p will normally only upgrade files that have changed on the repository since the last time an upgrade was performed. The -o flag, or the old supfile option, will cause _s_u_p 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. -v Normally, _s_u_p will only print messages if there are problems. This flag causes _s_u_p to also print messages during normal progress showing what _s_u_p is doing. SETTING UP UPGRADES Each file collection to be upgraded must have a _b_a_s_e _d_i_r_e_c_- _t_o_r_y which contains a subdirectory called sup that will be used by the _s_u_p program; it will be created automatically if you do not create it. _S_u_p will put subdirectories and files into this directory as needed. _S_u_p will look for a subdirectory with the same name as the collection within the sup subdirectory of the _b_a_s_e _d_i_r_e_c_- _t_o_r_y. If it exists it may contain any of the following files: when This file is automatically updated by _s_u_p when a col- lection is successfully upgraded and contains the time that the file server, or possibly _s_u_p_s_c_a_n, created the list of files in the upgrade list. _S_u_p will send this time to the file server for generating the list of files that have been changed on the repository machine. refuse This file contains a list of files and directories, one per line, that the client is not interested in that should not be upgraded. lock This file is used by _s_u_p to lock a collection while it is being upgraded. _S_u_p will get exclusive access to the lock file using _f_l_o_c_k(2), preventing more than one _s_u_p from upgrading the same collection at the same time. last This file contains a list of files and directories, one per line, that have been upgraded by _s_u_p in the past. This information is used when the delete option, or the -d flag is used to locate files previously upgraded that are no longer in the collection that should be deleted. Each file collection must also be described in one or more supfiles. When _s_u_p is executed, it reads the specified sup- file to determine what file collections to upgrade. Each collection is described by a single line of text in the sup- file; this line must contain the name of the collection, and possibly one or more options separated by spaces. The options are: base=_d_i_r_e_c_t_o_r_y The usual default name of the base directory for a col- lection is described below (see FILES); if you want to specify another directory name, use this option speci- fying the desired directory. prefix=_d_i_r_e_c_t_o_r_y Each collection may also have an associated _p_r_e_f_i_x _d_i_r_e_c_t_o_r_y which is used instead of the base directory for references to files within the collection. host=_h_o_s_t_n_a_m_e hostbase=_d_i_r_e_c_t_o_r_y _S_y_s_t_e_m collections are supported by the system main- tainers, and _s_u_p will automatically find out the name of the host machine and base directory on that machine. However, you can also upgrade _p_r_i_v_a_t_e collections; you simply specify with these options the _h_o_s_t_n_a_m_e of the machine containing the files and the _d_i_r_e_c_t_o_r_y used as a base directory for the file server on that machine. Details of setting up a file collection are given in the section below. login=_a_c_c_o_u_n_t_i_d password=_p_a_s_s_w_o_r_d crypt=_k_e_y Files on the file server may be protected, and network transmissions may be encrypted. This prevents unau- thorized access to files via _s_u_p. When files are not accessible to the default account (e.g. the anon anonymous account), you can specify an alternative _a_c_c_o_u_n_t_i_d and _p_a_s_s_w_o_r_d for the file server to use on the repository host. Network transmission of the pass- word will be always be encrypted. You can also have the actual file data encrypted by specifying a _k_e_y; the file collection on the repository must specify the same key or else _s_u_p will not be able to upgrade files from that collection. 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) rather than the anon anonymous account. notify=_a_d_d_r_e_s_s If you use the -m option to receive log messages by mail, you can have the mail sent to different user, possibly on another host, than the user running the sup program. Messages will be sent to the specified _a_d_d_r_e_s_s, 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 _s_u_p 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. old As described above under the -o flag. PREPARING A FILE COLLECTION REPOSITORY A set of files residing on a repository must be prepared before _s_u_p client processes can upgrade those files. The collection must be given a _n_a_m_e and a _b_a_s_e _d_i_r_e_c_t_o_r_y. 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 _s_u_p_f_i_l_e_s_r_v(8). Within the base directory, a subdirectory must be created called sup . Within this directory there must be a subdirec- tory 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. 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. 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. crypt If you wish to use the _s_u_p 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 con- tents and filenames will be encrypted. list This file describes the actual list of files to be included in this file collection, in a format described below. scan This file, created by _s_u_p_s_c_a_n, 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 _s_u_p_s_e_r_v_e_r_s(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 _f_l_o_c_k(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 request- ing the upgrade. It should be noted that _s_u_p allows several different named collections to use the same base directory. Separate encryption, remote host access, and file lists are then used for each collection. 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, direc- tory for the client. The _f_i_l_e_n_a_m_e_s below (except _e_x_e_c- _c_o_m_m_a_n_d) may all include wild-cards and meta-characters as used by _c_s_h(1) including *, ?, [...], and {...}. The com- mands are: upgrade _f_i_l_e_n_a_m_e ... 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 subdirec- tories and files within that directory. always _f_i_l_e_n_a_m_e ... The always command is identical to upgrade, except that omit and omitany commands do not affect filenames specified with the always command. omit _f_i_l_e_n_a_m_e ... 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). omitany _p_a_t_t_e_r_n ... 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. backup _f_i_l_e_n_a_m_e ... 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. noaccount _f_i_l_e_n_a_m_e ... The accounting information of the specified file(s) will not be preserved by _s_u_p. Accounting information consists of the owner, group, mode and modified time of a file. symlink _f_i_l_e_n_a_m_e ... The specified file(s) are to be treated as symbolic links and will be transfered as such and not followed. By default, _s_u_p will follow symbolic links. execute _e_x_e_c-_c_o_m_m_a_n_d (_f_i_l_e_n_a_m_e ...) The _e_x_e_c-_c_o_m_m_a_n_d 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 _e_x_e_c-_c_o_m_m_a_n_d 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 _s_u_p with the -e flag to allow the automatic exe- cution of command files. include _l_i_s_t_f_i_l_e ... The specified _l_i_s_t_f_i_l_e_s will be read at this point. This is useful when one collection subsumes other col- lections; the larger collection can simply specify the listfiles for the smaller collections contained within it. The order in which the command lines appear in the list file does not matter. Blank lines may appear freely in the list file. FILES Files on the client machine for _s_u_p: /usr/cs/lib/supfiles/name.host list of names of host machines acting as name servers /usr/cs/lib/supfiles/coll.list supfile used for -s flag <_b_a_s_e-_d_i_r_e_c_t_o_r_y>/sup/<_c_o_l_l_e_c_t_i_o_n>/last recorded list of files in collection as of last upgrade <_b_a_s_e-_d_i_r_e_c_t_o_r_y>/sup/<_c_o_l_l_e_c_t_i_o_n>/lock file used to lock collection <_b_a_s_e-_d_i_r_e_c_t_o_r_y>/sup/<_c_o_l_l_e_c_t_i_o_n>/refuse list of files to refuse in collection <_b_a_s_e-_d_i_r_e_c_t_o_r_y>/sup/<_c_o_l_l_e_c_t_i_o_n>/when recorded time of last upgrade /usr/<_c_o_l_l_e_c_t_i_o_n> default base directory for file collection Files needed on each name-server machine for the name server: /usr/cs/lib/supservers/coll.host host name list for system collections Files needed on each repository machine for the file server: /usr/cs/lib/supservers/coll.dir base directory list for system collections <_b_a_s_e-_d_i_r_e_c_t_o_r_y>/sup/<_c_o_l_l_e_c_t_i_o_n>/crypt data encryption key for a collection. the owner of this file is the default account used when data encryption is specified <_b_a_s_e-_d_i_r_e_c_t_o_r_y>/sup/<_c_o_l_l_e_c_t_i_o_n>/host list of remote hosts allowed to upgrade a collection <_b_a_s_e-_d_i_r_e_c_t_o_r_y>/sup/<_c_o_l_l_e_c_t_i_o_n>/list list file for a collection <_b_a_s_e-_d_i_r_e_c_t_o_r_y>/sup/<_c_o_l_l_e_c_t_i_o_n>/lock lock file for a collection <_b_a_s_e-_d_i_r_e_c_t_o_r_y>/sup/<_c_o_l_l_e_c_t_i_o_n>/logfile log file for a collection <_b_a_s_e-_d_i_r_e_c_t_o_r_y>/sup/<_c_o_l_l_e_c_t_i_o_n>/prefix file containing the name of the prefix directory for a collection <_b_a_s_e-_d_i_r_e_c_t_o_r_y>/sup/<_c_o_l_l_e_c_t_i_o_n>/scan scan file for a collection /usr/<_c_o_l_l_e_c_t_i_o_n> default base directory for a file collection SEE ALSO _s_u_p_s_e_r_v_e_r_s(8) _T_h_e _S_U_P _S_o_f_t_w_a_r_e _U_p_g_r_a_d_e _P_r_o_t_o_c_o_l, S. A. Shafer, CMU Com- puter Science Department, 1985. EXAMPLE <example> BUGS The encryption mechanism should be strengthened, although it's not trivial. HISTORY 10-May-86 Glenn Marcy (gm0w) at Carnegie-Mellon University Replaced reference to /usr/cmu with /usr/cs. 29-Mar-86 Glenn Marcy (gm0w) at Carnegie-Mellon University Updated manual entry to version 5.14 of sup. 14-Jan-86 Glenn Marcy (gm0w) at Carnegie-Mellon University Updated manual entry to version 5.7 of sup. 04-Apr-85 Steven Shafer (sas) at Carnegie-Mellon University Created.