Go to the first, previous, next, last section, table of contents.


3 The Repository

The CVS repository stores a complete copy of all the files and directories which are under version control.

Normally, you never access any of the files in the repository directly. Instead, you use CVS commands to get your own copy of the files into a working directory, and then work on that copy. When you've finished a set of changes, you check (or commit) them back into the repository. The repository then contains the changes which you have made, as well as recording exactly what you changed, when you changed it, and other such information. Note that the repository is not a subdirectory of the working directory, or vice versa; they should be in separate locations.

CVS can access a repository by a variety of means. It might be on the local computer, or it might be on a computer across the room or across the world. To distinguish various ways to access a repository, the repository name can start with an access method. For example, the access method :local: means to access a repository directory, so the repository :local:/usr/local/cvsroot means that the repository is in `/usr/local/cvsroot' on the computer running CVS. For information on other access methods, see section 3.9 Remote repositories.

If the access method is omitted, then if the repository does not contain `:', then :local: is assumed. If it does contain `:' than either :ext: or :server: is assumed. For example, if you have a local repository in `/usr/local/cvsroot', you can use /usr/local/cvsroot instead of :local:/usr/local/cvsroot. But if (under Windows NT, for example) your local repository is `c:\src\cvsroot', then you must specify the access method, as in :local:c:\src\cvsroot.

The repository is split in two parts. `$CVSROOT/CVSROOT' contains administrative files for CVS. The other directories contain the actual user-defined modules.

3.1 Telling CVS where your repository is

There are a couple of different ways to tell CVS where to find the repository. You can name the repository on the command line explicitly, with the -d (for "directory") option:

cvs -d /usr/local/cvsroot checkout yoyodyne/tc

Or you can set the $CVSROOT environment variable to an absolute path to the root of the repository, `/usr/local/cvsroot' in this example. To set $CVSROOT, all csh and tcsh users should have this line in their `.cshrc' or `.tcshrc' files:

setenv CVSROOT /usr/local/cvsroot

sh and bash users should instead have these lines in their `.profile' or `.bashrc':

CVSROOT=/usr/local/cvsroot
export CVSROOT

A repository specified with -d will override the $CVSROOT environment variable. Once you've checked a working copy out from the repository, it will remember where its repository is (the information is recorded in the `CVS/Root' file in the working copy).

The -d option and the `CVS/Root' file both override the $CVSROOT environment variable. If -d option differs from `CVS/Root', the former is used (and specifying -d will cause `CVS/Root' to be updated). Of course, for proper operation they should be two ways of referring to the same repository.

3.2 How data is stored in the repository

For most purposes it isn't important how CVS stores information in the repository. In fact, the format has changed in the past, and is likely to change in the future. Since in almost all cases one accesses the repository via CVS commands; such changes need not be disruptive.

However, in some cases it may be necessary to understand how CVS stores data in the repository, for example you might need to track down CVS locks (see section 5.5 Several developers simultaneously attempting to run CVS) or you might need to deal with the file permissions appropriate for the repository.

3.2.1 Where files are stored within the repository

The overall structure of the repository is a directory tree corresponding to the directories in the working directory. For example, supposing the repository is in

/usr/local/cvsroot

here is a possible directory tree (showing only the directories):

/usr
 |
 +--local
 |   |
 |   +--cvsroot
 |   |    | 
 |   |    +--CVSROOT
          |      (administrative files) 
          | 
          +--gnu
          |   | 
          |   +--diff
          |   |   (source code to GNU diff) 
          |   | 
          |   +--rcs
          |   |   (source code to RCS)
          |   | 
          |   +--cvs
          |       (source code to CVS) 
          | 
          +--yoyodyne
              | 
              +--tc
              |    |
              |    +--man
              |    |
              |    +--testing
              | 
              +--(other Yoyodyne software)

