cvsup
has been deprecated by the
project, and its use is not recommended.
Subversion should be used
instead.
CVSup is a software package for distributing and updating source trees from a master CVS repository on a remote server host. The FreeBSD sources are maintained in a CVS repository on a central development machine in California. With CVSup, FreeBSD users can easily keep their own source trees up to date.
CVSup uses the so-called
pull model of updating. Under the pull
model, each client asks the server for updates, if and when
they are wanted. The server waits passively for update
requests from its clients. Thus all updates are instigated by
the client. The server never sends unsolicited updates.
Users must either run the CVSup
client manually to get an update, or they must set up a
cron
job to run it automatically on a
regular basis.
The term CVSup, capitalized
just so, refers to the entire software package. Its main
components are the client cvsup
which runs
on each user's machine, and the server
cvsupd
which runs at each of the FreeBSD
mirror sites.
The csup utility is a rewrite of the CVSup software in C. Its biggest advantage is, that it is faster and does not depend on the Modula-3 language, thus you do not need to install it as a requirement. Moreover you can use it out-of-the-box, since it is included in the base system. If you decided to use csup, just skip the steps on the installation of CVSup and substitute the references of CVSup with csup while following the remainder of this article.
The easiest way to install
CVSup is to use the precompiled
net/cvsup
package from the
FreeBSD packages collection. If you
prefer to build CVSup from source,
you can use the net/cvsup
port instead. But be forewarned: the net/cvsup
port depends on the
Modula-3 system, which takes a substantial amount of time and
disk space to download and build.
If you are going to be using
CVSup on a machine which will not
have Xorg installed, such as a
server, be sure to use the port which does not include the
CVSup GUI,
net/cvsup-without-gui
.
CVSup's operation is controlled
by a configuration file called the
supfile
. There are some sample
supfiles
in the directory /usr/share/examples/cvsup/
.
The information in a supfile
answers
the following questions for
CVSup:
In the following sections, we will construct a typical
supfile
by answering each of these
questions in turn. First, we describe the overall structure
of a supfile
.
A supfile
is a text file. Comments
begin with #
and extend to the end of the
line. Lines that are blank and lines that contain only
comments are ignored.
Each remaining line describes a set of files that the user
wishes to receive. The line begins with the name of a
“collection”, a logical grouping of files defined
by the server. The name of the collection tells the server
which files you want. After the collection name come zero or
more fields, separated by white space. These fields answer
the questions listed above. There are two types of fields:
flag fields and value fields. A flag field consists of a
keyword standing alone, e.g., delete
or
compress
. A value field also begins with a
keyword, but the keyword is followed without intervening white
space by =
and a second word. For example,
release=cvs
is a value field.
A supfile
typically specifies more
than one collection to receive. One way to structure a
supfile
is to specify all of the relevant
fields explicitly for each collection. However, that tends to
make the supfile
lines quite long, and it
is inconvenient because most fields are the same for all of
the collections in a supfile
.
CVSup provides a defaulting
mechanism to avoid these problems. Lines beginning with the
special pseudo-collection name *default
can
be used to set flags and values which will be used as defaults
for the subsequent collections in the
supfile
. A default value can be
overridden for an individual collection, by specifying a
different value with the collection itself. Defaults can also
be changed or augmented in mid-supfile by additional
*default
lines.
With this background, we will now proceed to construct a
supfile
for receiving and updating the
main source tree of
FreeBSD-CURRENT.
Which files do you want to receive?
The files available via
CVSup are organized into named
groups called “collections”. The collections
that are available are described in the
following section. In
this example, we wish to receive the entire main source
tree for the FreeBSD system. There is a single large
collection src-all
which will give us
all of that. As a first step toward constructing our
supfile
, we simply list the
collections, one per line (in this case, only one
line):
Which version(s) of them do you want?
With CVSup, you can receive
virtually any version of the sources that ever existed.
That is possible because the
cvsupd server works directly
from the CVS repository, which contains all of the
versions. You specify which one of them you want using
the tag=
and date=
value fields.
Be very careful to specify any
tag=
fields correctly. Some tags are
valid only for certain collections of files. If you
specify an incorrect or misspelled tag,
CVSup will delete files which
you probably do not want deleted. In particular, use
only tag=.
for
the ports-*
collections.
The tag=
field names a symbolic tag
in the repository. There are two kinds of tags, revision
tags and branch tags. A revision tag refers to a specific
revision. Its meaning stays the same from day to day. A
branch tag, on the other hand, refers to the latest
revision on a given line of development, at any given
time. Because a branch tag does not refer to a specific
revision, it may mean something different tomorrow than it
means today.
Section A.8, “CVS Tags” contains branch tags that
users might be interested in. When specifying a tag in
CVSup's configuration file, it
must be preceded with tag=
(RELENG_8
will become
tag=RELENG_8
).
Keep in mind that only the tag=.
is
relevant for the Ports Collection.
Be very careful to type the tag name exactly as shown. CVSup cannot distinguish between valid and invalid tags. If you misspell the tag, CVSup will behave as though you had specified a valid tag which happens to refer to no files at all. It will delete your existing sources in that case.
When you specify a branch tag, you normally receive
the latest versions of the files on that line of
development. If you wish to receive some past version,
you can do so by specifying a date with the
date=
value field. The cvsup(1)
manual page explains how to do that.
For our example, we wish to receive FreeBSD-CURRENT. We
add this line at the beginning of our
supfile
:
There is an important special case that comes into
play if you specify neither a tag=
field nor a date=
field. In that case,
you receive the actual RCS files directly from the
server's CVS repository, rather than receiving a
particular version. Developers generally prefer this mode
of operation. By maintaining a copy of the repository
itself on their systems, they gain the ability to browse
the revision histories and examine past versions of files.
This gain is achieved at a large cost in terms of disk
space, however.
Where do you want to get them from?
We use the host=
field to tell
cvsup
where to obtain its updates. Any
of the
CVSup mirror sites
will do, though you should try to select one that is close
to you in cyberspace. In this example we will use a
fictional FreeBSD distribution site,
cvsup99.FreeBSD.org
:
You will need to change the host to one that actually
exists before running CVSup.
On any particular run of cvsup
, you can
override the host setting on the command line, with
-h
.hostname
Where do you want to put them on your own machine?
The prefix=
field tells
cvsup
where to put the files it
receives. In this example, we will put the source files
directly into our main source tree,
/usr/src
. The
src
directory is already implicit in
the collections we have chosen to receive, so this is the
correct specification:
Where should
cvsup
maintain its status files?
The CVSup client maintains
certain status files in what is called the
“base” directory. These files help
CVSup to work more efficiently,
by keeping track of which updates you have already
received. We will use the standard base directory,
/var/db
:
If your base directory does not already exist, now
would be a good time to create it. The
cvsup
client will refuse to run if the
base directory does not exist.
Miscellaneous supfile
settings:
There is one more line of boiler plate that normally
needs to be present in the
supfile
:
release=cvs
indicates that the
server should get its information out of the main FreeBSD CVS
repository. This is virtually always the case, but there
are other possibilities which are beyond the scope of this
discussion.
delete
gives
CVSup permission to delete
files. You should always specify this, so that
CVSup can keep your source tree
fully up-to-date. CVSup is
careful to delete only those files for which it is
responsible. Any extra files you happen to have will be
left strictly alone.
use-rel-suffix
is ... arcane. If
you really want to know about it, see the cvsup(1)
manual page. Otherwise, just specify it and do not worry
about it.
compress
enables the use of
gzip-style compression on the communication channel. If
your network link is T1 speed or faster, you probably
should not use compression. Otherwise, it helps
substantially.
Putting it all together:
Here is the entire supfile
for
our example:
As mentioned above, CVSup
uses a pull method. Basically, this
means that you connect to the
CVSup server, and it says,
“Here is what you can download from me...”, and
your client responds
“OK, I will take this, this, this, and this.”
In the default configuration, the
CVSup client will take every file
associated with the collection and tag you chose in the
configuration file. In order to download a partial tree,
use the refuse
file.
The refuse
file tells
CVSup that it should not take
every single file from a collection; in other words, it
tells the client to refuse certain
files from the server. The refuse
file
can be found (or, if you do not yet have one, should be
placed) in
.
base
/sup/base
is defined in your
supfile
; our defined
base
is
/var/db
, which means that by default
the refuse
file is
/var/db/sup/refuse
.
The refuse
file has a very simple
format; it simply contains the names of files or directories
that you do not wish to download. For example:
Users who are on
slow links or pay by the minute for their Internet
connection will be able to save time as they will
no longer need to download files that they will never use.
For more information on refuse
files
and other neat features of CVSup,
please view its manual page.
You are now ready to try an update. The command line for doing this is quite simple:
#
cvsup supfile
where
is of
course the name of the supfile
supfile
you have
just created. Assuming you are running under X11,
cvsup
will display a GUI window with some
buttons to do the usual things. Press the
button, and watch it run.
Since you are updating your actual
/usr/src
tree in this example, you will
need to run the program as root
so that
cvsup
has the permissions it needs to
update your files. Having just created your configuration
file, and having never used this program before, that might
understandably make you nervous. There is an easy way to do a
trial run without touching your precious files. Just create
an empty directory somewhere convenient, and name it as an
extra argument on the command line:
#
mkdir /var/tmp/dest
#
cvsup supfile /var/tmp/dest
The directory you specify will be used as the destination
directory for all file updates.
CVSup will examine your usual files
in /usr/src
, but it will not modify or
delete any of them. Any file updates will instead land in
/var/tmp/dest/usr/src
.
CVSup will also leave its base
directory status files untouched when run this way. The new
versions of those files will be written into the specified
directory. As long as you have read access to
/usr/src
, you do not even need to be
root
to perform this kind of trial
run.
If you are not running X11 or if you just do not like
GUIs, you should add a couple of options to the command line
when you run cvsup
:
#
cvsup -g -L 2 supfile
The -g
tells
CVSup not to use its GUI. This is
automatic if you are not running X11, but otherwise you have
to specify it.
The -L 2
tells
CVSup to print out the
details of all the file updates it is doing. There are three
levels of verbosity, from -L 0
to
-L 2
. The default is 0, which means total
silence except for error messages.
There are plenty of other options available. For a brief
list of them, type cvsup -H
. For more
detailed descriptions, see the manual page.
Once you are satisfied with the way updates are working, you can arrange for regular runs of CVSup using cron(8). Obviously, you should not let CVSup use its GUI when running it from cron(8).
The file collections available via CVSup are organized hierarchically. There are a few large collections, and they are divided into smaller sub-collections. Receiving a large collection is equivalent to receiving each of its sub-collections. The hierarchical relationships among collections are reflected by the use of indentation in the list below.
The most commonly used collection is
src-all
.
cvs-all release=cvs
The main FreeBSD CVS repository, including the cryptography code.
distrib release=cvs
Files related to the distribution and mirroring of FreeBSD.
projects-all release=cvs
Sources for the FreeBSD projects repository.
src-all release=cvs
The main FreeBSD sources, including the cryptography code.
src-base
release=cvs
Miscellaneous files at the top of
/usr/src
.
src-bin
release=cvs
User utilities that may be needed in
single-user mode
(/usr/src/bin
).
src-cddl
release=cvs
Utilities and libraries covered by the
CDDL license
(/usr/src/cddl
).
src-contrib
release=cvs
Utilities and libraries from outside the
FreeBSD project, used relatively unmodified
(/usr/src/contrib
).
src-crypto release=cvs
Cryptography utilities and libraries
from outside the FreeBSD project, used
relatively unmodified
(/usr/src/crypto
).
src-eBones release=cvs
Kerberos and DES
(/usr/src/eBones
). Not
used in current releases of FreeBSD.
src-etc
release=cvs
System configuration files
(/usr/src/etc
).
src-games
release=cvs
Games
(/usr/src/games
).
src-gnu
release=cvs
Utilities covered by the GNU Public
License
(/usr/src/gnu
).
src-include
release=cvs
Header files
(/usr/src/include
).
src-kerberos5
release=cvs
Kerberos5 security package
(/usr/src/kerberos5
).
src-kerberosIV
release=cvs
KerberosIV security package
(/usr/src/kerberosIV
).
src-lib
release=cvs
Libraries
(/usr/src/lib
).
src-libexec
release=cvs
System programs normally executed by
other programs
(/usr/src/libexec
).
src-release
release=cvs
Files required to produce a FreeBSD
release
(/usr/src/release
).
src-rescue
release=cvs
Statically linked programs for emergency
recovery; see rescue(8)
(/usr/src/rescue
).
src-sbin release=cvs
System utilities for single-user mode
(/usr/src/sbin
).
src-secure
release=cvs
Cryptographic libraries and commands
(/usr/src/secure
).
src-share
release=cvs
Files that can be shared across multiple
systems
(/usr/src/share
).
src-sys
release=cvs
The kernel
(/usr/src/sys
).
src-sys-crypto
release=cvs
Kernel cryptography code
(/usr/src/sys/crypto
).
src-tools
release=cvs
Various tools for the maintenance of
FreeBSD
(/usr/src/tools
).
src-usrbin
release=cvs
User utilities
(/usr/src/usr.bin
).
src-usrsbin
release=cvs
System utilities
(/usr/src/usr.sbin
).
distrib release=self
The CVSup server's own configuration files. Used by CVSup mirror sites.
gnats release=current
The GNATS bug-tracking database.
mail-archive release=current
FreeBSD mailing list archive.
For the CVSup FAQ and other information about CVSup, see The CVSup Home Page.
Most FreeBSD-related discussion of CVSup takes place on the FreeBSD technical discussions mailing list. New versions of the software are announced there, as well as on the FreeBSD announcements mailing list.
For questions or bug reports about CVSup take a look at the CVSup FAQ.
CVSup servers for FreeBSD are running at the following sites:
Central Servers, Primary Mirror Sites, Armenia, Australia, Brazil, Czech Republic, Denmark, Estonia, Finland, France, Germany, Ireland, Italy, Japan, Korea, Latvia, Lithuania, Netherlands, Norway, Poland, Russia, Slovak Republic, Slovenia, South Africa, Spain, Sweden, Switzerland, Taiwan, Ukraine, USA.
(as of UTC)
cvsup.FreeBSD.org
cvsup1.FreeBSD.org
cvsup3.FreeBSD.org
cvsup4.FreeBSD.org
cvsup5.FreeBSD.org
cvsup6.FreeBSD.org
cvsup7.FreeBSD.org
cvsup9.FreeBSD.org
cvsup10.FreeBSD.org
cvsup11.FreeBSD.org
cvsup12.FreeBSD.org
cvsup14.FreeBSD.org
cvsup15.FreeBSD.org
cvsup18.FreeBSD.org
cvsup1.am.FreeBSD.org
cvsup.au.FreeBSD.org
cvsup2.br.FreeBSD.org
cvsup.cz.FreeBSD.org
cvsup.dk.FreeBSD.org
cvsup.ee.FreeBSD.org
cvsup.fi.FreeBSD.org
cvsup3.fr.FreeBSD.org
cvsup5.fr.FreeBSD.org
cvsup8.fr.FreeBSD.org
cvsup.de.FreeBSD.org
cvsup2.de.FreeBSD.org
cvsup4.de.FreeBSD.org
cvsup5.de.FreeBSD.org
cvsup.ie.FreeBSD.org
cvsup2.ie.FreeBSD.org
cvsup.it.FreeBSD.org
cvsup.jp.FreeBSD.org
cvsup2.jp.FreeBSD.org
cvsup3.jp.FreeBSD.org
cvsup4.jp.FreeBSD.org
cvsup5.jp.FreeBSD.org
cvsup6.jp.FreeBSD.org
cvsup.kr.FreeBSD.org
cvsup.lv.FreeBSD.org
cvsup.lt.FreeBSD.org
cvsup.nl.FreeBSD.org
cvsup2.nl.FreeBSD.org
cvsup3.nl.FreeBSD.org
cvsup.no.FreeBSD.org
cvsup.pl.FreeBSD.org
cvsup3.ru.FreeBSD.org
cvsup5.ru.FreeBSD.org
cvsup6.ru.FreeBSD.org
cvsup.sk.FreeBSD.org
cvsup.si.FreeBSD.org
cvsup.za.FreeBSD.org
cvsup.es.FreeBSD.org
cvsup2.es.FreeBSD.org
cvsup3.es.FreeBSD.org
cvsup.se.FreeBSD.org
cvsup2.se.FreeBSD.org
cvsup.ch.FreeBSD.org
cvsup.tw.FreeBSD.org
cvsup3.tw.FreeBSD.org
cvsup6.tw.FreeBSD.org
cvsup10.tw.FreeBSD.org
cvsup11.tw.FreeBSD.org
cvsup12.tw.FreeBSD.org
cvsup13.tw.FreeBSD.org
cvsup5.ua.FreeBSD.org
cvsup6.ua.FreeBSD.org
cvsup1.us.FreeBSD.org
cvsup3.us.FreeBSD.org
cvsup4.us.FreeBSD.org
cvsup5.us.FreeBSD.org
cvsup7.us.FreeBSD.org
cvsup9.us.FreeBSD.org
cvsup11.us.FreeBSD.org
cvsup12.us.FreeBSD.org
cvsup13.us.FreeBSD.org
cvsup14.us.FreeBSD.org
cvsup15.us.FreeBSD.org
cvsup18.us.FreeBSD.org
All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.