1 .\" Copyright 1996-2003 John D. Polstra.
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
14 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
15 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
16 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
17 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
18 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
19 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
20 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
21 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
22 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
24 .\" $Id: cvsup.1,v 1.70 2003/03/04 18:23:46 jdp Exp $
32 .Nd network distribution package for CVS repositories
45 .Op Fl r Ar maxRetries
49 is a software package for updating collections of files across a network.
50 It is a rewrite of the
53 This manual page describes the usage of the
57 Unlike more traditional network distribution packages, such as
62 has specific optimizations for distributing CVS repositories.
64 takes advantage of the properties of CVS repositories and the files they
65 contain (in particular, RCS files), enabling it to perform updates much
66 faster than traditional systems.
69 is a general-purpose network file updating package.
71 even for collections of files which have nothing to do with CVS or
76 requires at least a single argument,
78 It names a file describing one or more collections of files to be
79 transferred and/or updated from the server.
82 has a format similar to the corresponding file used by
89 The following options are supported by
93 Disables automatic retries when transient failures occur.
94 Without this option, a transient failure such as a dropped network
97 to retry repeatedly, using randomized exponential backoff to space the
99 This option is equivalent to
104 to use IPv4 addresses only.
108 to use IPv6 addresses only.
110 Specifies a local address to bind to when connecting to the server.
111 The local address might be a hostname or a numeric host address string
112 consisting of a dotted decimal IPv4 address or an IPv6 address.
113 This may be useful on hosts which have multiple IP addresses.
115 Specifies the base directory under which
117 will maintain its bookkeeping files, overriding any
119 specifications in the
122 Specifies the subdirectory of
124 where the information about the collections is maintained.
128 Specifies the maximum number of files that may be deleted in a
130 Any attempt to exceed the limit results in a fatal error.
131 This can provide some protection against temporary configuration
132 mistakes on the server.
133 The default limit is infinity.
135 Specifies the server host to contact, overriding any
137 specifications in the
142 to include only files and directories matching
144 in the update. If a directory matches the pattern, then the entire
145 subtree rooted at the directory is included. If this option is
146 specified multiple times, the patterns are combined using the
150 options are given, the default is to update all files in each
155 is a standard file name pattern.
156 It is interpreted relative to the collection's prefix directory.
157 Slash characters are matched only by explicit slashes in the pattern.
158 Leading periods in file name are not treated specially.
162 to keep the temporary copies of any incorrectly edited files, in the
163 event of checksum mismatches.
164 This option is for debugging, to help determine why the files were
166 Regardless of whether this option is specified, the permanent versions
167 of faulty files are replaced with correct versions obtained by
168 transferring the files in their entirety.
169 Such transfers are called fixups.
171 Creates and locks the
173 while the update is in progress.
178 fails without performing automatic retries.
179 This option is useful when
181 is executed periodically from
183 It prevents a job from interfering with an earlier job that is perhaps
184 taking extra long because of network problems.
186 The process-ID is written to the lock file in text form when the lock
187 is successfully acquired.
188 Upon termination of the update, the lock file is removed.
189 .It Fl L Ar verbosity
190 Sets the verbosity level for output.
193 to be completely silent unless errors occur.
194 A level of 1 (the default) causes each updated file to be listed.
195 A level of 2 provides more detailed information about the updates
196 performed on each file.
197 All messages are directed to the standard output.
199 Sets the TCP port to which
201 attempts to connect on the server host.
202 The default port is 5999.
203 .It Fl r Ar maxRetries
204 Limits the number of automatic retries that will be attempted when
205 transient errors such as lost network connections are encountered.
208 will retry indefinitely until an update is successfully completed.
209 The retries are spaced using randomized exponential backoff.
216 Suppresses the check of each client file's status against what is
217 recorded in the list file. Instead, the list file is assumed to be
218 accurate. This option greatly reduces the amount of disk activity and
219 results in faster updates with less load on the client host. However
220 it should only be used if client's files are never modified locally in
221 any way. Mirror sites may find this option beneficial to reduce the
222 disk load on their systems. For safety, even mirror sites should run
224 occasionally (perhaps once a day) without the
234 call on each file and verifies that its attributes match those
235 recorded in the list file. This ensures that any file changes made
238 are detected and corrected.
242 option is used when one or more files have been modified locally, the
243 results are undefined. Local file damage may remain uncorrected,
244 updates may be missed, or
246 may abort prematurely.
248 Prints the version number and exits, without contacting the server.
250 Enables compression for all collections, as if the
252 keyword were added to every collection in the
255 Disables compression for all collections, as if the
257 keyword were removed from every collection in the
263 is a text file which specifies the file collections to be updated.
266 and extend to the end of the line. Lines that are empty except for
267 comments and white space are ignored. Each remaining line begins
268 with the name of a server-defined collection of files. Following the
269 collection name on the line are zero or more keywords or keyword=value
272 Default settings may be specified in lines whose collection name is
274 Such defaults will apply to subsequent lines in the
278 lines may be present.
279 New values augment or override any defaults specified earlier in the
281 Values specified explicitly for a collection override any default
284 The most commonly used keywords are:
286 .It Cm release= Ns Ar releaseName
287 This specifies the release of the files within a collection.
288 Like collection names, release names are defined by the server
289 configuration files. Usually there is only one release in each
290 collection, but there may be any number. Collections which come from
291 a CVS repository often use
293 by convention. Non-CVS collections conventionally use
294 .Cm release=current .
295 .It Cm base= Ns Ar base
296 This specifies a directory under which
298 will maintain its bookkeeping files, describing the state of each
299 collection on the client machine.
302 directory must already exist;
308 .Pa /usr/local/etc/csup .
309 .It Cm prefix= Ns Ar prefix
310 This is the directory under which updated files will be placed.
311 By default, it is the same as
313 If it is not an absolute pathname, it is interpreted relative to
317 directory must already exist;
321 As a special case, if
323 is a symbolic link pointing to a nonexistent file named
327 will skip the collection.
328 The parameters associated with the collection are still checked for
329 validity, but none of its files will be updated.
330 This feature allows a site to use a standard
332 on several machines, yet control which collections get updated on a
334 .It Cm host= Ns Ar hostname
335 This specifies the server machine from which all files will be taken.
337 requires that all collections in a single run come from the same host.
338 If you wish to update collections from several different hosts, you must
343 The presence of this keyword gives
345 permission to delete files.
346 If it is missing, no files will be deleted.
356 does its best to make the client's files correspond to those on the server.
357 This includes deleting individual deltas and symbolic tags from RCS
358 files, as well as deleting entire files.
361 verifies every edited file with a checksum, to ensure that the edits
362 have produced a file identical to the master copy on the server.
363 If the checksum test fails for a file, then
365 falls back upon transferring the entire file.
369 deletes only files which are known to the server.
370 Extra files present in the client's tree are left alone, even in exact
374 is willing to delete two classes of files:
377 Files that were previously created or updated by
381 Checked-out versions of files which are marked as dead on the server.
383 .It Cm use-rel-suffix
386 to append a suffix constructed from the release and tag to the name of
387 each list file that it maintains.
392 This enables compression of all data sent across the network.
393 Compression is quite effective, normally eliminating 65% to 75% of the
394 bytes that would otherwise need to be transferred.
395 However, it is costly in terms of CPU time on both the client and the
397 On local area networks, compression is generally counter-productive; it
398 actually slows down file updates.
399 On links with speeds of 56K bits/second or less, compression is almost
401 For network links with speeds between these two extremes, let
402 experimentation be your guide.
406 command line option enables the
408 keyword for all collections, regardless of what is specified in the supfile.
411 command line option disables the
413 option for all collections.
415 uses a looser checksum for RCS files, which ignores harmless
416 differences in white space. Different versions of CVS and RCS produce
417 a variety of differences in white space for the same RCS files. Thus
418 the strict checksum can report spurious mismatches for files which are
419 logically identical. This can lead to numerous unneeded
421 and thus to slow updates.
422 .It Cm umask= Ns Ar n
425 to use a umask value of
427 (an octal number) when updating the files in the collection.
428 This option is ignored if
433 Some additional, more specialized keywords are described below.
434 Unrecognized keywords are silently ignored for backward compatibility
439 supports two primary modes of operation.
446 In CVS mode, the client receives copies of the actual RCS files making
447 up the master CVS repository. CVS mode is the default mode of operation.
448 It is appropriate when the user wishes to maintain a full copy of the
449 CVS repository on the client machine.
451 CVS mode is also appropriate for file collections which are not
452 based upon a CVS repository. The files are simply transferred
453 verbatim, without interpretation.
455 In checkout mode, the client receives specific revisions of files,
456 checked out directly from the server's CVS repository.
457 Checkout mode allows the client to receive any version from the
458 repository, without requiring any extra disk space on the server for
459 storing multiple versions in checked-out form.
460 Checkout mode provides much flexibility beyond that basic functionality,
462 The client can specify any CVS symbolic tag, or any date, or both, and
464 will provide the corresponding checked-out versions of the files in the
467 Checkout mode is selected on a per-collection basis, by the presence of
468 one or both of the following keywords in the
471 .It Cm tag= Ns Ar tagname
472 This specifies a symbolic tag that should be used to select the
473 revisions that are checked out from the CVS repository.
474 The tag may refer to either a branch or a specific revision.
475 It must be symbolic; numeric revision numbers are not supported.
477 For the FreeBSD source repository, the most commonly used tags will be:
478 .Bl -tag -width RELENG_6
487 This is the default, if only the
494 .Ar yy.mm.dd.hh.mm.ss
497 This specifies a date that should be used to select the revisions that
498 are checked out from the CVS repository.
499 The client will receive the revisions that were in effect at the
500 specified date and time.
502 At present, the date format is inflexible. All 17 or 19 characters must
503 be specified, exactly as shown.
504 For the years 2000 and beyond, specify the century
506 For earlier years, specify only the last two digits
508 Dates and times are considered to
513 .Dq as late as possible .
516 To enable checkout mode, you must specify at least one of these keywords.
519 defaults to CVS mode.
521 If both a branch tag and a date are specified, then the revisions on the
522 given branch, as of the given date, will be checked out. It is
523 permitted, but not particularly useful, to specify a date with a
524 specific release tag.
526 In checkout mode, the tag and/or date may be changed between updates.
527 For example, suppose that a collection has been transferred using the
530 The user could later change the specification to
534 to edit the checked-out files in such a way as to transform them from the
541 is willing to transform any tag/date combination into any other tag/date
542 combination, by applying the intervening RCS deltas to the existing files.
544 When transforming a collection of checked-out files from one tag to
545 another, it is important to specify the
549 to ensure that the same list file is used both before and after the
551 The list file is described in
557 maintains a bookkeeping file for each collection, called the list file.
558 The list file contains information about which files and revisions the client
560 It also contains information used for verifying that the list file
561 is consistent with the actual files in the client's tree.
563 The list file is not strictly necessary. If it is deleted, or becomes
564 inconsistent with the actual client files,
566 falls back upon a less efficient method of identifying the client's
567 files and performing its updates.
570 mode of operation, the fallback method employs time stamps, checksums, or
571 analysis of RCS files.
573 Because the list file is not essential,
577 an existing file tree acquired by FTP or from a CD-ROM.
579 identifies the client's versions of the files, updates them as
580 necessary, and creates a list file for future use.
581 Adopting a foreign file tree is not as fast as performing a normal
583 It also produces a heavier load on the server.
585 The list file is stored in a collection-specific directory; see
588 Its name always begins with
594 a suffix, formed from the release and tag, is appended to the name.
595 The default suffix can be overridden by specifying an explicit suffix in
599 .It Cm list= Ns Ar suffix
600 This specifies a suffix for the name of the list file. A leading dot is
601 provided automatically.
604 would produce a list file named
605 .Pa checkouts.stable ,
606 regardless of the release, tag, or
611 The user can specify sets of files that he does not wish to receive.
612 The files are specified as file name patterns in so-called
615 The patterns are separated by whitespace, and multiple patterns are
616 permitted on each line.
617 Files and directories matching the patterns are neither updated nor
618 deleted; they are simply ignored.
620 There is currently no provision for comments in refuse files.
622 The patterns are similar to those of
624 except that there is no special treatment for slashes or for
625 filenames that begin with a period.
626 For example, the pattern
628 will match any file name ending with
630 including those in subdirectories, such as
632 All patterns are interpreted relative to the collection's prefix
635 If the files are coming from a CVS repository, as is usually
636 the case, then they will be RCS files. These have a
638 suffix which must be taken into account in the patterns. For
639 example, the FreeBSD documentation files are in a sub-directory of
645 from that directory is not required then the line
647 .Bl -item -compact -offset indent
652 will not work because the file on the server is called
654 A better solution would be
656 .Bl -item -compact -offset indent
661 which will match whether
663 is an RCS file or not.
665 As another example, to receive the FreeBSD documentation files without
666 the Japanese, Russian, and Chinese translations, create a refuse file
667 containing the following lines:
669 .Bl -item -compact -offset indent
678 As many as three refuse files are examined for each
681 There can be a global refuse file named
683 .Ar base / Ar collDir Pa /refuse
685 which applies to all collections and releases.
686 There can be a per-collection refuse file named
688 .Xo Ar base / Ar collDir / Ar collection
692 which applies to a specific collection.
693 Finally, there can be a per-release and tag refuse file which applies only
694 to a given release/tag combination within a collection.
695 The name of the latter is formed by suffixing the name of the
696 per-collection refuse file in the same manner as described above for the
698 None of the refuse files are required to exist.
701 has a built-in default value of
702 .Ar /usr/local/etc/cvsup
709 but it is possible to override both of these. The value of
711 can be changed using the
717 (If both are used the
719 option will override the
723 can only be changed with the
727 command to change it.
729 As an example, suppose that the
733 both have their default values, and that the collection and release are
738 Assume further that checkout mode is being used with
740 The three possible refuse files would then be named:
742 .Bl -item -compact -offset indent
744 .Pa /usr/local/etc/cvsup/sup/refuse
746 .Pa /usr/local/etc/cvsup/sup/src-all/refuse
748 .Pa /usr/local/etc/cvsup/sup/src-all/refuse.cvs:RELENG_3
755 the refuse files would be:
757 .Bl -item -compact -offset indent
761 .Pa /foo/sup/src-all/refuse
763 .Pa /foo/sup/src-all/refuse.cvs:RELENG_3
774 .Bl -item -compact -offset indent
778 .Pa /bar/sup/src-all/refuse
780 .Pa /bar/sup/src-all/refuse.cvs:RELENG_3
788 .Bl -item -compact -offset indent
790 .Pa /bar/stool/refuse
792 .Pa /bar/stool/src-all/refuse
794 .Pa /bar/stool/src-all/refuse.cvs:RELENG_3
796 .Sh csup AND FIREWALLS
799 will work through any firewall which permits outbound connections to
800 port 5999 of the server host.
801 .Sh USING csup WITH SOCKS
803 can be used through a SOCKS proxy server with the standard
808 executable needs to be dynamically-linked with the system
812 .Sh USING ssh PORT FORWARDING
813 As an alternative to SOCKS, a user behind a firewall can penetrate it
814 with the TCP port forwarding provided by the Secure Shell package
816 The user must have a login account on the
818 server host in order to do this.
819 The procedure is as follows:
822 Establish a connection to the server host with
826 ssh -f -x -L 5999:localhost:5999 serverhost sleep 60
831 with the hostname of the CVSup server, but type
834 This sets up the required port forwarding.
840 Once the update has begun,
842 will keep the forwarded channels open as long as they are needed.
846 on the local host, including the arguments
851 .Bl -tag -width base/sup/collection/checkouts*xx -compact
852 .It Pa /usr/local/etc/cvsup
861 .It Xo Ar base / Ar collDir / Ar collection
873 http://mu.org/~mux/csup.html
877 .An Maxime Henrion Aq mux@FreeBSD.org
883 .An John Polstra Aq jdp@polstra.com
887 CVSup is a registered trademark of John D. Polstra.
890 is released under a 2-clauses BSD license.
892 An RCS file is not recognized as such unless its name ends with
897 is assumed to be a CVS Attic, and is treated specially.
projects / FreeBSD / releng / 8.1.git / blob