With the directories are history files for each file under version control. The name of the history file is the name of the corresponding file with `,v' appended to the end. Here is what the repository for the `yoyodyne/tc' directory might look like:

  $CVSROOT
    |
    +--yoyodyne
    |   |
    |   +--tc
    |   |   |
            +--Makefile,v
            +--backend.c,v
            +--driver.c,v
            +--frontend.c,v
            +--parser.c,v
            +--man
            |    |
            |    +--tc.1,v
            |     
            +--testing
                 |
                 +--testpgm.t,v
                 +--test2.t,v

The history files contain, among other things, enough information to recreate any revision of the file, a log of all commit messages and the user-name of the person who committed the revision. The history files are known as RCS files, because the first program to store files in that format was a version control system known as RCS. For a full description of the file format, see the man page rcsfile(5), distributed with RCS. This file format has become very common--many systems other than CVS or RCS can at least import history files in this format.

The RCS files used in CVS differ in a few ways from the standard format. The biggest difference is magic branches; for more information see section 6.8 Magic branch numbers. Also in CVS the valid tag names are a subset of what RCS accepts; for CVS's rules see section 6.4 Tags--Symbolic revisions.

3.2.2 File permissions

All `,v' files are created read-only, and you should not change the permission of those files. The directories inside the repository should be writable by the persons that have permission to modify the files in each directory. This normally means that you must create a UNIX group (see group(5)) consisting of the persons that are to edit the files in a project, and set up the repository so that it is that group that owns the directory.

This means that you can only control access to files on a per-directory basis.

Note that users must also have write access to check out files, because CVS needs to create lock files (see section 5.5 Several developers simultaneously attempting to run CVS).

Also note that users must have write access to the `CVSROOT/val-tags' file. CVS uses it to keep track of what tags are valid tag names (it is sometimes updated when tags are used, as well as when they are created, though).

CVS tries to set up reasonable file permissions for new directories that are added inside the tree, but you must fix the permissions manually when a new directory should have different permissions than its parent directory. If you set the CVSUMASK environment variable that will control the file permissions which CVS uses in creating directories and/or files in the repository. CVSUMASK does not affect the file permissions in the working directory; such files have the permissions which are typical for newly created files, except that sometimes CVS creates them read-only (see the sections on watches, section 5.6.1 Telling CVS to watch certain files; -r, section A.4 Global options; or CVSREAD, section D All environment variables which affect CVS).

Note that using the client/server CVS (see section 3.9 Remote repositories), there is no good way to set CVSUMASK; the setting on the client machine has no effect. If you are connecting with rsh, you can set CVSUMASK in `.bashrc' or `.cshrc', as described in the documentation for your operating system. This behavior might change in future versions of CVS; do not rely on the setting of CVSUMASK on the client having no effect.

Since CVS was not written to be run setuid, it is unsafe to try to run it setuid. You cannot use the setuid features of RCS together with CVS.

3.2.3 The attic

You will notice that sometimes CVS stores an RCS file in the Attic. For example, if the CVSROOT is `/usr/local/cvsroot' and we are talking about the file `backend.c' in the directory `yoyodyne/tc', then the file normally would be in

/usr/local/cvsroot/yoyodyne/tc/backend.c,v

but if it goes in the attic, it would be in

/usr/local/cvsroot/yoyodyne/tc/Attic/backend.c,v

instead. It should not matter from a user point of view whether a file is in the attic; CVS keeps track of this and looks in the attic when it needs to. But in case you want to know, the rule is that the RCS file is stored in the attic if and only if the head revision on the trunk has state dead. A dead state means that file has been removed, or never added, for that revision. For example, if you add a file on a branch, it will have a trunk revision in dead state, and a branch revision in a non-dead state.

3.3 How data is stored in the working directory

While we are discussing CVS internals which may become visible from time to time, we might as well talk about what CVS puts in the `CVS' directories in the working directories. As with the repository, CVS handles this information and one can usually access it via CVS commands. But in some cases it may be useful to look at it, and other programs, such as the jCVS graphical user interface or the VC package for emacs, may need to look at it. Such programs should follow the recommendations in this section if they hope to be able to work with other programs which use those files, including future versions of the programs just mentioned and the command-line CVS client.

The `CVS' directory contains several files. Programs which are reading this directory should silently ignore files which are in the directory but which are not documented here, to allow for future expansion.

