oreilly.comSafari Books Online.Conferences.


Essential CVS

Adventures with Kerberos, CVS, and GSS-API

by Jennifer Vesperman, author of Essential CVS

While I was writing Essential CVS, I needed to write a section about using CVS with Kerberos 5 and GSS-API. Unfortunately, I've never used Kerberos before, not even as a user or a system administrator.

I happened to be running the sid release of Debian Linux. I needed to practice using CVS with both Kerberos 5 and Kerberos 4, so I chose the Heimdal implementation of Kerberos 5 because it includes Kerberos 4 support. I used CVS 1.11.2, which was the latest stable version. I was running the client and the server on the same computer to make the task easier.

(Note: CVS 1.11.5 became the latest stable before I finished Essential CVS, and I updated it before it went into technical review. I strongly recommend that you use at least CVS 1.11.5 because of a security problem with earlier versions.)

Installing CVS and Heimdal

The easiest way to install CVS on a Debian system is to use apt, with the command apt-get install cvs. However, the binaries from the Debian package I used weren't compiled to allow you to use GSS-API and Kerberos, and I needed to compile from source. To install the CVS sources, I used apt-get source cvs.

You can check whether your CVS installation is compiled to run GSS-API by trying to check out a project. Test both client and server. Example 1 shows what happens if it fails.

Example 1 — testing gserver mode

