*Launching CVSTrac Into A Chroot Jail*

CVSTrac will automatically put itself into a chroot jail if its
first argument is _chroot_ and it is started as root.  After the
*chroot* argument, the next two arguments are the directory which
should be the new root directory and the user that the program
should run as after it is chrooted.  (CVSTrac always drops any superuser
privileges before doing any real work, regardless of whether or not
you use the *chroot* option.)  After the _chroot_ argument and its
two parameters, the usual *cgi* or *http* keyword and its arguments
appear.

When CVSTrac is run from
inetd, the inetd.conf configuration line looks something like this:

  2080 stream tcp nowait.1000 root /usr/bin/cvstrac \
       cvstrac chroot /home/cvs cvs http /

The three arguments *chroot /home/cvs cvs* tell the server to put
itself into a chroot jail located at */home/cvs* and drop superuser
privilege and become user *cvs* before continuing.  The first three
arguments are then removed and processing continues as if the
command had been launched as

  cvstrac http /

Notice that the directory argument to the _http_ directive, the argument
that tells CVSTrac where to look for its database, is specified
relative to the chroot jail, not to the regular filesystem.

*Configuring The Jail*

CVSTrac does a popen() of a few commands for some of its operations.
It uses the following external programs: *rlog rcsdiff co.*
The popen() procedure uses /bin/sh and rcsdiff uses diff.
All of these external programs most be available inside the chroot
jail.  In addition, CVSTrac needs to access a stripped-down version
of /etc/passwd at one point.  It also needs access to the /tmp
directory and to the special file /dev/null.  The /etc/localtime
file is optional, but without it, all times are shown in UTC.
It should NOT be a symlink, but a copy.

The dev/null node can be created like this:

  mknod dev/null c 1 3
  chmod ugo+rw dev/null

The following listing shows all the files and directories in the chroot jail
for the canonical CVSTrac installation:

  bin
  bin/sh
  bin/bash
  dev
  dev/null
  etc
  etc/localtime
  etc/passwd
  lib
  lib/libc.so.6
  lib/ld-linux.so.2
  lib/libtermcap.so.2
  tmp
  usr
  usr/bin
  usr/bin/rcsdiff
  usr/bin/co
  usr/bin/rlog
  usr/bin/diff

A similar set of files will be required in any chroot jail for
CVSTrac, though the details may vary.  For example, the required
libraries might change.  Or you might use a different shell.
(The bin/sh above is a hard link to bin/bash)

You can easily create a chroot jail with {link: http://olivier.sessink.nl/jailkit/ Jailkit}, it has useful utilities like jk_cp and jk_init to quickly create chroot jails and automatically copy the required libraries into the chroot jail.

You can determine which libraries are needed by using ldd for each executable you place within
the chroot jail:

  ldd /bin/bash

        libtermcap.so.2 => /lib/libtermcap.so.2 (0x4001b000)
        libc.so.6 => /lib/libc.so.6 (0x4001c000)
        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x4000d000)


*Setup Changes*

After you get CVSTrac running inside a chroot jail, you'll need to log in
as the "setup" user, go to the "setup" page, and change the path to the
CVS repository and the log file so that they are relative to the chroot
jail not the regular filesystem.  Other than that, though, no additional
setup changes are required.

*Additional Considerations*

The above instructions are intended for Linux. If you need to create a chroot jail for CVSTrac on
FreeBSD 4.x or another operating system, or if you need help troubleshooting your chroot jail
installation, please review the FrequentlyAskedQuestions.