`Root'
This file contains the current CVS root, as described in section 3.1 Telling CVS where your repository is.
`Repository'
This file contains the directory within the repository which the current directory corresponds with. For historical reasons it is an absolute pathname, although it would make more sense for it to be relative to the root. For example, after the command
cvs -d :local:/usr/local/cvsroot checkout yoyodyne/tc
`Root' will contain
:local:/usr/local/cvsroot
and `Repository' will contain
/usr/local/cvsroot/yoydyne/tc
`Entries'
This file lists the files and directories in the working directory. It is a text file according to the conventions appropriate for the operating system in question. The first character of each line indicates what sort of line it is. If the character is unrecognized, programs reading the file should silently skip that line, to allow for future expansion. If the first character is `/', then the format is:
/name/revision/timestamp[+conflict]/options/tagdate
where `[' and `]' are not part of the entry, but instead indicate that the `+' and conflict marker are optional. name is the name of the file within the directory. revision is the revision that the file in the working derives from, or `0' for an added file, or `-' followed by a revision for a removed file. timestamp is the timestamp of the file at the time that CVS created it; if the timestamp differs with the actual modification time of the file it means the file has been modified. It is in Universal Time (UT), stored in the format used by the ISO C asctime() function (for example, `Sun Apr 7 01:29:26 1996'). One may write a string which is not in that format, for example, `Result of merge', to indicate that the file should always be considered to be modified. This is not a special case; to see whether a file is modified a program should take the timestamp of the file and simply do a string compare with timestamp. conflict indicates that there was a conflict; if it is the same as the actual modification time of the file it means that the user has obviously not resolved the conflict. options contains sticky options (for example `-kb' for a binary file). tagdate contains `T' followed by a tag name, or `D' for a date, followed by a sticky tag or date. Note that if timestamp contains a pair of timestamps separated by a space, rather than a single timestamp, you are dealing with a version of CVS earlier than CVS 1.5 (not documented here). If the first character of a line in `Entries' is `D', then it indicates a subdirectory. `D' on a line all by itself indicates that the program which wrote the `Entries' file does record subdirectories (therefore, if there is such a line and no other lines beginning with `D', one knows there are no subdirectories). Otherwise, the line looks like:
D/name/filler1/filler2/filler3/filler4
where name is the name of the subdirectory, and all the filler fields should be silently ignored, for future expansion. Programs which modify Entries files should preserve these fields.
`Entries.Log'
This file does not record any information beyond that in `Entries', but it does provide a way to update the information without having to rewrite the entire `Entries' file, including the ability to preserve the information even if the program writing `Entries' and `Entries.Log' abruptly aborts. Programs which are reading the `Entries' file should also check for `Entries.Log'. If the latter exists, they should read `Entries' and then apply the changes mentioned in `Entries.Log'. After applying the changes, the recommended practice is to rewrite `Entries' and then delete `Entries.Log'. The format of a line in `Entries.Log' is a single character command followed by a space followed by a line in the format specified for a line in `Entries'. The single character command is `A' to indicate that the entry is being added, `R' to indicate that the entry is being removed, or any other character to indicate that the entire line in `Entries.Log' should be silently ignored (for future expansion). If the second character of the line in `Entries.Log' is not a space, then it was written by an older version of CVS (not documented here).
`Entries.Backup'
This is a temporary file. Recommended usage is to write a new entries file to `Entries.Backup', and then to rename it (atomically, where possible) to `Entries'.
`Entries.Static'
The only relevant thing about this file is whether it exists or not. If it exists, then it means that only part of a directory was gotten and CVS will not create additional files in that directory. To clear it, use the update command with the `-d' option, which will get the additional files and remove `Entries.Static'.
`Tag'
This file contains per-directory sticky tags or dates. The first character is `T' for a branch tag, `N' for a non-branch tag, or `D' for a date, or another character to mean the file should be silently ignored, for future expansion. This character is followed by the tag or date. Note that per-directory sticky tags or dates are used for things like applying to files which are newly added; they might not be the same as the sticky tags or dates on individual files. For general information on sticky tags and dates, see section 6.7 Sticky tags.
`Checkin.prog'
`Update.prog'
These files store the programs specified by the `-i' and `-u' options in the modules file, respectively.
`Notify'
This file stores notifications (for example, for edit or unedit) which have not yet been sent to the server. Its format is not yet documented here.
`Notify.tmp'
This file is to `Notify' as `Entries.Backup' is to `Entries'. That is, to write `Notify', first write the new contents to `Notify.tmp' and then (atomically where possible), rename it to `Notify'.
`Base'
If watches are in use, then an edit command stores the original copy of the file in the `Base' directory. This allows the unedit command to operate even if it is unable to communicate with the server.
`Template'
This file contains the template specified by the `rcsinfo' file (see section C.8 Rcsinfo). It is only used by the client; the non-client/server CVS consults `rcsinfo' directly.

