A.7. Using CVSup (Deprecated)
Prev | Appendix A. Obtaining FreeBSD | Next

## A.7. Using CVSup (Deprecated)

### A.7.1. Introduction

### Warning:

`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.

### Note:

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.

### A.7.2. Installation

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.

### Note:

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`.

### A.7.3. CVSup Configuration

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:

- Which files do you want to receive?

- Which versions of them do you want?

- Where do you want to get them from?

- Where do you want to put them on your own machine?

- Where do you want to put your status files?

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):

  src-all

- 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.

  ### Warning:

  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.

  ### Warning:

  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`:

  *default tag=.

  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`:

  *default host=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:

  *default prefix=/usr

- 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`:

  *default base=/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`:

  *default release=cvs delete use-rel-suffix compress

  `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:

  *default tag=. *default host=cvsup99.FreeBSD.org *default prefix=/usr *default base=/var/db *default release=cvs delete use-rel-suffix compress src-all

#### A.7.3.1. The `refuse` File

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:

bin/ usr.bin/

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.

### A.7.4. Running CVSup

You are now ready to try an update. The command line for doing this is quite simple:

`#` `cvsup `supfile``

where ``supfile`` is of course the name of the `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 go 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).

### A.7.5. CVSup File Collections

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.

### A.7.6. For More Information

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.

### A.7.7. CVSup Sites

CVSup servers for FreeBSD are running at the following sites:

Central Servers, Primary Mirror Sites, Armenia, Australia, Austria, Brazil, Canada, China, Costa Rica, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Iceland, Ireland, Israel, Italy, Japan, Korea, Kuwait, Kyrgyzstan, Latvia, Lithuania, Netherlands, New Zealand, Norway, Philippines, Poland, Portugal, Romania, Russia, San Marino, Slovak Republic, Slovenia, South Africa, Spain, Sweden, Switzerland, Taiwan, Thailand, Turkey, Ukraine, United Kingdom, USA.

(as of UTC)

Central Servers

  - cvsup.FreeBSD.org

Primary Mirror Sites

  - cvsup1.FreeBSD.org

  - cvsup2.FreeBSD.org

  - cvsup3.FreeBSD.org

  - cvsup4.FreeBSD.org

  - cvsup5.FreeBSD.org

  - cvsup6.FreeBSD.org

  - cvsup7.FreeBSD.org

  - cvsup8.FreeBSD.org

  - cvsup9.FreeBSD.org

  - cvsup10.FreeBSD.org

  - cvsup11.FreeBSD.org

  - cvsup12.FreeBSD.org

  - cvsup13.FreeBSD.org

  - cvsup14.FreeBSD.org

  - cvsup15.FreeBSD.org

  - cvsup16.FreeBSD.org

  - cvsup18.FreeBSD.org

Armenia

  - cvsup1.am.FreeBSD.org

Australia

  - cvsup.au.FreeBSD.org

Austria

  - cvsup.at.FreeBSD.org

Brazil

  - cvsup.br.FreeBSD.org

  - cvsup2.br.FreeBSD.org

  - cvsup3.br.FreeBSD.org

  - cvsup4.br.FreeBSD.org

  - cvsup5.br.FreeBSD.org

Canada

  - cvsup1.ca.FreeBSD.org

China

  - cvsup.cn.FreeBSD.org

  - cvsup2.cn.FreeBSD.org

Costa Rica

  - cvsup1.cr.FreeBSD.org

Czech Republic

  - cvsup.cz.FreeBSD.org

Denmark

  - cvsup.dk.FreeBSD.org

  - cvsup2.dk.FreeBSD.org

Estonia

  - cvsup.ee.FreeBSD.org

Finland

  - cvsup.fi.FreeBSD.org

  - cvsup2.fi.FreeBSD.org

France

  - cvsup.fr.FreeBSD.org

  - cvsup1.fr.FreeBSD.org

  - cvsup2.fr.FreeBSD.org

  - cvsup3.fr.FreeBSD.org

  - cvsup4.fr.FreeBSD.org

  - cvsup5.fr.FreeBSD.org

  - cvsup8.fr.FreeBSD.org

Germany

  - cvsup.de.FreeBSD.org

  - cvsup2.de.FreeBSD.org

  - cvsup3.de.FreeBSD.org

  - cvsup4.de.FreeBSD.org

  - cvsup5.de.FreeBSD.org

  - cvsup6.de.FreeBSD.org

  - cvsup7.de.FreeBSD.org

  - cvsup8.de.FreeBSD.org

Greece

  - cvsup.gr.FreeBSD.org

  - cvsup2.gr.FreeBSD.org

Iceland

  - cvsup.is.FreeBSD.org

Ireland

  - cvsup.ie.FreeBSD.org

  - cvsup2.ie.FreeBSD.org

Israel

  - cvsup.il.FreeBSD.org

Italy

  - cvsup.it.FreeBSD.org

Japan

  - cvsup.jp.FreeBSD.org

  - cvsup2.jp.FreeBSD.org

  - cvsup3.jp.FreeBSD.org

  - cvsup4.jp.FreeBSD.org

  - cvsup5.jp.FreeBSD.org

  - cvsup6.jp.FreeBSD.org

Korea

  - cvsup.kr.FreeBSD.org

  - cvsup2.kr.FreeBSD.org

  - cvsup3.kr.FreeBSD.org

Kuwait

  - cvsup1.kw.FreeBSD.org

Kyrgyzstan

  - cvsup.kg.FreeBSD.org

Latvia

  - cvsup.lv.FreeBSD.org

  - cvsup2.lv.FreeBSD.org

Lithuania

  - cvsup.lt.FreeBSD.org

  - cvsup2.lt.FreeBSD.org

  - cvsup3.lt.FreeBSD.org

Netherlands

  - cvsup.nl.FreeBSD.org

  - cvsup2.nl.FreeBSD.org

  - cvsup3.nl.FreeBSD.org

New Zealand

  - cvsup.nz.FreeBSD.org

Norway

  - cvsup.no.FreeBSD.org

Philippines

  - cvsup1.ph.FreeBSD.org

Poland

  - cvsup.pl.FreeBSD.org

  - cvsup2.pl.FreeBSD.org

  - cvsup3.pl.FreeBSD.org

Portugal

  - cvsup.pt.FreeBSD.org

  - cvsup2.pt.FreeBSD.org

  - cvsup3.pt.FreeBSD.org

Romania

  - cvsup.ro.FreeBSD.org

  - cvsup1.ro.FreeBSD.org

  - cvsup2.ro.FreeBSD.org

  - cvsup3.ro.FreeBSD.org

Russia

  - cvsup.ru.FreeBSD.org

  - cvsup2.ru.FreeBSD.org

  - cvsup3.ru.FreeBSD.org

  - cvsup4.ru.FreeBSD.org

  - cvsup5.ru.FreeBSD.org

  - cvsup6.ru.FreeBSD.org

  - cvsup7.ru.FreeBSD.org

San Marino

  - cvsup.sm.FreeBSD.org

Slovak Republic

  - cvsup.sk.FreeBSD.org

Slovenia

  - cvsup.si.FreeBSD.org

  - cvsup2.si.FreeBSD.org

South Africa

  - cvsup.za.FreeBSD.org

  - cvsup2.za.FreeBSD.org

Spain

  - cvsup.es.FreeBSD.org

  - cvsup2.es.FreeBSD.org

  - cvsup3.es.FreeBSD.org

Sweden

  - cvsup.se.FreeBSD.org

  - cvsup2.se.FreeBSD.org

Switzerland

  - cvsup.ch.FreeBSD.org

Taiwan

  - cvsup.tw.FreeBSD.org

  - cvsup3.tw.FreeBSD.org

  - cvsup4.tw.FreeBSD.org

  - cvsup5.tw.FreeBSD.org

  - cvsup6.tw.FreeBSD.org

  - cvsup7.tw.FreeBSD.org

  - cvsup8.tw.FreeBSD.org

  - cvsup9.tw.FreeBSD.org

  - cvsup10.tw.FreeBSD.org

  - cvsup11.tw.FreeBSD.org

  - cvsup12.tw.FreeBSD.org

  - cvsup13.tw.FreeBSD.org

  - cvsup14.tw.FreeBSD.org

Thailand

  - cvsup.th.FreeBSD.org

Turkey

  - cvsup.tr.FreeBSD.org

  - cvsup2.tr.FreeBSD.org

Ukraine

  - cvsup3.ua.FreeBSD.org

  - cvsup5.ua.FreeBSD.org

  - cvsup6.ua.FreeBSD.org

United Kingdom

  - cvsup.uk.FreeBSD.org

  - cvsup2.uk.FreeBSD.org

  - cvsup3.uk.FreeBSD.org

  - cvsup4.uk.FreeBSD.org

USA

  - cvsup1.us.FreeBSD.org

  - cvsup2.us.FreeBSD.org

  - cvsup3.us.FreeBSD.org

  - cvsup4.us.FreeBSD.org

  - cvsup5.us.FreeBSD.org

  - cvsup6.us.FreeBSD.org

  - cvsup7.us.FreeBSD.org

  - cvsup8.us.FreeBSD.org

  - cvsup9.us.FreeBSD.org

  - cvsup10.us.FreeBSD.org

  - cvsup11.us.FreeBSD.org

  - cvsup12.us.FreeBSD.org

  - cvsup13.us.FreeBSD.org

  - cvsup14.us.FreeBSD.org

  - cvsup15.us.FreeBSD.org

  - cvsup16.us.FreeBSD.org

  - cvsup18.us.FreeBSD.org

Prev | Up | Next
A.6. Subversion Mirror Sites | Home | A.8. CVS Tags

This, and other documents, can be downloaded from http://ftp.FreeBSD.org/pub/FreeBSD/doc/

For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.