A.3 Using CVSup

A.3.1 Introduction

CVSup is a software package for distributing and updating source trees from a master CVS repository on a remote server host. The DragonFly sources are maintained in a CVS repository on a central development machine in California. With CVSup, DragonFly 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 DragonFly mirror sites that use CVSup.

A.3.2 Installation

CVSup is installed by default on all DragonFly systems.

A.3.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:

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

A.3.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. However, this is not always what you want, especially if you are synching the doc, ports, or www trees -- most people cannot read four or five languages, and therefore they do not need to download the language-specific files. If you are CVSuping the ports collection, you can get around this by specifying each collection individually (e.g., ports-astrology, ports-biology, etc instead of simply saying ports-all). However, since the doc and www trees do not have language-specific collections, you must use one of CVSup's many nifty features: the refuse file.

The refuse file essentially 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; by default, base is /usr/local/etc/cvsup, which means that by default the refuse file is /usr/local/etc/cvsup/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, if you cannot speak any languages other than English and some German, and you do not feel the need to use the German applications (or applications for any other languages, except for English), you can put the following in your refuse file:


and so forth for the other languages (you can find the full list by browsing the FreeBSD CVS repository).

With this very useful feature, those users who are on slow links or pay by the minute for their Internet connection will be able to save valuable 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.3.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.3.5 CVSup File Collections

The most commonly used collections are cvs-src, and cvs-dfports.


The DragonFly source code.


Documentation. This does not include the DragonFly website.


Overrides for the FreeBSD Ports Collection.


The DragonFly website code.


Basic CVS data. This is only needed if you are pulling the RCS data.

A.3.6 For More Information

For the CVSup FAQ and other information about CVSup, see The CVSup Home Page.

Questions and bug reports should be addressed to the author of the program at .

A.3.7 CVSup Sites

CVSup servers for DragonFly are running at the following sites:

Primary Mirror Sites, Australia, USA.

(as of 2005/06/27 23:37:47 UTC)

Primary Mirror Sites

  • chlamydia.fs.ei.tum.de

  • cvsup.allbsd.org

  • grappa.unix-ag.uni-kl.de

  • mirror.isp.net.au

  • alxl.info

  • dragonflybsd.delphij.net

  • fred.acm.cs.rpi.edu


  • mirror.isp.net.au


  • fred.acm.cs.rpi.edu

Contact the Documentation mailing list for comments, suggestions and questions about this document.