3.4 The administrative files

The directory `$CVSROOT/CVSROOT' contains some administrative files. See section C Reference manual for Administrative files, for a complete description. You can use CVS without any of these files, but some commands work better when at least the `modules' file is properly set up.

The most important of these files is the `modules' file. It defines all modules in the repository. This is a sample `modules' file.

CVSROOT         CVSROOT
modules         CVSROOT modules
cvs             gnu/cvs
rcs             gnu/rcs
diff            gnu/diff
tc              yoyodyne/tc

The `modules' file is line oriented. In its simplest form each line contains the name of the module, whitespace, and the directory where the module resides. The directory is a path relative to $CVSROOT. The last four lines in the example above are examples of such lines.

The line that defines the module called `modules' uses features that are not explained here. See section C.1 The modules file, for a full explanation of all the available features.

3.4.1 Editing administrative files

You edit the administrative files in the same way that you would edit any other module. Use `cvs checkout CVSROOT' to get a working copy, edit it, and commit your changes in the normal way.

It is possible to commit an erroneous administrative file. You can often fix the error and check in a new revision, but sometimes a particularly bad error in the administrative file makes it impossible to commit new revisions.

3.5 Multiple repositories

In some situations it is a good idea to have more than one repository, for instance if you have two development groups that work on separate projects without sharing any code. All you have to do to have several repositories is to specify the appropriate repository, using the CVSROOT environment variable, the `-d' option to CVS, or (once you have checked out a working directory) by simply allowing CVS to use the repository that was used to check out the working directory (see section 3.1 Telling CVS where your repository is).

The big advantage of having multiple repositories is that they can reside on different servers. The big disadvantage is that you cannot have a single CVS command recurse into directories which comes from different repositories. Generally speaking, if you are thinking of setting up several repositories on the same machine, you might want to consider using several directories within the same repository.

None of the examples in this manual show multiple repositories.

3.6 Creating a repository

To set up a CVS repository, first choose the machine and disk on which you want to store the revision history of the source files. CPU and memory requirements are modest--a server with 32M of memory or even less can handle a fairly large source tree with a fair amount of activity. To estimate disk space requirements, if you are importing RCS files from another system, the size of those files is the approximate initial size of your repository, or if you are starting without any version history, a rule of thumb is to allow for the server approximately three times the size of the code to be under CVS for the repository (you will eventually outgrow this, but not for a while). On the machines on which the developers will be working, you'll want disk space for approximately one working directory for each developer (either the entire tree or a portion of it, depending on what each developer uses). Don't worry about CPU and memory requirements for the clients--any machine with enough capacity to run the operating system in question should have little trouble.

