« back to all changes in this revision
Viewing changes to sup.doc
- browse files at revision 4
- compare with another revision
- download diff
- download tarball
- view history from revision 4
- Committer: Bazaar Package Importer
- Author(s): Jochen Friedrich
- Date: 2006-11-02 15:03:30 UTC
- mfrom: (1.1.1 upstream) (3.1.1 dapper)
- Revision ID: james.westby@ubuntu.com-20061102150330-yt4yavw4rj1hz8yj
Tags: 20060803-2
Fix CFLAGS, so libwrap is built into sup again.
- files added:
- cvt.c
- debian/patches
- files removed:
- README.FreeBSD
- pkg
- files modified:
- Makefile
added
removed
sup.doc
1
2
3
4
5
6
7
8
9
10
11
12
THE SUP SOFTWARE UPGRADE PROTOCOL
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
Carnegie Mellon University
37
School of Computer Science
38
39
Steven Shafer
40
Mary Thompson
41
42
8 September 1989
43
44
45
46
47
48
49
50
51
52
The SUP system is a set of programs for maintaining a set of files in
53
identical versions across a network of cooperating machines. It runs under the
54
Mach operating system.
55
1. Introduction
56
The SUP System is a set of programs that provide for collections of files to
57
be maintained in identical versions across a number of machines. These
58
programs are:
59
60
SUP The "client" program, run by users or system maintainers, which
61
initiates the upgrade activity on a machine requesting the
62
latest version of a collection of files. SUP will normally be
63
run as a daemon, firing up once each night (week, etc.) to
64
upgrade the specified file collections.
65
66
SUPFILESRV The "file server" program, a daemon that is run by the system
67
maintainer to service requests for files initiated by client
68
SUP programs. The file server runs on every machine used as a
69
"repository" of distributable versions of files. It runs
70
continuously and listens for network connection requests by
71
individual client processes; for each individual client
72
request, a process is forked to service that request.
73
74
SUPSCAN The "file scanner" program, that may optionally be run
75
periodically to speed up execution of the file server. It
76
pre-compiles a list of files on the file system that match the
77
specifications for a given file collection so that the file
78
server need not do this during each upgrade of that collection.
79
The file scanner is normally used daily for very large file
80
collections that are upgraded by many clients each day; it is
81
not so useful for small file collections or for those that are
82
upgraded by only a few client machines per day.
83
84
When SUP is run, the user designates the names of certain "file collections",
85
sets of files, that should be upgraded. All pre-defined system collections
86
have entries in the coll.host file that gives the name of the host will act as
87
the repository for that software collection. The file server on that machine
88
provides a list of the files included in the collection and which ones have
89
been changed since the last time this collection was upgraded from that client
90
machine; the client decides which of these files it needs to receive; and the
91
files are sent from the file server. In this way, files can be installed on
92
the repository machine once, and they will propagate to all machines upgrading
93
from that repository as soon as the respective users execute SUP to perform the
94
upgrade. This allows groups of cooperating users to establish sets of files
95
that can be relied upon to be the same across a set of host machines.
96
97
SUP is intended to provide a broadcast facility for maintaining identical
98
versions of files across multiple machines. An alternative approach is to
99
provide a common file system; even when such a system is available, SUP is
100
useful for maintaining frequently used files on local disk storage, and for
101
maintaining files across the file server machines themselves.
102
103
The SUP system does not address the issues of version control, nor of
104
maintaining compatibility of pieces of a system that are being independently
105
changed by different users or on different machines; what SUP provides is a
106
broadcast mechanism for issuing stable, reliable versions of software or data
107
files, produced by a small number of maintainers and needed by a larger number
108
of users. SUP is intended specifically to address these situations:
109
110
- A large collection of system software prepared by a maintenance staff
111
for use by a large user community. For example, the CMU-CSD UNIX
112
software used by hundreds of workstations. In such situations, the
113
users know absolutely nothing about how to obtain such software, but
114
they need to keep it constantly upgraded on their machines.
115
Similarly, the maintainers cannot possibly maintain each user's
116
machine individually: they must rely on a broadcast mechanism such as
117
SUP.
118
119
- A moderate collection of software and data files shared by the
120
members of a project. For example, the vision libraries used by
121
computer vision researchers at CMU. Again, a small number of
122
maintainers on a specific machine produce and maintain this software,
123
which is used by many users on many machines in the CMU environment.
124
However, SUP will not support the practice of some groups that have
125
large programs with different pieces being simultaneously modified
126
and tested in incompatible ways by various users.
127
128
- A user with accounts on more than one machine. Such a user can set
129
up SUP to automatically copy a collection of files from one machine
130
to one or more others whenever they are changed on the repository
131
machine.
132
133
If the system maintenance staff is involved on the repository machine a
134
"system" file collection can be set up for which client SUP programs need know
135
nothing but the name of the collection. Otherwise, the file collection will be
136
"private", and client SUP programs must be specifically told the name of the
137
repository host and the base directory name for the collection on that host.
138
139
SUP provides facilities for upgrading read-protected files (i.e. files that
140
are not readable by the general public), data encryption of transmitted files
141
and filenames, allowing access only to selected host machines not on the local
142
network, automatically creating backup copies of critical files, executing
143
command-files or programs after upgrading files that require special handling,
144
and mailing progress and error messages to designated users. SUP is also as
145
clever as can be about ensuring that upgraded files have the same accounting
146
information (mode, owner, links, etc.) on the client machine as on the
147
repository machine, and ensuring that upgrade problems don't wipe out existing
148
files when this is avoidable.
149
2. How to Use SUP to Upgrade a File Collection
150
You will normally want to run SUP periodically, say every day or every week,
151
using the at program, to upgrade important file collections such as UNIX system
152
software. You can also execute SUP directly at any time. The SUP command
153
looks like this:
154
155
$ sup [flags] [supfile]
156
157
These are the flags and arguments:
158
159
-a (all files) Normally, SUP only upgrades files if they are out-of-date or
160
missing on your machine. If you specify the -a flag, then all
161
files in the collection will be upgraded regardless of whether
162
they meet these conditions. This is useful for recovering from
163
catastrophic file deletions or disk crashes.
164
165
-b (backup) If this flag is given, or the backup supfile option is
166
specified, the contents of regular files on the local system
167
will be saved before they are overwritten with new data. The
168
file collection maintainer can designate specific files to be
169
worthy of backing up whenever they are upgraded. However, such
170
backup will only take place if you specify this flag or the
171
backup option to allow backups for a file collection on your
172
machine. The backup mechanism will create a copy of the
173
current version of a file immediately before a new copy is
174
received from the file server; the copy is given the same name
175
as the original file but is put into a directory called BACKUP
176
within the directory containing the original file. For
177
example, /usr/sas/src/foo.c would have a backup copy called
178
/usr/sas/src/BACKUP/foo.c. There is no provision for
179
automatically maintaining multiple old versions of files; you
180
would have to do this yourself.
181
182
-B overrides and disables the -b flag and the backup supfile
183
option.
184
185
-d (delete) Files that are no longer in the collection on the repository
186
will be deleted if present on the local machine. This may also
187
be specified in a supfile with the deleteoption.
188
189
-D This flag overrides and disables the -d flag and the delete
190
supfile option.
191
192
-e (execute) Sup will execute commands sent from the repository that should
193
be run when a file is upgraded. If the -e flag is omitted,
194
Sup will print a message that specifies the command to execute.
195
This may also be specified in a supfile with the execute
196
option.
197
198
-E overrides and disables the -e flag and the execute supfile
199
option.
200
201
-f (file list) If you specify -f, then SUP will print a list of all the files
202
in the specified collections, indicating which ones need to be
203
upgraded, which are directories, and which require backup
204
copies to be created. The upgrade itself will not be
205
performed.
206
207
-l (local) Normally, SUP will not upgrade a collection if the repository
208
is on the same machine. This allows users to run upgrades on
209
all machines without having to make special checks for the
210
repository machine. If the -l flag is specified, collections
211
will be upgraded even if the repository is local.
212
213
-m (mail) Normally, SUP prints log messages on its standard output and
214
diagnostic output. With the -m flag, messages will be mailed
215
to you instead. This also allows the notify option to be
216
effective (see the discussion of supfiles below) to send mail
217
to someone else.
218
219
-N (network debugging)
220
The -N flag causes SUP to produce tons of output lines
221
describing the progress and status of the network
222
communications with the name server and file server.
223
224
-P (debugging ports)
225
The -P flag tells SUP to use an alternate set of TCP ports from
226
the normal ports. This is a debugging aid for system
227
maintenance.
228
229
-o (old files) This flag overrides the noold option if it appears in the
230
supfile. The -a flag also overrides the noold option. See
231
"Supfiles" below for details.
232
233
-O overrides and disables the -o flag and the old supfile option.
234
235
-s (system collections)
236
Normally, you will specify a specific supfile to describe the
237
file collections you want. If you use the -s flag, then a
238
specific supfile will be used that describes the system
239
software file collections. The supfile for system software is
240
/usr/cmu/lib/supfiles/coll.list.
241
242
-t (time) If you specify -t, then SUP will simply print out the last time
243
and date at which each specified file collection was
244
successfully upgraded; it will not perform any actual upgrade.
245
This is a diagnostic aid in case you suspect the upgrades
246
aren't working.
247
248
-v (verbose) Normally, SUP only produces messages to tell what's gone wrong
249
(if anything does go wrong). With the -v flag, messages will
250
be produced to tell what is happening when things are going
251
normally as well.
252
253
supfile You must specify the name of a supfile, unless you use the -s
254
flag to indicate the system software supfile. The supfile,
255
described below, specifies which file collections you want to
256
upgrade.
257
258
For example, to upgrade system software on your machine, type:
259
260
$ sup -s
261
262
or, to have detailed log messages mailed to you:
263
264
$ sup -v -m -s
265
266
Because SUP runs with your user-id, you will not be able to upgrade the system
267
software unless you are logged onto that account when you execute SUP.
268
269
Each file collection being upgraded must have a base directory on your
270
machine, which will normally contain all the files in the collection. Within
271
this directory there should be a subdirectory called sup that will be used by
272
the SUP program; it will be created automatically if you do not create it. SUP
273
will put files into this directory as needed.
274
275
If you want to find out what files need to be upgraded, type:
276
277
$ sup -f supfile
278
279
This will list all the files in the collection, indicating which need to be
280
upgraded (and why), which are directories, and which would have backup copies
281
created if the upgrade were performed. If you simply want to find out the date
282
and time of the last successful upgrades, type:
283
284
$ sup -t supfile
285
286
This will print the collection name and time of the last upgrade for each
287
collection described in the indicated supfile. For the system collections, you
288
can use:
289
290
$ sup -s -t
291
292
2.1 Supfiles
293
When you execute SUP, you specify a supfile either by name or by using the -s
294
flag. This file is a list of the file collections you wish to upgrade.
295
296
The supfile is a text file, with each file collection described on a single
297
line. The line begins with the name of the collection, and may then have a
298
number of options separated by spaces. The options are:
299
300
base=directory The name of the base directory on this machine for this file
301
collection, when you don't want to use the default
302
(/usr/collection).
303
304
host=hostname The name of the host machine acting as the repository for this
305
file collection, used for "private" file collections. For
306
"system" file collections, this is unnecessary because the this
307
information is kept in /usr/cs/lib/supfiles/coll.host.
308
309
hostbase=directory
310
The name of the base directory on the repository machine for
311
the file collection (see "How to Set Up a File Collection"
312
below). This is also used only for "private" file collections;
313
for "system" file collections, the information is obtained
314
automatically by the file server. The default name of the host
315
base directory is /usr/collection.
316
317
login=accountid The name of the account to be used by the file server, when the
318
default is not acceptable (i.e. it doesn't have the necessary
319
file access privileges to read the file collection). The
320
default at CMU is the "Anonymous FTP" account if no data
321
encryption is used, or the owner of the directory
322
sup/collection within the repository machine's base directory
323
if encryption is used.
324
325
password=password
326
The password used for the login account specified by the
327
"login" option. This password will be transmitted in encrypted
328
form over the network.
329
330
crypt=key An optional encryption key for filenames and file data for this
331
file collection. If used, the same key must be specified on
332
the repository machine or the upgrade will not take place.
333
This key is used for filenames and data only -- not for
334
transmission of the passsword in the "password" option. The
335
use of data encryption also implies an alternate default
336
account for the file server (see the "login" option above).
337
338
notify=mailaddress
339
The account name to which mail is to be addressed for log
340
messages for this file collection, when the -m flag is given to
341
SUP. The account name can be a complete mail address, possibly
342
including a network host name such as sas@cmu-cs-ius.
343
344
noexec This option prevents the automatic execution of command files
345
on your machine with the upgrade is finished (see "What SUP
346
Does" below).
347
348
backup This option enables backup copies of critical files to be
349
created by SUP as specified in "What SUP Does" below.
350
351
nodelete This option prevents SUP from deleting files on your machine if
352
they are deleted from the file collection on the repository
353
machine.
354
355
noold This option tells SUP not to check on files in the collection
356
that have not been modified or created since the last upgrade.
357
This allows SUP to run much faster on large file collections,
358
but prevents it from deleting files on the client machine if
359
they are deleted from the repository, or from restoring files
360
that have been accidentally deleted from the client machine.
361
This option is normally useful only for very large file
362
collections. Its function subsumes that of the nodelete
363
option. The noold flag will be ignored when either the -a or
364
-o flag is specified to SUP; this allows a complete file check
365
to be performed with the -o flag when needed to recover from,
366
say, accidental deletion of critical files.
367
368
Here is an example of a supfile:
369
370
cmu backup
371
vision crypt=pupil backup notify=vision@cmu-cs-ius
372
sas host=ius hostbase=/usr/sas/sun login=sas password=foo crypt=bletch
373
374
This supfile specifies the following file collection upgrades:
375
376
cmu The "cmu" file collection, which is a "system" file collection,
377
with local base directory /usr/cmu (the default). Backup
378
copies of critical files will be created during upgrading.
379
380
vision The "vision" file collection, also a "system" file collection,
381
with local base directory /usr/vision. Backups will be
382
created. The data will be encrypted with key pupil, and log
383
messages will be sent to the vision account on cmu-cs-ius.
384
385
sas A "private" file collection will be upgraded from the
386
cmu-cs-ius machine. The remote base directory is /usr/sas/sun,
387
but the local base directory is /usr/sas. The file server will
388
login on account sas with password foo; the data will be
389
encrypted with key bletch.
390
3. What SUP Does
391
An upgrade involves several steps:
392
393
1. SUP first reads the specified supfile, checking it for errors and
394
recording all the specifications and options.
395
396
2. If any collections do not specify a host name, SUP will look in
397
/usr/cs/supfiles/coll.host to find out the names of the hosts for
398
these collections. In the preceding example, the name server would
399
be asked to supply the host names for the cmu and vision file
400
collections.
401
402
3. For each collection on the list, SUP will connect to the file server
403
on the appropriate host and carry on the upgrade process. (If the
404
file server is on the same host machine as the client, and the base
405
directories are the same, then no upgrade is performed.)
406
407
a. The file server and SUP exchange setup information, including
408
the host base directory, login account name, password, and
409
encryption key. SUP also reports the time of the last
410
upgrade, by looking in the file sup/collection/when (e.g.
411
/usr/vision/sup/vision/when) on the client machine. The file
412
server gets the base directory name, if needed, by looking in
413
the file /usr/cs/lib/supservers/coll.dir, and gets the
414
encryption key from sup/collection/crypt on the repository
415
machine. The connection may be refused by the file server for
416
such reasons as:
417
418
- incorrect login name or password
419
- base directory is protected against access by the
420
specified account
421
- incorrect data encryption key
422
- host not allowed access
423
424
b. Once the connection is established and access permission has
425
been granted as above, the file server builds a list of all
426
files and directories in the file collection. The list file
427
sup/collection/list (see "How to Set Up a File Collection"
428
below) is used to generate this list. The files indicated in
429
the list file are marked with a special flag if they are
430
indicated to have backup copies created in case of upgrade.
431
The last modification date of each file is checked against the
432
time of the last upgrade (reported by the client above), and
433
if it has been modified since the last upgrade, a flag is set
434
to indicate that the client's copy of this file is out of
435
date. The file list, along with the backup and out-of-date
436
flag for each file, is sent to the client. If a scan file
437
exists as created by SUPSCAN (sup/collection/scan), then the
438
file list is taken from the scan file instead of being
439
constructed from the list file by the file server. In this
440
case, the time of record for the upgrade will be the time at
441
which the scan file was created rather than the time at which
442
the upgrade actually occurs. If the noold option was
443
specified in the supfile (and not overridden by the -a or -o
444
flag to SUP), the list of filenames sent to the client process
445
will exclude those files that were not created or modified
446
since the last upgrade.
447
448
c. The client SUP process receives the list of files and
449
constructs a list of the files it needs. This will normally
450
be those files that are either (1) out-of-date as indicated by
451
the flag sent from the file server, or (2) missing from the
452
local machine. However, if the -a flag was specified to SUP,
453
then every file in the list will be selected by the client
454
process. The list of needed files is sent to the file server.
455
For each selected file, if the backup flag was marked and the
456
user specified the backup option in the supfile, then a backup
457
copy of the file will be created. This will be a copy of the
458
file with "backup/" inserted in the filename just after the
459
directory name, i.e. /usr/vision/lib/libvision.a would have a
460
backup copy named /usr/vision/lib/backup/libvision.a. (The
461
indicated directory, e.g. /usr/vision/lib/backup, will be
462
created if needed.) Also at this time, if the nodelete option
463
was not specified, the client reads its list of files in the
464
collection during the last successful upgrade,
465
sup/collection/last, and deletes any files appearing in that
466
list that are not in the current file list.
467
468
d. The file server receives the list of files requested by the
469
client. It checks to see that each file is on its list of
470
files for this collection, and that each file is accessible;
471
if a file fails either condition its name will be reported to
472
the client as being denied to that client. Each file will be
473
sent to the client machine, along with the owning account
474
name, the owning group name, the 12 low-order mode bits, and
475
the last modification time for that file. If a file has more
476
than one link (filename), both of which are requested by the
477
client, then the file will be sent once and the second (etc.)
478
filename will be accompanied only by a flag saying it's a link
479
and the name of the file actually sent. The client receives
480
each file and processes it as described under "File
481
Installation" below. Directories are treated similarly to
482
files; the mode, owning account and group, and modification
483
time are transmitted to the client machine whenever a
484
directory is upgraded.
485
486
e. When all files have been transmitted, the file server looks at
487
the list of command-files to be executed after upgrading for
488
this collection (see "How to Set Up a File Collection" below).
489
If any of the command-files or their trigger files have been
490
upgraded, then the client is sent the filename of the
491
command-file. The client SUP process will normally execute
492
these files; however, if the user has specified noexec in the
493
supfile, then the files will not be executed. In this case, a
494
log message will be created and printed or mailed, telling the
495
user to please execute these files. When creating command
496
files to be executed by SUP, you should bear in mind that the
497
command file might be executed several times on the same
498
version of the trigger files.
499
500
f. Finally, if the upgrade is successfully completed, the file
501
server reports the time (on its own clock) at which the
502
upgrade began; the client will record this time in the file
503
sup/collection/when to be reported as above at the start of
504
the next upgrade. If the nodelete option was not specified,
505
then the list of all files in the collection is written into
506
sup/collection/last.
507
508
SUP and the server processes begin each connection by determining whether
509
byte-swapping is necessary for passing integers across the network. If so, the
510
server process performs byte-swapping on input or output of integers to the
511
network, while the client uses its natural representation for network I/O.
512
513
3.1 File Installation
514
When SUP receives an ordinary file (i.e. one that is not a link to a
515
previously sent file), it follows this procedure:
516
517
1. If the file doesn't already exist on the local machine, it's a new
518
file. It will be created and the data will be read directly into
519
this file.
520
521
2. Otherwise, the file already exists. An attempt will be made to read
522
the file contents from the network into a temporary file, which will
523
later be renamed to replace the destination file. SUP will try to
524
create a temporary file in the following directories, proceeding
525
down the list until one of the attempts succeeds:
526
527
a. destination-directory (the directory containing the file
528
itself)
529
b. sup (the sup subdirectory of the local base directory)
530
c. . (the local base directory)
531
d. /usr/tmp
532
e. /tmp
533
534
If all these attempts fail, SUP will try to create the destination
535
file itself instead of using a temporary file. If that fails, SUP
536
will complain with a log message and go on to the next file.
537
538
3. The file data itself is read into the temporary or destination file.
539
Interrupts are disabled during this process.
540
541
4. If the file read was a temporary file, it is renamed to the
542
destination file. This is done via link/unlink, if possible, unless
543
the destination file has more than one link already on this machine.
544
If the link/unlink fails or if the destination file has multiple
545
links, then the temporary file is actually copied to the destination
546
and the temporary file is unlinked.
547
548
5. The owner, group, modification time, and low-order 12 mode bits of
549
the destination file are set to the values received from the file
550
server. The last-access time of the file is set to the current
551
local clock.
552
553
6. If the -v flag was specified to SUP, a log message is printed
554
indicating the successful receipt of the file.
555
556
When SUP receives a new link to a file previously received, it simply tries
557
to unlink and link unless the two names are on different file systems on the
558
local machine. If this is the case, or if the link fails, then the previously
559
received file is actually copied to the new name (using exactly the same
560
process as described above for creating a temporary file if needed, etc.) The
561
file-system comparison checks the file system of the old file itself and the
562
directory containing the new name.
563
564
In all cases, if the directory containing a received file or link does not
565
exist on the local machine, SUP creates it with mkdir (recursively if needed)
566
before creating that file or link. The mode, owner, group, and modification
567
time of the newly created directory will then be set to be the same as the mode
568
of the corresponding directory on the repository machine. This accounting
569
information will be updated whenever the directory is modified on the
570
repository machine.
571
572
As can be seen from this description, SUP will work the most smoothly (i.e.
573
always using link/unlink for file name changing) if it has write permission in
574
the local base directory and in all subdirectories of that directory.
575
4. How to Set Up a File Collection
576
It takes only a little bit of effort to set up a file collection on a
577
repository machine to be upgraded by authorized clients.
578
579
First, the file collection must be given a name and a base directory. There
580
can be several collections with different names sharing the same base
581
directory; for example, there might be a file collection called cmulib for the
582
CMU C library, and one called cmumathlib for just the math routines in the CMU
583
C library, both using /usr/cmu as the base directory.
584
585
If it is a "private" file collection, client users must be told the name of
586
the repository host and the name of the host base directory for use in the host
587
and hostbase options in the supfile, described above. If it is a "system"
588
collection instead, the system maintainers must alert the name servers of the
589
host name (in /usr/cmu/lib/supservers/coll.host) and the appropriate file
590
server of the base directory name (if not the default, by putting it into
591
/usr/cmu/lib/supservers/coll.dir).
592
593
Within the base directory, a subdirectory must be created called sup. Within
594
this subdirectory will be a further subdirectory whose name is the name of the
595
collection (there may be several of these if several collections share the same
596
base directory). Each collection's subdirectory will contain any or all of
597
four files:
598
599
collection/list The list file, describing the files in the collection. The
600
format of this file is explained below.
601
602
collection/host Normally, the file server allows access to a collection by all
603
machines. If you wish to allow access only to specific remote
604
hosts, you can list their names, one per line, in this text
605
file. If a remote host has several alias names, it need only
606
be listed once in this file. The name LOCAL can be used to
607
allow access to all machines on the local network. This access
608
control is in addition to the other forms of authentication
609
provided by SUP (data encryption and UNIX file protection
610
modes).
611
612
collection/crypt
613
If you wish to apply data encryption to the filenames and file
614
contents in this collection during upgrading, create this file
615
and place in it the encryption key. This should be on a single
616
line of text containing nothing else except an optional newline
617
character. The client must supply the same key via the crypt
618
option in the supfile for this file collection; the file server
619
checks that explicitly before authorizing the upgrade to take
620
place.
621
622
collection/scan To speed up execution of the file server, you may wish to
623
create a scan file periodically. This is done by executing the
624
SUPSCAN program:
625
626
$ supscan [-v] collection [basedir]
627
628
This will construct a list of all files matching the
629
specifications in the list file, and record it in the scan
630
file. When an upgrade is performed on the collection, the file
631
server will notice that the scan file is present and use this
632
list instead of actually building the filename list by
633
analyzing the list file. The time of record for the upgrade
634
will then be the time at which the scan file was created rather
635
than the time at which the upgrade occurs. A scan file is only
636
useful for very large file collections that are upgraded many
637
times each day. The options for the SUPSCAN program are -v
638
("verbose") to produce messages as it scans the file list, and
639
basedir if the collection is a private collection whose base
640
directory name is not the default name.
641
642
This is all the preparation required for a file collection to be upgraded.
643
644
Note that the default user-id for the file server is "Anonymous FTP" if no
645
data encryption is used; if encryption is used, the default will be the owner
646
of the subdirectory sup/collection within the base directory.
647
648
4.1 The List File
649
The list file contains a description of the files to be upgraded. It
650
contains any number of commands, each on a separate line of text. Each line
651
contains a keyword and a number of operands separated by spaces. All filenames
652
in the list are evaluated relative to the collection's base directory on the
653
repository machine for the file server, and relative to the base directory on
654
the client machine for the client SUP process. All (except execfile) may be
655
file specifications containing the shell's meta-characters *, ?, [...], and
656
{...}.
657
658
The commands are:
659
660
upgrade filename ...
661
These files will be included in the list of files to be
662
upgraded. If a directory name is given, all the files in that
663
directory will be included and any subdirectories will be
664
recursively included as well.
665
666
omit filename ...
667
These files will not be included in the list; if a directory is
668
specified, it will not be included nor will its contents be
669
included. For example, the specifications upgrade lib and omit
670
lib/test will include all files and subdirectories of lib
671
except lib/test (and any subdirectories or files within
672
lib/test).
673
674
omitany pattern ...
675
The specified patterns are compared against the files in the
676
upgrade list. If a pattern matches, the file is omitted. The
677
omitany command currently supports all wild-card patterns
678
except {...}. Also, the pattern must match the entire
679
filename, so a leading */, or a trailing /*, may be necessary
680
in the pattern.
681
682
backup filename ...
683
The files will be marked for creating backup copies whenever
684
they are upgraded (as described above). Only files can be
685
included in this list -- not directories. As noted above,
686
actual backup copies will only be created by SUP when these
687
files are being upgraded, and then only if the user has
688
specified the backup option in the supfile.
689
690
execute execfile (triggerfile ...) ...
691
The listed execfiles are command files or programs to be
692
executed after an upgrade to perform routine installation of
693
the upgraded files. Each execfile will be executed only when
694
it is upgraded itself, or when any of its listed triggerfiles
695
have been upgraded. The installation tasks performed by such
696
files might be, for example, creating a table of contents for
697
manual entries or for a subroutine library, or modifying a host
698
name field within a data file.
699
700
include listfile ...
701
The named listfiles will be read at this point. This allows a
702
collection to contain another collection in its entirety, by
703
simply specifying the name of the listfile for that other
704
collection.
705
706
backup filename...
707
The specified file(s) are marked for backup; if they are
708
upgraded and the client has specified the backup option in the
709
corresponding line of the supfile, then backup copies will be
710
created as described above. Directories may not be specified,
711
and no recursive filename construction is performed; you must
712
specify the names of the specific files to be backed up before
713
upgrading.
714
715
symlink filename...
716
The specified file(s) are to be treated as symbolic links and
717
will be transfered as such and not followed. By default, SUP
718
will follow symbolic links.
719
720
rsymlink dirname...
721
All the symbolic links in the specified subdirectories are to
722
be transferred as such and not followed.
723
724
Blank lines may appear freely in the list file, and the order in which
725
command lines appear within the file does not matter. Filenames must generally
726
match as strings, e.g. with base directory /usr/vision, "lib" in the upgrade
727
command would not match "/usr/vision/lib" in the omit command; it would only
728
match "lib" in the omit command. However, one special exception exists: if
729
the base directory is specified via "dot" (.) in the upgrade command, the
730
filenames within that directory need not begin with "./" in other commands.
731
For example, with base directory /usr/vision, the commands "upgrade ." and
732
"omit exp" specify a file list including all files and directories within
733
/usr/vision except the subdirectory /usr/vision/exp and its subdirectories and
734
files.
735
5. Setup for SUP
736
You need to add the following entries to /etc/services:
737
738
supfilesrv 871/tcp
739
supfiledbg 1127/tcp
740
741
A supfilsrv daemon should be kept running on any machine that may act as a
742
repository for a collection. Since this includes private collections, it is
743
advisable to have supfilesrv running on all machines if SUP is to be widely
744
used. nanny can be used to start the supfilesrv.
745
746
The program modcoll.8 is used to set up the control files for the "system"
747
collections. See /usr/cs/man/man8/modcoll.8
748
Table of Contents
749
750
1. Introduction 1
751
752
2. How to Use SUP to Upgrade a File Collection 2
753
754
2.1 Supfiles 2
755
756
3. What SUP Does 4
757
758
3.1 File Installation 4
759
760
4. How to Set Up a File Collection 5
761
762
4.1 The List File 5
763
764
5. Setup for SUP 6
Loggerhead is a web-based interface for Breezy
Version: 2.0.1