Section 6.8. Distributed Repositories

6.8. Distributed Repositories

Many CVS systems use only a single, central repository, but not all. Many open source projects that rely on CVS use mirrored repositories to distribute the latest source, and many of those have a version of the repository available on the World Wide Web. Recently, write-proxying has been enabled for mirror repositories: this process allows the user to connect to the mirror as if the mirror were the central repository.

6.8.1. Mirroring a Repository

Many project teams have public, read-only CVS repositories. If you want to do likewise, you can copy the repository, reserve the original repository for your project work, and use the copy (or mirror) repository as a public repository.

The copy can be on the same computer as the original or on a different computer or even a different network. Having two or more copies of a repository allows you to put one copy on a trusted network for your developers and another on a more public part of your network for the general public.

You can't commit to a repository mirror, but CVS permits you to make a mirror repository into a write-proxy for a primary repository. See the following section on write proxies.

Mirror a repository by copying the repository files. To avoid getting part of one release and part of another due to the copy overlapping with a commit, freeze the repository with read locks before mirroring and unfreeze it afterward.

The Unix and Linux rsync program is a useful tool to use when mirroring. It allows you to recursively transfer only the changed files between any two directories and recovers properly if it's interrupted. It also has an optional CVS-exclusion mode, called with the --cvs-exclude option, which ignores the same files CVS ignores by default. By default, rsync uses SSH, but if your system is configured differently, you can use the -e ssh option to rsync to transfer using the SSH protocol. An rsync command or script can be triggered at either the central repository or the mirror.

There is also a repository mirroring tool called CVSup. It's designed specifically for use with CVS, and parses the CVS data files to do the mirroring as efficiently as possible. It is triggered by the mirror, and is most often updated on a daily basis, triggered by an automation application such as cron.

To keep a secondary repository up to date with all changes from the primary repository, trigger an rsync script in all four of the loginfo, postadmin, posttag, and postwatch scripting files. You can't as easily keep a CVSup'd mirror constantly up to date, because the CVSup system is designed to be triggered from the mirror rather than from the central repository.

Example 6-10 shows a typical rsync line for the scripting files. Add this line to all four of the loginfo, postadmin, posttag, and postwatch files to generate an rsync attempt with the mirror repository in the directory /usr/local/cvs on the machine mirror1. Configure rsync and SSH so that they don't need a passwordsee your SSH documentation for details. Note that rsync has many useful options other than the ones I've included, which are to preserve permissions, group, and owner, and to use compression.

Example 6-10. Mirroring with rsync

 ALL rsync -pgoz -e ssh ./ mirror1:/usr/local/cvs/%p & 

Because we're trying to mirror the repository, I've chosen not to use cvs-exclude and thus kept the CVS administrative files. The %p is an internal CVS variable (valid in recent versions only) and is explained in the section "Running Scripts" in Chapter 7.

6.8.2. Write Proxies

In CVS version 1.12.10, the developers added the ability for CVS mirrors to act as write proxies for the central repository. The mirror (or secondary repository, in the proxy system) handles all read requests itself, but passes write requests to the central (primary) repository.

The write proxy system does not modify the secondary repository, nor does it do anything to keep the secondary repository up to date. Use the techniques explained in "Mirroring a Repository," earlier in this chapter, to update your secondary repositories.

To configure a write proxy system, edit the CVSROOT/config files in your secondary repositories. The PrimaryServer configuration option must specify the repository path of the primary repository: be aware that at present, you must use the :ext: or :fork: connection methods. There is no mandatory configuration on the primary repository for write proxying itself, but almost all administrators will choose to configure a mirroring system of some sort.

CVS clients older than CVS 1.12.9 do not recognize write proxying. In the new clients, the secondary server requests that the client redirect the write request to the primary server. To support older clients, the secondary server will act as a transparent proxy to the primary server. Unfortunately, this requires additional configuration.

The good news is that if all your clients are newer than 1.12.9, the extra configuration is unnecessary.

To support pre-CVS 1.12.9 clients, your primary and secondary servers must be compatible. Ideally, use the same version of CVS for both; otherwise, you will need to ensure that the same write requests are used both by primary and secondary server.

Also (still supporting older clients), you should ensure that all secondary servers are invoked with the parameter allow-root=secondary repository root. You will probably need to do this by installing an alias or a script on your server's machine.

6.8.3. Web-Viewable Repositories

An alternative way to distribute a repositoryfor read-only accessis across the Web. The current favorite tool for doing this is ViewVC (formerly ViewCVS), which generates HTML navigation for CVS and Subversion repositories, and is available at http://www.viewvc.org. A similar tool is CVSWeb, which has gone through several incarnations and is currently being maintained as FreeBSD-CVSWeb.

Web distribution is very popular in open source projects, or in other projects where a variety of people using a variety of platforms will want read-only access to the documents stored in CVS.

The INSTALL document included in the ViewVC source distribution is very clear and easy to read, and the installation is automated. Configuration is done by editing the file viewvc.conf, which itself contains clear and concise examples.