The repository should be accessable (directly or via a networked file system) from all machines which want to use CVS in server or local mode; the client machines need not have any access to it other than via the CVS protocol. It is not possible to use CVS to read from a repository which one only has read access to; CVS needs to be able to create lock files (see section 5.5 Several developers simultaneously attempting to run CVS).

To create a repository, run the cvs init command. It will set up an empty repository in the CVS root specified in the usual way (see section 3 The Repository). For example,

cvs -d /usr/local/cvsroot init

cvs init is careful to never overwrite any existing files in the repository, so no harm is done if you run cvs init on an already set-up repository.

cvs init will enable history logging; if you don't want that, remove the history file after running cvs init. See section C.10 The history file.

3.7 Backing up a repository

There is nothing particularly magical about the files in the repository; for the most part it is possible to back them up just like any other files. However, there are a few issues to consider.

The first is that to be paranoid, one should either not use CVS during the backup, or have the backup program lock CVS while doing the backup. To not use CVS, you might forbid logins to machines which can access the repository, turn off your CVS server, or similar mechanisms. The details would depend on your operating system and how you have CVS set up. To lock CVS, you would create `#cvs.rfl' locks in each repository directory. See section 5.5 Several developers simultaneously attempting to run CVS, for more on CVS locks. Having said all this, if you just back up without any of these precautions, the results are unlikely to be particularly dire. Restoring from backup, the repository might be in an inconsistent state, but this would not be particularly hard to fix manually.

When you restore a repository from backup, assuming that changes in the repository were made after the time of the backup, working directories which were not affected by the failure may refer to revisions which no longer exist in the repository. Trying to run CVS in such directories will typically produce an error message. One way to get those changes back into the repository is as follows:

3.8 Moving a repository

Just as backing up the files in the repository is pretty much like backing up any other files, if you need to move a repository from one place to another it is also pretty much like just moving any other collection of files.

The main thing to consider is that working directories point to the repository. The simplest way to deal with a moved repository is to just get a fresh working directory after the move. Of course, you'll want to make sure that the old working directory had been checked in before the move, or you figured out some other way to make sure that you don't lose any changes. If you really do want to reuse the existing working directory, it should be possible with manual surgery on the `CVS/Repository' files. You can see section 3.3 How data is stored in the working directory, for information on the `CVS/Repository' and `CVS/Root' files, but unless you are sure you want to bother, it probably isn't worth it.

3.9 Remote repositories

Your working copy of the sources can be on a different machine than the repository. Using CVS in this manner is known as client/server operation. You run CVS on a machine which can mount your working directory, known as the client, and tell it to communicate to a machine which can mount the repository, known as the server. Generally, using a remote repository is just like using a local one, except that the format of the repository name is:

:method:user@hostname:/path/to/repository

The details of exactly what needs to be set up depend on how you are connecting to the server.

If method is not specified, and the repository name contains `:', then the default is ext or server, depending on your platform; both are described in section 3.9.2 Connecting with rsh.

3.9.1 Server requirements

The quick answer to what sort of machine is suitable as a server is that requirements are modest--a server with 32M of memory or even less can handle a fairly large source tree with a fair amount of activity.

The real answer, of course, is more complicated. The CVS server consists of two processes for each client that it is serving. Memory consumption on the child process should remain fairly small. Memory consumption on the parent process, particularly if the network connection to the client is slow, can be expected to grow to slightly more than the size of the sources in a single directory, or two megabytes, whichever is larger.

Multiplying the size of each CVS server by the number of servers which you expect to have active at one time should give an idea of memory requirements for the server. For the most part, the memory consumed by the parent process probably can be swap space rather than physical memory.

Resource consumption for the client or the non-client/server CVS is even more modest--any machine with enough capacity to run the operating system in question should have little trouble.

3.9.2 Connecting with rsh

CVS uses the `rsh' protocol to perform these operations, so the remote user host needs to have a `.rhosts' file which grants access to the local user.