bash-2.05a$ cvs -d :gserver:cvs:/var/lib/cvs checkout wizzard
cvs checkout: CVSROOT is set for a GSS-API access method but your
cvs checkout: CVS executable doesn't support it.
cvs [checkout aborted]: Bad CVSROOT: `:gserver:cvs:/var/lib/cvs'.

Related Reading

Essential CVS
By Jennifer Vesperman

You can also install Heimdal with the command apt-get install heimdal. To compile CVS for GSS-API, you need to install the Heimdal libraries as well, which you can do with apt-get source heimdal.

It didn't initially occur to me to install the Heimdal libraries, so my first attempt at compiling CVS with GSS-API failed.

Compiling CVS

CVS will automatically support its gserver repository access method if it finds GSS-API and Kerberos 5 libraries at compile time. Installations from packages may or may not support gserver, depending on the package maintainer's choices. My installation of CVS didn't, so the first thing to do was to try to compile CVS.

I read the INSTALL file (always read the INSTALL file) and tried to run the configure script with the option --with-gssapi. CVS searched for the GSS-API libraries, but the Debian package for Heimdal installed them in /usr/include, and CVS did not find them there.

Example 2 is part of the configure output when CVS doesn't find GSS-API and Kerberos libraries. There was no error message, so you need to check this output carefully. You can also find a configure report in the file config.log.

Example 2 — configure fails to find GSS-API

default place for krb4 is /usr/kerberos
checking for krb.h... 
checking for krb_get_err_text... no
checking for GSS-API
checking for GSS-API.h... no
checking for GSS-API/GSS-API.h... no
checking for krb5.h... no
checking for GSS-API in /usr/kerberos
checking for GSS-API.h... no
checking for GSS-API/GSS-API.h... no
checking for krb5.h... no
checking for GSS-API in /usr/cygnus/kerbnet
checking for GSS-API.h... no
checking for GSS-API/GSS-API.h... no
checking for krb5.h... no
checking for GSS-API... no

As I discovered when I reread the INSTALL file, and read the source for the configure script, the syntax for --with-gssapi is actually --with-gssapi[=directory]. The directory should contain the header files, but need not contain them directly--if they are in /usr/gssapi/include and /usr/gssapi/lib, you can use /usr/gssapi as the argument.

I also found that my INSTALL file listed --enable-encryption instead of --enable-encrypt. Check the INSTALL file in your source code to see which command your configure script expects.

Then I had a couple of failed configure runs which didn't make sense until I reread the INSTALL file, consulted a friendly sysadmin guru, and realized I had forgotten to run make distclean.

The final command I used for configure was configure --with-GSS-API=/usr/include --with-krb4=/usr/include --enable-encryption. I used --with-krb4 to compile CVS for Kerberos 4, which isn't necessary if you're only compiling for Kerberos 5. The relevant parts of successful configure output are shown in Example 3.

Example 3 — configure finds GSS-API

default place for krb4 is /usr/include
checking for krb.h... yes
checking for printf in -lkrb... yes
checking for printf in -ldes... no
checking for krb_get_err_text... yes
checking for GSS-API... /usr/include
checking for GSS-API.h... yes
checking for GSS-API/GSS-API.h... no
checking for GSS-API/GSS-API_generic.h... no
checking for krb5.h... yes
checking for GSS_C_NT_HOSTBASED_SERVICE... yes
checking for library containing des_set_odd_parity... none required
checking for library containing com_err... none required
checking for library containing initialize_asn1_error_table_r... -lasn1
checking for library containing __dn_expand... none required
checking for library containing roken_gethostbyaddr... -lroken
checking for library containing valid_enctype... no
checking for library containing compile... no
checking for library containing krb5_free_context... -lkrb5
checking for library containing gss_import_name... -lGSS-API

So, in order to compile CVS with GSS-API and Kerberos 5 support:

  1. Ensure that you have the necessary header files available, including GSS-API and Kerberos 5 libraries.
  2. Change directories to the CVS source directory.
  3. Run make distclean to remove any cached configuration information or other remnants of previous compilations.
  4. Run configure with the arguments you need. To configure CVS for GSS-API and Kerberos 5, use --with-gssapi. To enable encryption, use --enable-encrypt. You may need to read the INSTALL file; you may also need to state the library location explicitly.
  5. Run make, switch to root, then run make install.


The next step was configuring inetd to run the CVS server automatically when someone tries to connect to it. If inetd isn't configured, an attempt to connect to CVS with the gserver method will result in an error message as shown in example 4.

Example 4 — inetd not configured

bash$ cvs -d :gserver:helit:/home/cvs checkout wizzard
cvs [checkout aborted]: connect to helit( failed:
	Connection refused

Configuring inetd went smoothly. The instructions for configuring inetd are in info:cvs#Password_authentication_server or in chapter 6 of Essential CVS. CVS uses pserver for gserver GSSAPI/Kerberos 5 connections.

CVS 1.11.2 bug

The version of CVS that I was using (version 1.11.2) has an bug in its GSS-API code--a bug which produces the message shown in example 5 when it attempts to connect to a GSS-API server. Later versions do not have this problem, and you should be using CVS 1.11.5 or later for security reasons anyway. This is a legitimate error message if the file that it is attempting to connect through is not a socket. The bug causes it to be reported in all cases.

Example 5 — CVS 1.11.2 bug

cvs [import aborted]: gserver currently only enabled for socket

A temporary fix is to use a patch to modify the auth_server() function in client.c, and move the definition of stdio_buffer_closure from buffer.c to buffer.h. This repair was created by Brandon Rhodes and is described in the archives of the info-cvs mailing list.

Configuring Kerberos

Once CVS was running gserver successfully as both client and server, I configured the Kerberos configuration file /etc/krb5.conf. I used the Heimdal installation documentation and info heimdal to work out what to put into the config file, and I attempted to set up the Kerberos principal cvs/NOSUCH.COM@NOSUCH.COM.*. A misconfigured Kerberos file produces the errors shown in examples 6 and 7.

Example 6 — Kerberos 5 misconfigured - client side

bash$ cvs -d :gserver:helit:/home/cvs checkout wizzard
cvs checkout: GSS-API authentication failed:  Miscellaneous failure (see text)
cvs [checkout aborted]: GSS-API authentication failed:
	No such entry in the database

Example 7 — Kerberos 5 misconfigured /var/log/heimdal-kdc.log

2002-10-20T20:11:53 Server not found in database:
	cvs/ No such entry in the database

After more reading, experimentation, and the occasional bout of swearing, I used kadmin -l to change the principal to cvs/, and made progress. I had a new error. I needed to create the principal with a random key and export the key so that CVS could use it. The new error is shown in example 8. Example 9 shows how I successfully added the CVS principal and eliminated the error.

Example 8 — Kerberos 5 still misconfigured

Kerberos 5 still misconfigured
cvs [checkout aborted]: error from server helit: cvs [pserver aborted]: 
   could not acquire GSS-API server credentials

Example 9 — correctly adding a CVS principal

Correctly adding a cvs principal
kadmin> add --random-key cvs/
Max ticket life [1 day]:
Max renewable life [1 week]:
Principal expiration time [never]:
Password expiration time [never]:
Attributes []:
kadmin> ext cvs/
bash$ ktutil list

Vno  Type           Principal                         
  1  des-cbc-crc    cvs/
  1  des-cbc-md4    cvs/
  1  des-cbc-md5    cvs/
  1  des3-cbc-sha1  cvs/

Getting a ticket

After all of this, I forgot to get a new ticket in the Kerberos client. The error is shown in example 10. Once I used kinit as the client to get a ticket, gserver mode worked for me.

Example 10 — user didn't have a ticket

cvs [checkout aborted]: error from server blackrock: 
   cvs [pserver aborted]: could not verify credentials

Final Words

All of this was to produce two sections of a single chapter of Essential CVS, and to be sure I was accurate. I have, however, added a new page to my article ideas book: Kerberos. We definitely need more articles about Kerberos.

Further reading

  • man cvs
  • man 5 cvs
  • info cvs has a good section on 'what CVS is' and 'what CVS is not'. It's also a useful expansion on the manual. The 'Repository' section discusses protocols.
  • CVS Pocket Reference, by Gregor N. Purdy (O'Reilly and Associates)
  • Essential CVS, by Jennifer Vesperman (O'Reilly and Associates)
  • From the Big Scary Demons column: BSD Tricks: CVS
  • SourceForge has several articles on CVS. See sections 6 and 7 on the Sourceforge Site Docs page.

Jennifer Vesperman is the author of Essential CVS. She writes for the O'Reilly Network, the Linux Documentation Project, and occasionally Linux.Com.

O'Reilly & Associates will soon release (June 2003) Essential CVS.

Return to the Linux DevCenter.

Linux Online Certification

Linux/Unix System Administration Certificate Series
Linux/Unix System Administration Certificate Series — This course series targets both beginning and intermediate Linux/Unix users who want to acquire advanced system administration skills, and to back those skills up with a Certificate from the University of Illinois Office of Continuing Education.

Enroll today!

Linux Resources
  • Linux Online
  • The Linux FAQ
  • Linux Kernel Archives
  • Kernel Traffic

  • Sponsored by: