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 Requires the server to authenticate itself (prove its identity) to
111 the client. If authentication of the server fails, the update is
116 Specifies a local address to bind to when connecting to the server.
117 The local address might be a hostname or a numeric host address string
118 consisting of a dotted decimal IPv4 address or an IPv6 address.
119 This may be useful on hosts which have multiple IP addresses.
121 Specifies the base directory under which
123 will maintain its bookkeeping files, overriding any
125 specifications in the
128 Specifies the subdirectory of
130 where the information about the collections is maintained.
134 Specifies the maximum number of files that may be deleted in a
136 Any attempt to exceed the limit results in a fatal error.
137 This can provide some protection against temporary configuration
138 mistakes on the server.
139 The default limit is infinity.
141 Specifies the server host to contact, overriding any
143 specifications in the
148 to include only files and directories matching
150 in the update. If a directory matches the pattern, then the entire
151 subtree rooted at the directory is included. If this option is
152 specified multiple times, the patterns are combined using the
156 options are given, the default is to update all files in each
161 is a standard file name pattern.
162 It is interpreted relative to the collection's prefix directory.
163 Slash characters are matched only by explicit slashes in the pattern.
164 Leading periods in file name are not treated specially.
168 to keep the temporary copies of any incorrectly edited files, in the
169 event of checksum mismatches.
170 This option is for debugging, to help determine why the files were
172 Regardless of whether this option is specified, the permanent versions
173 of faulty files are replaced with correct versions obtained by
174 transferring the files in their entirety.
175 Such transfers are called fixups.
177 Creates and locks the
179 while the update is in progress.
184 fails without performing automatic retries.
185 This option is useful when
187 is executed periodically from
189 It prevents a job from interfering with an earlier job that is perhaps
190 taking extra long because of network problems.
192 The process-ID is written to the lock file in text form when the lock
193 is successfully acquired.
194 Upon termination of the update, the lock file is removed.
195 .It Fl L Ar verbosity
196 Sets the verbosity level for output.
199 to be completely silent unless errors occur.
200 A level of 1 (the default) causes each updated file to be listed.
201 A level of 2 provides more detailed information about the updates
202 performed on each file.
203 All messages are directed to the standard output.
205 Sets the TCP port to which
207 attempts to connect on the server host.
208 The default port is 5999.
209 .It Fl r Ar maxRetries
210 Limits the number of automatic retries that will be attempted when
211 transient errors such as lost network connections are encountered.
214 will retry indefinitely until an update is successfully completed.
215 The retries are spaced using randomized exponential backoff.
222 Suppresses the check of each client file's status against what is
223 recorded in the list file. Instead, the list file is assumed to be
224 accurate. This option greatly reduces the amount of disk activity and
225 results in faster updates with less load on the client host. However
226 it should only be used if client's files are never modified locally in
227 any way. Mirror sites may find this option beneficial to reduce the
228 disk load on their systems. For safety, even mirror sites should run
230 occasionally (perhaps once a day) without the
240 call on each file and verifies that its attributes match those
241 recorded in the list file. This ensures that any file changes made
244 are detected and corrected.
248 option is used when one or more files have been modified locally, the
249 results are undefined. Local file damage may remain uncorrected,
250 updates may be missed, or
252 may abort prematurely.
254 Prints the version number and exits, without contacting the server.
256 Enables compression for all collections, as if the
258 keyword were added to every collection in the
261 Disables compression for all collections, as if the
263 keyword were removed from every collection in the
269 is a text file which specifies the file collections to be updated.
272 and extend to the end of the line. Lines that are empty except for
273 comments and white space are ignored. Each remaining line begins
274 with the name of a server-defined collection of files. Following the
275 collection name on the line are zero or more keywords or keyword=value
278 Default settings may be specified in lines whose collection name is
280 Such defaults will apply to subsequent lines in the
284 lines may be present.
285 New values augment or override any defaults specified earlier in the
287 Values specified explicitly for a collection override any default
290 The most commonly used keywords are:
292 .It Cm release= Ns Ar releaseName
293 This specifies the release of the files within a collection.
294 Like collection names, release names are defined by the server
295 configuration files. Usually there is only one release in each
296 collection, but there may be any number. Collections which come from
297 a CVS repository often use
299 by convention. Non-CVS collections conventionally use
300 .Cm release=current .
301 .It Cm base= Ns Ar base
302 This specifies a directory under which
304 will maintain its bookkeeping files, describing the state of each
305 collection on the client machine.
308 directory must already exist;
314 .Pa /usr/local/etc/cvsup .
315 .It Cm prefix= Ns Ar prefix
316 This is the directory under which updated files will be placed.
317 By default, it is the same as
319 If it is not an absolute pathname, it is interpreted relative to
323 directory must already exist;
327 As a special case, if
329 is a symbolic link pointing to a nonexistent file named
333 will skip the collection.
334 The parameters associated with the collection are still checked for
335 validity, but none of its files will be updated.
336 This feature allows a site to use a standard
338 on several machines, yet control which collections get updated on a
340 .It Cm host= Ns Ar hostname
341 This specifies the server machine from which all files will be taken.
343 requires that all collections in a single run come from the same host.
344 If you wish to update collections from several different hosts, you must
349 The presence of this keyword gives
351 permission to delete files.
352 If it is missing, no files will be deleted.
362 does its best to make the client's files correspond to those on the server.
363 This includes deleting individual deltas and symbolic tags from RCS
364 files, as well as deleting entire files.
367 verifies every edited file with a checksum, to ensure that the edits
368 have produced a file identical to the master copy on the server.
369 If the checksum test fails for a file, then
371 falls back upon transferring the entire file.
375 deletes only files which are known to the server.
376 Extra files present in the client's tree are left alone, even in exact
380 is willing to delete two classes of files:
383 Files that were previously created or updated by
387 Checked-out versions of files which are marked as dead on the server.
389 .It Cm use-rel-suffix
392 to append a suffix constructed from the release and tag to the name of
393 each list file that it maintains.
398 This enables compression of all data sent across the network.
399 Compression is quite effective, normally eliminating 65% to 75% of the
400 bytes that would otherwise need to be transferred.
401 However, it is costly in terms of CPU time on both the client and the
403 On local area networks, compression is generally counter-productive; it
404 actually slows down file updates.
405 On links with speeds of 56K bits/second or less, compression is almost
407 For network links with speeds between these two extremes, let
408 experimentation be your guide.
412 command line option enables the
414 keyword for all collections, regardless of what is specified in the supfile.
417 command line option disables the
419 option for all collections.
421 uses a looser checksum for RCS files, which ignores harmless
422 differences in white space. Different versions of CVS and RCS produce
423 a variety of differences in white space for the same RCS files. Thus
424 the strict checksum can report spurious mismatches for files which are
425 logically identical. This can lead to numerous unneeded
427 and thus to slow updates.
428 .It Cm umask= Ns Ar n
431 to use a umask value of
433 (an octal number) when updating the files in the collection.
434 This option is ignored if
439 Some additional, more specialized keywords are described below.
440 Unrecognized keywords are silently ignored for backward compatibility
445 supports two primary modes of operation.
452 In CVS mode, the client receives copies of the actual RCS files making
453 up the master CVS repository. CVS mode is the default mode of operation.
454 It is appropriate when the user wishes to maintain a full copy of the
455 CVS repository on the client machine.
457 CVS mode is also appropriate for file collections which are not
458 based upon a CVS repository. The files are simply transferred
459 verbatim, without interpretation.
461 In checkout mode, the client receives specific revisions of files,
462 checked out directly from the server's CVS repository.
463 Checkout mode allows the client to receive any version from the
464 repository, without requiring any extra disk space on the server for
465 storing multiple versions in checked-out form.
466 Checkout mode provides much flexibility beyond that basic functionality,
468 The client can specify any CVS symbolic tag, or any date, or both, and
470 will provide the corresponding checked-out versions of the files in the
473 Checkout mode is selected on a per-collection basis, by the presence of
474 one or both of the following keywords in the
477 .It Cm tag= Ns Ar tagname
478 This specifies a symbolic tag that should be used to select the
479 revisions that are checked out from the CVS repository.
480 The tag may refer to either a branch or a specific revision.
481 It must be symbolic; numeric revision numbers are not supported.
483 For the FreeBSD source repository, the most commonly used tags will be:
484 .Bl -tag -width RELENG_6
493 This is the default, if only the
500 .Ar yy.mm.dd.hh.mm.ss
503 This specifies a date that should be used to select the revisions that
504 are checked out from the CVS repository.
505 The client will receive the revisions that were in effect at the
506 specified date and time.
508 At present, the date format is inflexible. All 17 or 19 characters must
509 be specified, exactly as shown.
510 For the years 2000 and beyond, specify the century
512 For earlier years, specify only the last two digits
514 Dates and times are considered to
519 .Dq as late as possible .
522 To enable checkout mode, you must specify at least one of these keywords.
525 defaults to CVS mode.
527 If both a branch tag and a date are specified, then the revisions on the
528 given branch, as of the given date, will be checked out. It is
529 permitted, but not particularly useful, to specify a date with a
530 specific release tag.
532 In checkout mode, the tag and/or date may be changed between updates.
533 For example, suppose that a collection has been transferred using the
536 The user could later change the specification to
540 to edit the checked-out files in such a way as to transform them from the
547 is willing to transform any tag/date combination into any other tag/date
548 combination, by applying the intervening RCS deltas to the existing files.
550 When transforming a collection of checked-out files from one tag to
551 another, it is important to specify the
555 to ensure that the same list file is used both before and after the
557 The list file is described in
563 maintains a bookkeeping file for each collection, called the list file.
564 The list file contains information about which files and revisions the client
566 It also contains information used for verifying that the list file
567 is consistent with the actual files in the client's tree.
569 The list file is not strictly necessary. If it is deleted, or becomes
570 inconsistent with the actual client files,
572 falls back upon a less efficient method of identifying the client's
573 files and performing its updates.
576 mode of operation, the fallback method employs time stamps, checksums, or
577 analysis of RCS files.
579 Because the list file is not essential,
583 an existing file tree acquired by FTP or from a CD-ROM.
585 identifies the client's versions of the files, updates them as
586 necessary, and creates a list file for future use.
587 Adopting a foreign file tree is not as fast as performing a normal
589 It also produces a heavier load on the server.
591 The list file is stored in a collection-specific directory; see
594 Its name always begins with
600 a suffix, formed from the release and tag, is appended to the name.
601 The default suffix can be overridden by specifying an explicit suffix in
605 .It Cm list= Ns Ar suffix
606 This specifies a suffix for the name of the list file. A leading dot is
607 provided automatically.
610 would produce a list file named
611 .Pa checkouts.stable ,
612 regardless of the release, tag, or
617 The user can specify sets of files that he does not wish to receive.
618 The files are specified as file name patterns in so-called
621 The patterns are separated by whitespace, and multiple patterns are
622 permitted on each line.
623 Files and directories matching the patterns are neither updated nor
624 deleted; they are simply ignored.
626 There is currently no provision for comments in refuse files.
628 The patterns are similar to those of
630 except that there is no special treatment for slashes or for
631 filenames that begin with a period.
632 For example, the pattern
634 will match any file name ending with
636 including those in subdirectories, such as
638 All patterns are interpreted relative to the collection's prefix
641 If the files are coming from a CVS repository, as is usually
642 the case, then they will be RCS files. These have a
644 suffix which must be taken into account in the patterns. For
645 example, the FreeBSD documentation files are in a sub-directory of
651 from that directory is not required then the line
653 .Bl -item -compact -offset indent
658 will not work because the file on the server is called
660 A better solution would be
662 .Bl -item -compact -offset indent
667 which will match whether
669 is an RCS file or not.
671 As another example, to receive the FreeBSD documentation files without
672 the Japanese, Russian, and Chinese translations, create a refuse file
673 containing the following lines:
675 .Bl -item -compact -offset indent
684 As many as three refuse files are examined for each
687 There can be a global refuse file named
689 .Ar base / Ar collDir Pa /refuse
691 which applies to all collections and releases.
692 There can be a per-collection refuse file named
694 .Xo Ar base / Ar collDir / Ar collection
698 which applies to a specific collection.
699 Finally, there can be a per-release and tag refuse file which applies only
700 to a given release/tag combination within a collection.
701 The name of the latter is formed by suffixing the name of the
702 per-collection refuse file in the same manner as described above for the
704 None of the refuse files are required to exist.
707 has a built-in default value of
708 .Ar /usr/local/etc/cvsup
715 but it is possible to override both of these. The value of
717 can be changed using the
723 (If both are used the
725 option will override the
729 can only be changed with the
733 command to change it.
735 As an example, suppose that the
739 both have their default values, and that the collection and release are
744 Assume further that checkout mode is being used with
746 The three possible refuse files would then be named:
748 .Bl -item -compact -offset indent
750 .Pa /usr/local/etc/cvsup/sup/refuse
752 .Pa /usr/local/etc/cvsup/sup/src-all/refuse
754 .Pa /usr/local/etc/cvsup/sup/src-all/refuse.cvs:RELENG_3
761 the refuse files would be:
763 .Bl -item -compact -offset indent
767 .Pa /foo/sup/src-all/refuse
769 .Pa /foo/sup/src-all/refuse.cvs:RELENG_3
780 .Bl -item -compact -offset indent
784 .Pa /bar/sup/src-all/refuse
786 .Pa /bar/sup/src-all/refuse.cvs:RELENG_3
794 .Bl -item -compact -offset indent
796 .Pa /bar/stool/refuse
798 .Pa /bar/stool/src-all/refuse
800 .Pa /bar/stool/src-all/refuse.cvs:RELENG_3
804 implements an optional authentication mechanism which can be used by the
805 client and server to verify each other's identities.
806 Public CVSup servers normally do not enable authentication.
808 users may ignore this section unless they have been informed
809 that authentication is required by the administrator of their server.
811 The authentication subsystem uses a
812 challenge-response protocol which is immune to packet sniffing and
813 replay attacks. No passwords are sent over the network in either
814 direction. Both the client and the server can independently verify
815 the identities of each other.
818 .Li $ Ns Ev HOME Ns Pa /.csup/auth
819 holds the information used for authentication. This file contains a
820 record for each server that the client is allowed to access. Each
821 record occupies one line in the file. Lines beginning with
823 are ignored, as are lines containing only white space. White space is
824 significant everywhere else in the file. Fields are separated by
828 Each record of the file has the following form:
829 .Bd -literal -offset indent
831 .Xo Ar serverName No : Ar clientName No :
832 .Ar password No : Ar comment
837 All fields must be present even if some of them are empty.
839 is the name of the server to which the record applies. By convention,
840 it is the canonical fully-qualified domain name of the server, e.g.,
841 .Ql CVSup177.FreeBSD.ORG .
842 This must agree with the server's own idea of its name. The name is
846 is the name the client uses to gain access to the server. By
847 convention, e-mail addresses are used for all client names, e.g.,
848 .Ql BillyJoe@FreeBSD.org .
849 Client names are case-insensitive.
852 is a secret string of characters that the client uses to prove its
853 identity. It may not contain any
855 or newline characters.
858 may contain any additional information to identify the record. It
859 is not interpreted by the program.
861 To set up authentication for a given server, one must perform the
867 from the administrator of the server or from some other source.
869 Choose an appropriate
871 It should be in the form of a valid e-mail address, to make it easy
872 for the server administrator to contact the user if necessary.
874 Choose an arbitrary secret
879 utility, and type in the
881 when prompted for it. The utility will print out a line to send
882 to the server administrator, and instruct you how to modify your
883 .Li $ Ns Ev HOME Ns Pa /.csup/auth
884 file. You should use a secure channel to send the line to the
885 server administrator.
889 .Li $ Ns Ev HOME Ns Pa /.csup/auth
890 contains passwords, you should ensure that it is not readable by
891 anyone except yourself.
893 Authentication works independently in both directions. The server
894 administrator controls whether you must prove your identity.
895 You control whether to check the server's identity, by means of the
898 .Sh csup AND FIREWALLS
901 will work through any firewall which permits outbound connections to
902 port 5999 of the server host.
903 .Sh USING csup WITH SOCKS
905 can be used through a SOCKS proxy server with the standard
910 executable needs to be dynamically-linked with the system
914 .Sh USING ssh PORT FORWARDING
915 As an alternative to SOCKS, a user behind a firewall can penetrate it
916 with the TCP port forwarding provided by the Secure Shell package
918 The user must have a login account on the
920 server host in order to do this.
921 The procedure is as follows:
924 Establish a connection to the server host with
928 ssh -f -x -L 5999:localhost:5999 serverhost sleep 60
933 with the hostname of the CVSup server, but type
936 This sets up the required port forwarding.
942 Once the update has begun,
944 will keep the forwarded channels open as long as they are needed.
948 on the local host, including the arguments
953 .Bl -tag -width base/sup/collection/checkouts*xx -compact
954 .It Pa /usr/local/etc/cvsup
963 .It Xo Ar base / Ar collDir / Ar collection
976 .An Maxime Henrion Aq mux@FreeBSD.org
982 .An John Polstra Aq jdp@polstra.com
986 CVSup is a registered trademark of John D. Polstra.
989 is released under a 2-clauses BSD license.
991 An RCS file is not recognized as such unless its name ends with
996 is assumed to be a CVS Attic, and is treated specially.
projects / FreeBSD / releng / 9.2.git / blob