For example, suppose you are the user `mozart' on the local machine `toe.grunge.com', and the server machine is `chainsaw.yard.com'. On chainsaw, put the following line into the file `.rhosts' in `bach''s home directory:

toe.grunge.com  mozart

Then test that rsh is working with

rsh -l bach chainsaw.yard.com 'echo $PATH'

Next you have to make sure that rsh will be able to find the server. Make sure that the path which rsh printed in the above example includes the directory containing a program named cvs which is the server. You need to set the path in `.bashrc', `.cshrc', etc., not `.login' or `.profile'. Alternately, you can set the environment variable CVS_SERVER on the client machine to the filename of the server you want to use, for example `/usr/local/bin/cvs-1.6'.

There is no need to edit inetd.conf or start a CVS server daemon.

There are two access methods that you use in CVSROOT for rsh. :server: specifies an internal rsh client, which is supported only by some CVS ports. :ext: specifies an external rsh program. By default this is rsh but you may set the CVS_RSH environment variable to invoke another program which can access the remote server (for example, remsh on HP-UX 9 because rsh is something different). It must be a program which can transmit data to and from the server without modifying it; for example the Windows NT rsh is not suitable since it by default translates between CRLF and LF. The OS/2 CVS port has a hack to pass `-b' to rsh to get around this, but since this could potentially cause problems for programs other than the standard rsh, it may change in the future. If you set CVS_RSH to SSH or some other rsh replacement, the instructions in the rest of this section concerning `.rhosts' and so on are likely to be inapplicable; consult the documentation for your rsh replacement.

Continuing our example, supposing you want to access the module `foo' in the repository `/usr/local/cvsroot/', on machine `chainsaw.yard.com', you are ready to go:

cvs -d :ext:bach@chainsaw.yard.com:/usr/local/cvsroot checkout foo

