man/orig/csup
Материал из Xgu.ru
Не указан параметр (1)
CSUP(1) FreeBSD General Commands Manual CSUP(1)
Содержание |
[править] NAME
csup — network distribution package for CVS repositories
[править] SYNOPSIS
csup [-146aksvzZ] [-A addr] [-b base] [-c collDir] [-d delLimit]
[-h host] [-i pattern] [-l lockfile] [-L verbosity] [-p port]
[-r maxRetries] supfile
[править] DESCRIPTION
csup is a software package for updating collections of files across a
network. It is a rewrite of the CVSup software in C. This manual page
describes the usage of the csup client program.
Unlike more traditional network distribution packages, such as rdist and
sup, csup has specific optimizations for distributing CVS repositories.
csup takes advantage of the properties of CVS repositories and the files
they contain (in particular, RCS files), enabling it to perform updates
much faster than traditional systems.
csup is a general-purpose network file updating package. It is extremely
fast, even for collections of files which have nothing to do with CVS or
RCS.
[править] OPTIONS
The client program csup requires at least a single argument, supfile. It
names a file describing one or more collections of files to be trans‐
ferred and/or updated from the server. The supfile has a format similar
to the corresponding file used by sup. In most cases, csup can use
existing sup supfiles.
The following options are supported by csup:
-1 Disables automatic retries when transient failures occur.
Without this option, a transient failure such as a dropped
network connection causes csup to retry repeatedly, using
randomized exponential backoff to space the retries. This
option is equivalent to -r 0.
-4 Forces csup to use IPv4 addresses only.
-6 Forces csup to use IPv6 addresses only.
-a Requires the server to authenticate itself (prove its iden‐
tity) to the client. If authentication of the server fails,
the update is canceled. See AUTHENTICATION, below.
-A addr Specifies a local address to bind to when connecting to the
server. The local address might be a hostname or a numeric
host address string consisting of a dotted decimal IPv4
address or an IPv6 address. This may be useful on hosts
which have multiple IP addresses.
-b base Specifies the base directory under which csup will maintain
its bookkeeping files, overriding any base specifications in
the supfile.
-c collDir Specifies the subdirectory of base where the information
about the collections is maintained. The default is sup.
-d delLimit
Specifies the maximum number of files that may be deleted in
a single update run. Any attempt to exceed the limit results
in a fatal error. This can provide some protection against
temporary configuration mistakes on the server. The default
limit is infinity.
-h host Specifies the server host to contact, overriding any host
specifications in the supfile.
-i pattern Causes csup to include only files and directories matching
pattern in the update. If a directory matches the pattern,
then the entire subtree rooted at the directory is included.
If this option is specified multiple times, the patterns are
combined using the ‘or’ operation. If no -i options are
given, the default is to update all files in each collection.
The pattern is a standard file name pattern. It is inter‐
preted relative to the collection's prefix directory. Slash
characters are matched only by explicit slashes in the pat‐
tern. Leading periods in file name are not treated spe‐
cially.
-k Causes csup to keep the temporary copies of any incorrectly
edited files, in the event of checksum mismatches. This
option is for debugging, to help determine why the files were
edited incorrectly. Regardless of whether this option is
specified, the permanent versions of faulty files are
replaced with correct versions obtained by transferring the
files in their entirety. Such transfers are called fixups.
-l lockfile
Creates and locks the lockfile while the update is in
progress. If lockfile is already locked, csup fails without
performing automatic retries. This option is useful when
csup is executed periodically from cron. It prevents a job
from interfering with an earlier job that is perhaps taking
extra long because of network problems.
The process-ID is written to the lock file in text form when
the lock is successfully acquired. Upon termination of the
update, the lock file is removed.
-L verbosity
Sets the verbosity level for output. A level of 0 causes
csup to be completely silent unless errors occur. A level of
1 (the default) causes each updated file to be listed. A
level of 2 provides more detailed information about the
updates performed on each file. All messages are directed to
the standard output.
-p port Sets the TCP port to which csup attempts to connect on the
server host. The default port is 5999.
-r maxRetries
Limits the number of automatic retries that will be attempted
when transient errors such as lost network connections are
encountered. By default, csup will retry indefinitely until
an update is successfully completed. The retries are spaced
using randomized exponential backoff. Note that -r 0 is
equivalent to the -1 option.
-s Suppresses the check of each client file's status against
what is recorded in the list file. Instead, the list file is
assumed to be accurate. This option greatly reduces the
amount of disk activity and results in faster updates with
less load on the client host. However it should only be used
if client's files are never modified locally in any way.
Mirror sites may find this option beneficial to reduce the
disk load on their systems. For safety, even mirror sites
should run csup occasionally (perhaps once a day) without the
-s option.
Without the -s option, csup performs a stat(2) call on each
file and verifies that its attributes match those recorded in
the list file. This ensures that any file changes made out‐
side of csup are detected and corrected.
If the -s option is used when one or more files have been
modified locally, the results are undefined. Local file dam‐
age may remain uncorrected, updates may be missed, or csup
may abort prematurely.
-v Prints the version number and exits, without contacting the
server.
-z Enables compression for all collections, as if the compress
keyword were added to every collection in the supfile.
-Z Disables compression for all collections, as if the compress
keyword were removed from every collection in the supfile.
The supfile is a text file which specifies the file collections to be
updated. Comments begin with ‘#’ and extend to the end of the line.
Lines that are empty except for comments and white space are ignored.
Each remaining line begins with the name of a server-defined collection
of files. Following the collection name on the line are zero or more
keywords or keyword=value pairs.
Default settings may be specified in lines whose collection name is
*default. Such defaults will apply to subsequent lines in the supfile.
Multiple *default lines may be present. New values augment or override
any defaults specified earlier in the supfile. Values specified explic‐
itly for a collection override any default values.
The most commonly used keywords are:
release=releaseName
This specifies the release of the files within a collection.
Like collection names, release names are defined by the
server configuration files. Usually there is only one
release in each collection, but there may be any number.
Collections which come from a CVS repository often use
release=cvs by convention. Non-CVS collections convention‐
ally use release=current.
base=base This specifies a directory under which csup will maintain its
bookkeeping files, describing the state of each collection on
the client machine. The base directory must already exist;
csup will not create it. The default base directory is
/usr/local/etc/csup.
prefix=prefix
This is the directory under which updated files will be
placed. By default, it is the same as base. If it is not an
absolute pathname, it is interpreted relative to base. The
prefix directory must already exist; csup will not create it.
As a special case, if prefix is a symbolic link pointing to a
nonexistent file named ‘SKIP’, then csup will skip the col‐
lection. The parameters associated with the collection are
still checked for validity, but none of its files will be
updated. This feature allows a site to use a standard
supfile on several machines, yet control which collections
get updated on a per-machine basis.
host=hostname
This specifies the server machine from which all files will
be taken. csup requires that all collections in a single run
come from the same host. If you wish to update collections
from several different hosts, you must run csup several
times.
delete The presence of this keyword gives csup permission to delete
files. If it is missing, no files will be deleted.
The presence of the delete keyword puts csup into so-called
exact mode. In exact mode, csup does its best to make the
client's files correspond to those on the server. This
includes deleting individual deltas and symbolic tags from
RCS files, as well as deleting entire files. In exact mode,
csup verifies every edited file with a checksum, to ensure
that the edits have produced a file identical to the master
copy on the server. If the checksum test fails for a file,
then csup falls back upon transferring the entire file.
In general, csup deletes only files which are known to the
server. Extra files present in the client's tree are left
alone, even in exact mode. More precisely, csup is willing
to delete two classes of files:
· Files that were previously created or updated by csup
itself.
· Checked-out versions of files which are marked as dead on
the server.
use-rel-suffix
Causes csup to append a suffix constructed from the release
and tag to the name of each list file that it maintains. See
THE LIST FILE for details.
compress This enables compression of all data sent across the network.
Compression is quite effective, normally eliminating 65% to
75% of the bytes that would otherwise need to be transferred.
However, it is costly in terms of CPU time on both the client
and the server. On local area networks, compression is gen‐
erally counter-productive; it actually slows down file
updates. On links with speeds of 56K bits/second or less,
compression is almost always beneficial. For network links
with speeds between these two extremes, let experimentation
be your guide.
The -z command line option enables the compress keyword for
all collections, regardless of what is specified in the sup‐
file. Likewise, the -Z command line option disables the
compress option for all collections. csup uses a looser
checksum for RCS files, which ignores harmless differences in
white space. Different versions of CVS and RCS produce a
variety of differences in white space for the same RCS files.
Thus the strict checksum can report spurious mismatches for
files which are logically identical. This can lead to numer‐
ous unneeded “fixups”, and thus to slow updates.
umask=n Causes csup to use a umask value of n (an octal number) when
updating the files in the collection. This option is ignored
if preserve is specified.
Some additional, more specialized keywords are described below. Unrecog‐
nized keywords are silently ignored for backward compatibility with sup.
[править] CVS MODE
CVSup supports two primary modes of operation. They are called CVS mode
and checkout mode.
In CVS mode, the client receives copies of the actual RCS files making up
the master CVS repository. CVS mode is the default mode of operation.
It is appropriate when the user wishes to maintain a full copy of the CVS
repository on the client machine.
CVS mode is also appropriate for file collections which are not based
upon a CVS repository. The files are simply transferred verbatim, with‐
out interpretation.
[править] CHECKOUT MODE
In checkout mode, the client receives specific revisions of files,
checked out directly from the server's CVS repository. Checkout mode
allows the client to receive any version from the repository, without
requiring any extra disk space on the server for storing multiple ver‐
sions in checked-out form. Checkout mode provides much flexibility
beyond that basic functionality, however. The client can specify any CVS
symbolic tag, or any date, or both, and csup will provide the correspond‐
ing checked-out versions of the files in the repository.
Checkout mode is selected on a per-collection basis, by the presence of
one or both of the following keywords in the supfile:
tag=tagname
This specifies a symbolic tag that should be used to select
the revisions that are checked out from the CVS repository.
The tag may refer to either a branch or a specific revision.
It must be symbolic; numeric revision numbers are not sup‐
ported.
For the FreeBSD source repository, the most commonly used
tags will be:
RELENG_6 The ‘stable’ branch.
. The main branch (the ‘current’ release). This is
the default, if only the date keyword is given.
date=[cc]yy.mm.dd.hh.mm.ss
This specifies a date that should be used to select the revi‐
sions that are checked out from the CVS repository. The
client will receive the revisions that were in effect at the
specified date and time.
At present, the date format is inflexible. All 17 or 19
characters must be specified, exactly as shown. For the
years 2000 and beyond, specify the century cc. For earlier
years, specify only the last two digits yy. Dates and times
are considered to be GMT. The default date is ‘.’, which
means “as late as possible”.
To enable checkout mode, you must specify at least one of these keywords.
If both are missing, csup defaults to CVS mode.
If both a branch tag and a date are specified, then the revisions on the
given branch, as of the given date, will be checked out. It is permit‐
ted, but not particularly useful, to specify a date with a specific
release tag.
In checkout mode, the tag and/or date may be changed between updates.
For example, suppose that a collection has been transferred using the
specification ‘tag=.’. The user could later change the specification to
‘tag=RELENG_3’. This would cause csup to edit the checked-out files in
such a way as to transform them from the ‘current’ versions to the
‘stable’ versions. In general, csup is willing to transform any tag/date
combination into any other tag/date combination, by applying the inter‐
vening RCS deltas to the existing files.
When transforming a collection of checked-out files from one tag to
another, it is important to specify the list keyword in the supfile, to
ensure that the same list file is used both before and after the trans‐
formation. The list file is described in THE LIST FILE, below.
[править] THE LIST FILE
For efficiency, csup maintains a bookkeeping file for each collection,
called the list file. The list file contains information about which
files and revisions the client currently possesses. It also contains
information used for verifying that the list file is consistent with the
actual files in the client's tree.
The list file is not strictly necessary. If it is deleted, or becomes
inconsistent with the actual client files, csup falls back upon a less
efficient method of identifying the client's files and performing its
updates. Depending on csup's mode of operation, the fallback method
employs time stamps, checksums, or analysis of RCS files.
Because the list file is not essential, csup is able to “adopt” an exist‐
ing file tree acquired by FTP or from a CD-ROM. csup identifies the
client's versions of the files, updates them as necessary, and creates a
list file for future use. Adopting a foreign file tree is not as fast as
performing a normal update. It also produces a heavier load on the
server.
The list file is stored in a collection-specific directory; see FILES for
details. Its name always begins with ‘checkouts’. If the keyword
use-rel-suffix is specified in the supfile, a suffix, formed from the
release and tag, is appended to the name. The default suffix can be
overridden by specifying an explicit suffix in the supfile:
list=suffix
This specifies a suffix for the name of the list file. A
leading dot is provided automatically. For example,
‘list=stable’ would produce a list file named
checkouts.stable, regardless of the release, tag, or
use-rel-suffix keyword.
[править] REFUSE FILES
The user can specify sets of files that he does not wish to receive. The
files are specified as file name patterns in so-called refuse files. The
patterns are separated by whitespace, and multiple patterns are permitted
on each line. Files and directories matching the patterns are neither
updated nor deleted; they are simply ignored.
There is currently no provision for comments in refuse files.
The patterns are similar to those of sh(1), except that there is no spe‐
cial treatment for slashes or for filenames that begin with a period.
For example, the pattern ‘*.c’ will match any file name ending with ‘.c’
including those in subdirectories, such as ‘foo/bar/lam.c’. All patterns
are interpreted relative to the collection's prefix directory.
If the files are coming from a CVS repository, as is usually the case,
then they will be RCS files. These have a ‘,v’ suffix which must be taken
into account in the patterns. For example, the FreeBSD documentation
files are in a sub-directory of base called ‘doc’. If ‘Makefile’ from
that directory is not required then the line
doc/Makefile
will not work because the file on the server is called ‘Makefile,v.’ A
better solution would be
doc/Makefile*
which will match whether ‘Makefile’ is an RCS file or not.
As another example, to receive the FreeBSD documentation files without
the Japanese, Russian, and Chinese translations, create a refuse file
containing the following lines:
doc/ja*
doc/ru*
doc/zh*
As many as three refuse files are examined for each supfile line. There
can be a global refuse file named base/collDir/refuse which applies to
all collections and releases. There can be a per-collection refuse file
named base/collDir/collection/refuse which applies to a specific collec‐
tion. Finally, there can be a per-release and tag refuse file which
applies only to a given release/tag combination within a collection. The
name of the latter is formed by suffixing the name of the per-collection
refuse file in the same manner as described above for the list file.
None of the refuse files are required to exist.
csup has a built-in default value of /usr/local/etc/cvsup for base and
sup for collDir but it is possible to override both of these. The value
of base can be changed using the -b option or a base=pathname entry in
the supfile. (If both are used the -b option will override the supfile
entry.) The value of collDir can only be changed with the -c option;
there is no supfile command to change it.
As an example, suppose that the base and collDir both have their default
values, and that the collection and release are ‘src-all’ and ‘cvs’,
respectively. Assume further that checkout mode is being used with
‘tag=RELENG_3’. The three possible refuse files would then be named:
/usr/local/etc/cvsup/sup/refuse
/usr/local/etc/cvsup/sup/src-all/refuse
/usr/local/etc/cvsup/sup/src-all/refuse.cvs:RELENG_3
If the supfile includes the command base=/foo the refuse files would be:
/foo/sup/refuse
/foo/sup/src-all/refuse
/foo/sup/src-all/refuse.cvs:RELENG_3
If -b /bar is used (even with base=/foo in the supfile):
/bar/sup/refuse
/bar/sup/src-all/refuse
/bar/sup/src-all/refuse.cvs:RELENG_3
and with -c stool as well:
/bar/stool/refuse
/bar/stool/src-all/refuse
/bar/stool/src-all/refuse.cvs:RELENG_3
[править] AUTHENTICATION
csup implements an optional authentication mechanism which can be used by
the client and server to verify each other's identities. Public CVSup
servers normally do not enable authentication. csup users may ignore
this section unless they have been informed that authentication is
required by the administrator of their server.
The authentication subsystem uses a challenge-response protocol which is
immune to packet sniffing and replay attacks. No passwords are sent over
the network in either direction. Both the client and the server can
independently verify the identities of each other.
The file $HOME/.csup/auth holds the information used for authentication.
This file contains a record for each server that the client is allowed to
access. Each record occupies one line in the file. Lines beginning with
‘#’ are ignored, as are lines containing only white space. White space
is significant everywhere else in the file. Fields are separated by ‘:’
characters.
Each record of the file has the following form:
serverName:clientName:password:comment
All fields must be present even if some of them are empty. ServerName is
the name of the server to which the record applies. By convention, it is
the canonical fully-qualified domain name of the server, e.g.,
‘CVSup177.FreeBSD.ORG’. This must agree with the server's own idea of
its name. The name is case-insensitive.
ClientName is the name the client uses to gain access to the server. By
convention, e-mail addresses are used for all client names, e.g.,
‘BillyJoe@FreeBSD.org’. Client names are case-insensitive.
Password is a secret string of characters that the client uses to prove
its identity. It may not contain any ‘:’ or newline characters.
Comment may contain any additional information to identify the record.
It is not interpreted by the program.
To set up authentication for a given server, one must perform the follow‐
ing steps:
1. Obtain the official serverName from the administrator of the server
or from some other source.
2. Choose an appropriate clientName. It should be in the form of a
valid e-mail address, to make it easy for the server administrator
to contact the user if necessary.
3. Choose an arbitrary secret password.
4. Run the cpasswd utility, and type in the password when prompted for
it. The utility will print out a line to send to the server admin‐
istrator, and instruct you how to modify your $HOME/.csup/auth file.
You should use a secure channel to send the line to the server
administrator.
Since $HOME/.csup/auth contains passwords, you should ensure that it is
not readable by anyone except yourself.
Authentication works independently in both directions. The server admin‐
istrator controls whether you must prove your identity. You control
whether to check the server's identity, by means of the -a command line
option.
[править] csup AND FIREWALLS
In its default mode, csup will work through any firewall which permits
outbound connections to port 5999 of the server host.
[править] USING csup WITH SOCKS
csup can be used through a SOCKS proxy server with the standard runsocks
command. Your csup executable needs to be dynamically-linked with the
system libraries for runsocks to work properly.
[править] USING ssh PORT FORWARDING
As an alternative to SOCKS, a user behind a firewall can penetrate it
with the TCP port forwarding provided by the Secure Shell package ssh.
The user must have a login account on the CVSup server host in order to
do this. The procedure is as follows:
1. Establish a connection to the server host with ssh, like this:
ssh -f -x -L 5999:localhost:5999 serverhost sleep 60
Replace serverhost with the hostname of the CVSup server, but type
‘localhost’ literally. This sets up the required port forwarding.
You must start csup before the 60-second sleep finishes. Once the
update has begun, ssh will keep the forwarded channels open as long
as they are needed.
2. Run csup on the local host, including the arguments ‘-h localhost’
on the command line.
[править] FILES
/usr/local/etc/cvsup Default base directory.
sup Default collDir subdirectory.
base/collDir/collection/checkouts*
List files.
[править] SEE ALSO
cpasswd(1), cvs(1), rcsintro(1), ssh(1).
[править] AUTHORS
Maxime Henrion <mux@FreeBSD.org> is the author of csup, the rewrite of
CVSup in C. John Polstra <jdp@polstra.com> is the author of CVSup.
[править] LEGALITIES
CVSup is a registered trademark of John D. Polstra.
csup is released under a 2-clauses BSD license.
[править] BUGS
An RCS file is not recognized as such unless its name ends with ‘,v’.
Any directory named ‘Attic’ is assumed to be a CVS Attic, and is treated
specially.
FreeBSD February 1, 2006 FreeBSD
