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 only supports the checkout mode for now.
448 In CVS mode, the client receives copies of the actual RCS files making
449 up the master CVS repository. CVS mode is the default mode of operation.
450 It is appropriate when the user wishes to maintain a full copy of the
451 CVS repository on the client machine.
453 CVS mode is also appropriate for file collections which are not
454 based upon a CVS repository. The files are simply transferred
455 verbatim, without interpretation.
457 In checkout mode, the client receives specific revisions of files,
458 checked out directly from the server's CVS repository.
459 Checkout mode allows the client to receive any version from the
460 repository, without requiring any extra disk space on the server for
461 storing multiple versions in checked-out form.
462 Checkout mode provides much flexibility beyond that basic functionality,
464 The client can specify any CVS symbolic tag, or any date, or both, and
466 will provide the corresponding checked-out versions of the files in the
469 Checkout mode is selected on a per-collection basis, by the presence of
470 one or both of the following keywords in the
473 .It Cm tag= Ns Ar tagname
474 This specifies a symbolic tag that should be used to select the
475 revisions that are checked out from the CVS repository.
476 The tag may refer to either a branch or a specific revision.
477 It must be symbolic; numeric revision numbers are not supported.
479 For the FreeBSD source repository, the most commonly used tags will be:
480 .Bl -tag -width RELENG_6
489 This is the default, if only the
496 .Ar yy.mm.dd.hh.mm.ss
499 This specifies a date that should be used to select the revisions that
500 are checked out from the CVS repository.
501 The client will receive the revisions that were in effect at the
502 specified date and time.
504 At present, the date format is inflexible. All 17 or 19 characters must
505 be specified, exactly as shown.
506 For the years 2000 and beyond, specify the century
508 For earlier years, specify only the last two digits
510 Dates and times are considered to
515 .Dq as late as possible .
518 To enable checkout mode, you must specify at least one of these keywords.
521 defaults to CVS mode.
523 If both a branch tag and a date are specified, then the revisions on the
524 given branch, as of the given date, will be checked out. It is
525 permitted, but not particularly useful, to specify a date with a
526 specific release tag.
528 In checkout mode, the tag and/or date may be changed between updates.
529 For example, suppose that a collection has been transferred using the
532 The user could later change the specification to
536 to edit the checked-out files in such a way as to transform them from the
543 is willing to transform any tag/date combination into any other tag/date
544 combination, by applying the intervening RCS deltas to the existing files.
546 When transforming a collection of checked-out files from one tag to
547 another, it is important to specify the
551 to ensure that the same list file is used both before and after the
553 The list file is described in
559 maintains a bookkeeping file for each collection, called the list file.
560 The list file contains information about which files and revisions the client
562 It also contains information used for verifying that the list file
563 is consistent with the actual files in the client's tree.
565 The list file is not strictly necessary. If it is deleted, or becomes
566 inconsistent with the actual client files,
568 falls back upon a less efficient method of identifying the client's
569 files and performing its updates.
572 mode of operation, the fallback method employs time stamps, checksums, or
573 analysis of RCS files.
575 Because the list file is not essential,
579 an existing file tree acquired by FTP or from a CD-ROM.
581 identifies the client's versions of the files, updates them as
582 necessary, and creates a list file for future use.
583 Adopting a foreign file tree is not as fast as performing a normal
585 It also produces a heavier load on the server.
587 The list file is stored in a collection-specific directory; see
590 Its name always begins with
596 a suffix, formed from the release and tag, is appended to the name.
597 The default suffix can be overridden by specifying an explicit suffix in
601 .It Cm list= Ns Ar suffix
602 This specifies a suffix for the name of the list file. A leading dot is
603 provided automatically.
606 would produce a list file named
607 .Pa checkouts.stable ,
608 regardless of the release, tag, or
613 The user can specify sets of files that he does not wish to receive.
614 The files are specified as file name patterns in so-called
617 The patterns are separated by whitespace, and multiple patterns are
618 permitted on each line.
619 Files and directories matching the patterns are neither updated nor
620 deleted; they are simply ignored.
622 There is currently no provision for comments in refuse files.
624 The patterns are similar to those of
626 except that there is no special treatment for slashes or for
627 filenames that begin with a period.
628 For example, the pattern
630 will match any file name ending with
632 including those in subdirectories, such as
634 All patterns are interpreted relative to the collection's prefix
637 If the files are coming from a CVS repository, as is usually
638 the case, then they will be RCS files. These have a
640 suffix which must be taken into account in the patterns. For
641 example, the FreeBSD documentation files are in a sub-directory of
647 from that directory is not required then the line
649 .Bl -item -compact -offset indent
654 will not work because the file on the server is called
656 A better solution would be
658 .Bl -item -compact -offset indent
663 which will match whether
665 is an RCS file or not.
667 As another example, to receive the FreeBSD documentation files without
668 the Japanese, Russian, and Chinese translations, create a refuse file
669 containing the following lines:
671 .Bl -item -compact -offset indent
680 As many as three refuse files are examined for each
683 There can be a global refuse file named
685 .Ar base / Ar collDir Pa /refuse
687 which applies to all collections and releases.
688 There can be a per-collection refuse file named
690 .Xo Ar base / Ar collDir / Ar collection
694 which applies to a specific collection.
695 Finally, there can be a per-release and tag refuse file which applies only
696 to a given release/tag combination within a collection.
697 The name of the latter is formed by suffixing the name of the
698 per-collection refuse file in the same manner as described above for the
700 None of the refuse files are required to exist.
703 has a built-in default value of
704 .Ar /usr/local/etc/cvsup
711 but it is possible to override both of these. The value of
713 can be changed using the
719 (If both are used the
721 option will override the
725 can only be changed with the
729 command to change it.
731 As an example, suppose that the
735 both have their default values, and that the collection and release are
740 Assume further that checkout mode is being used with
742 The three possible refuse files would then be named:
744 .Bl -item -compact -offset indent
746 .Pa /usr/local/etc/cvsup/sup/refuse
748 .Pa /usr/local/etc/cvsup/sup/src-all/refuse
750 .Pa /usr/local/etc/cvsup/sup/src-all/refuse.cvs:RELENG_3
757 the refuse files would be:
759 .Bl -item -compact -offset indent
763 .Pa /foo/sup/src-all/refuse
765 .Pa /foo/sup/src-all/refuse.cvs:RELENG_3
776 .Bl -item -compact -offset indent
780 .Pa /bar/sup/src-all/refuse
782 .Pa /bar/sup/src-all/refuse.cvs:RELENG_3
790 .Bl -item -compact -offset indent
792 .Pa /bar/stool/refuse
794 .Pa /bar/stool/src-all/refuse
796 .Pa /bar/stool/src-all/refuse.cvs:RELENG_3
798 .Sh csup AND FIREWALLS
801 will work through any firewall which permits outbound connections to
802 port 5999 of the server host.
803 .Sh USING csup WITH SOCKS
805 can be used through a SOCKS proxy server with the standard
810 executable needs to be dynamically-linked with the system
814 .Sh USING ssh PORT FORWARDING
815 As an alternative to SOCKS, a user behind a firewall can penetrate it
816 with the TCP port forwarding provided by the Secure Shell package
818 The user must have a login account on the
820 server host in order to do this.
821 The procedure is as follows:
824 Establish a connection to the server host with
828 ssh -f -x -L 5999:localhost:5999 serverhost sleep 60
833 with the hostname of the CVSup server, but type
836 This sets up the required port forwarding.
842 Once the update has begun,
844 will keep the forwarded channels open as long as they are needed.
848 on the local host, including the arguments
853 .Bl -tag -width base/sup/collection/checkouts*xx -compact
854 .It Pa /usr/local/etc/cvsup
863 .It Xo Ar base / Ar collDir / Ar collection
875 http://mu.org/~mux/csup.html
879 .An Maxime Henrion Aq mux@FreeBSD.org
885 .An John Polstra Aq jdp@polstra.com
889 CVSup is a registered trademark of John D. Polstra.
892 is released under a 2-clauses BSD license.
894 An RCS file is not recognized as such unless its name ends with
899 is assumed to be a CVS Attic, and is treated specially.
projects / FreeBSD / FreeBSD.git / blob