(The `bach@' can be omitted if the username is the same on both the local and remote hosts.)

3.9.3 Direct connection with password authentication

The CVS client can also connect to the server using a password protocol. This is particularly useful if using rsh is not feasible (for example, the server is behind a firewall), and Kerberos also is not available.

To use this method, it is necessary to make some adjustments on both the server and client sides.

3.9.3.1 Setting up the server for password authentication

On the server side, the file `/etc/inetd.conf' needs to be edited so inetd knows to run the command cvs pserver when it receives a connection on the right port. By default, the port number is 2401; it would be different if your client were compiled with CVS_AUTH_PORT defined to something else, though.

If your inetd allows raw port numbers in `/etc/inetd.conf', then the following (all on a single line in `inetd.conf') should be sufficient:

2401  stream  tcp  nowait  root  /usr/local/bin/cvs
cvs -b /usr/local/bin --allow-root=/usr/cvsroot pserver

The `-b' option specifies the directory which contains the RCS binaries on the server. You could also use the `-T' option to specify a temporary directory.

The `--allow-root' option specifies the allowable CVSROOT directory. Clients which attempt to use a different CVSROOT directory will not be allowed to connect. If there is more than one CVSROOT directory which you want to allow, repeat the option.

If your inetd wants a symbolic service name instead of a raw port number, then put this in `/etc/services':

cvspserver      2401/tcp

and put cvspserver instead of 2401 in `inetd.conf'.

Once the above is taken care of, restart your inetd, or do whatever is necessary to force it to reread its initialization files.

Because the client stores and transmits passwords in cleartext (almost--see section 3.9.3.3 Security considerations with password authentication, for details), a separate CVS password file may be used, so people don't compromise their regular passwords when they access the repository. This file is `$CVSROOT/CVSROOT/passwd' (see section 3.4 The administrative files). Its format is similar to `/etc/passwd', except that it only has two fields, username and password. For example:

bach:ULtgRLXo7NRxs
cwang:1sOp854gDF3DY

The password is encrypted according to the standard Unix crypt() function, so it is possible to paste in passwords directly from regular Unix `passwd' files.

When authenticating a password, the server first checks for the user in the CVS `passwd' file. If it finds the user, it compares against that password. If it does not find the user, or if the CVS `passwd' file does not exist, then the server tries to match the password using the system's user-lookup routine. When using the CVS `passwd' file, the server runs under as the username specified in the the third argument in the entry, or as the first argument if there is no third argument (in this way CVS allows imaginary usernames provided the CVS `passwd' file indicates corresponding valid system usernames). In any case, CVS will have no privileges which the (valid) user would not have.

It is possible to "map" cvs-specific usernames onto system usernames (i.e., onto system login names) in the `$CVSROOT/CVSROOT/passwd' file by appending a colon and the system username after the password. For example:

cvs:ULtgRLXo7NRxs:kfogel
generic:1sOp854gDF3DY:spwang
anyone:1sOp854gDF3DY:spwang

Thus, someone remotely accessing the repository on `chainsaw.yard.com' with the following command:

cvs -d :pserver:cvs@chainsaw.yard.com:/usr/local/cvsroot checkout foo

would end up running the server under the system identity kfogel, assuming successful authentication. However, the remote user would not necessarily need to know kfogel's system password, as the `$CVSROOT/CVSROOT/passwd' file might contain a different password, used only for CVS. And as the example above indicates, it is permissible to map multiple cvs usernames onto a single system username.

This feature is designed to allow people repository access without full system access (in particular, see See section 3.10 Read-only repository access); however, also See section 3.9.3.3 Security considerations with password authentication. Any sort of repository access very likely implies a degree of general system access as well.

Right now, the only way to put a password in the CVS `passwd' file is to paste it there from somewhere else. Someday, there may be a cvs passwd command.

3.9.3.2 Using the client with password authentication

Before connecting to the server, the client must log in with the command cvs login. Logging in verifies a password with the server, and also records the password for later transactions with the server. The cvs login command needs to know the username, server hostname, and full repository path, and it gets this information from the repository argument or the CVSROOT environment variable.

cvs login is interactive -- it prompts for a password:

cvs -d :pserver:bach@chainsaw.yard.com:/usr/local/cvsroot login 
CVS password: 

The password is checked with the server; if it is correct, the login succeeds, else it fails, complaining that the password was incorrect.

Once you have logged in, you can force CVS to connect directly to the server and authenticate with the stored password:

cvs -d :pserver:bach@chainsaw.yard.com:/usr/local/cvsroot checkout foo

The `:pserver:' is necessary because without it, CVS will assume it should use rsh to connect with the server (see section 3.9.2 Connecting with rsh). (Once you have a working copy checked out and are running CVS commands from within it, there is no longer any need to specify the repository explicitly, because CVS records it in the working copy's `CVS' subdirectory.)

Passwords are stored by default in the file `$HOME/.cvspass'. Its format is human-readable, but don't edit it unless you know what you are doing. The passwords are not stored in cleartext, but are trivially encoded to protect them from "innocent" compromise (i.e., inadvertently being seen by a system administrator who happens to look at that file).

The password for the currently choosen remote repository can be removed from the CVS_PASSFILE by using the cvs logout command.

The CVS_PASSFILE environment variable overrides this default. If you use this variable, make sure you set it before cvs login is run. If you were to set it after running cvs login, then later CVS commands would be unable to look up the password for transmission to the server.

3.9.3.3 Security considerations with password authentication

The passwords are stored on the client side in a trivial encoding of the cleartext, and transmitted in the same encoding. The encoding is done only to prevent inadvertent password compromises (i.e., a system administrator accidentally looking at the file), and will not prevent even a naive attacker from gaining the password.

The separate CVS password file (see section 3.9.3.1 Setting up the server for password authentication) allows people to use a different password for repository access than for login access. On the other hand, once a user has access to the repository, she can execute programs on the server system through a variety of means. Thus, repository access implies fairly broad system access as well. It might be possible to modify CVS to prevent that, but no one has done so as of this writing. Furthermore, there may be other ways in which having access to CVS allows people to gain more general access to the system; noone has done a careful audit.

In summary, anyone who gets the password gets repository access, and some measure of general system access as well. The password is available to anyone who can sniff network packets or read a protected (i.e., user read-only) file. If you want real security, get Kerberos.

3.9.4 Direct connection with kerberos

The main disadvantage of using rsh is that all the data needs to pass through additional programs, so it may be slower. So if you have kerberos installed you can connect via a direct TCP connection, authenticating with kerberos.

To do this, CVS needs to be compiled with kerberos support; when configuring CVS it tries to detect whether kerberos is present or you can use the `--with-krb4' flag to configure.

The data transmitted is not encrypted by default. Encryption support must be compiled into both the client and server; use the `--enable-encryption' configure option to turn it on. You must then use the -x global option to request encryption.

You need to edit inetd.conf on the server machine to run cvs kserver. The client uses port 1999 by default; if you want to use another port specify it in the CVS_CLIENT_PORT environment variable on the client.

When you want to use CVS, get a ticket in the usual way (generally kinit); it must be a ticket which allows you to log into the server machine. Then you are ready to go:

cvs -d :kserver:chainsaw.yard.com:/user/local/cvsroot checkout foo

Previous versions of CVS would fall back to a connection via rsh; this version will not do so.

3.10 Read-only repository access

It is possible to grant read-only repository access to people using the password-authenticated server (see section 3.9.3 Direct connection with password authentication). (The other access methods do not have explicit support for read-only users because those methods all assume login access to the repository machine anyway, and therefore the user can do whatever local file permissions allow her to do.)

A user who has read-only access can do only those CVS operations which do not modify the repository, except for certain "administrative" files (such as lock files and the history file). It may be desirable to use this feature in conjunction with user-aliasing (see section 3.9.3.1 Setting up the server for password authentication). However, note that read-only access does not repeal the existing security considerations in See section 3.9.3.3 Security considerations with password authentication.

There are two ways to specify read-only access for a user: by inclusion, and by exclusion.

"Inclusion" means listing that user specifically in the `$CVSROOT/CVSROOT/readers' file, which is simply a newline-separated list of users. Here is a sample `readers' file:

melissa
splotnik
jrandom

(Don't forget the newline after the last user.)

"Exclusion" means explicitly listing everyone who has write access--if the file

$CVSROOT/CVSROOT/writers

exists, then only those users listed in it have write access, and everyone else has read-only access (of course, even the read-only users still need to be listed in the CVS `passwd' file). The `writers' file has the same format as the `readers' file.

Note: if your CVS `passwd' file maps cvs users onto system users (see section 3.9.3.1 Setting up the server for password authentication), make sure you deny or grant read-only access using the cvs usernames, not the system usernames. That is, the `readers' and `writers' files contain cvs usernames, which may or may not be the same as system usernames.

Here is a complete description of the server's behavior in deciding whether to grant read-only or read-write access:

If `readers' exists, and this user is listed in it, then she gets read-only access. Or if `writers' exists, and this user is NOT listed in it, then she also gets read-only access (this is true even if `readers' exists but she is not listed there). Otherwise, she gets full read-write access.

Of course there is a conflict if the user is listed in both files. This is resolved in the more conservative way, it being better to protect the repository too much than too little: such a user gets read-only access.

3.11 Temporary directories for the server

While running, the CVS server creates temporary directories. They are named

cvs-servpid

where pid is the process identification number of the server. They are located in the directory specified by the `TMPDIR' environment variable (see section D All environment variables which affect CVS), the `-T' global option (see section A.4 Global options), or failing that `/tmp'.

In most cases the server will remove the temporary directory when it is done, whether it finishes normally or abnormally. However, there are a few cases in which the server does not or cannot remove the temporary directory, for example:

In cases such as this, you will need to manually remove the `cvs-servpid' directories. As long as there is no server running with process identification number pid, it is safe to do so.


Go to the first, previous, next, last section, table of contents.