CVSTRAC(1)						      General Commands Manual							CVSTRAC(1)

NAME

       cvstrac - Low-ceremony bug tracker for projects under CVS

SYNOPSIS

       cvstrac [ command [ params ... ] ... ]

DESCRIPTION

       The cvstrac command is used to run the CVSTrac web service, or to initialise new databases for projects.

       Please read the section titled Security and Setup for details of the default password and why you should change it.

       This manual page was written for the Debian distribution because the original program source does contain a manual page. However CVSTrac is
       well documented at the CVSTrac Wiki, <http://www.cvstrac.org/cvstrac/wiki>, and you will be able  to  fin  d  more  up-to-date  information
       there.

OPTIONS

       Running	cvstrac  without  options  produces a usage message. A summary of the command sequences which can be passed to cvstrac is included
       below. For more details, see /usr/share/doc/cvstrac on this system.

       chroot dir user
	      Tells cvstrac to put itself into the chroot gaol dir and switch to the named user, dropping root privileges. These three	parameters
	      must be the first passed to cvstrac, and processing of command line parameters continues as normal after the chroot.

       init dir project
	      Initialises  a  new CVSTrac database.  dir is the name of the directory in which you want the database to reside, and project is the
	      name of the project that CVSTrac will be hosting. The database file will be created as dir/project.db

       The following parameters cause CVSTrac to begin responding to HTTP requests by various methods. You will need to set up the database before
       use  to	ensure	that only authorised users have administrative access.	PLEASE READ and understand the section below entitled Security and
       Setup before using these commands, because unless you understand what to do you'll be leaving your system vulnerable to arbitrary code exe-
       cution as the user invoking CVSTrac.

       http dir [ project ]
	      Causes  CVSTrac  to  start running as an HTTP server on the standard input, displaying responses to the standard out.  dir should be
	      the name of a directory holding project database or databases created by cvstrac init and project is the name of a project  database
	      without the ".db" extension, as for cvstrac init.  If the latter option is given, access is restricted to just the named project DB,
	      and the access URL will change slightly. See below for details.

       cgi dir [ project ]
	      Causes CVSTrac to respond as a CGI script.  dir and project are interpreted as for cvstrac http.	This invocation can  be  installed
	      into a simple shell or Perl CGI script anywhere on a server supporting the Common Gateway Interface.

       server port dir [ project ]
	      Causes CVSTrac to run as a self-hosted HTTP server on the specified port.  dir and project are interpreted as above.

Access to CVSTrac
       CVSTrac	accesses  databases  created by its own init command, and is accessed remotely by HTTP. If you did not specify a single project to
       access in any of the http, cgi, or server commands, then the running CVSTrac instance can be used to access any database in that  directory
       simply by modifying the URL, but you will need to supply the name of the database in order to access it.

       For self-hosted server instances of CVSTrac, and http instances started from inetd, the URL to use is of the form

	      http://hostname[:port]/

       if you specified a project in the invocation, or

	      http://hostname[:port]/project/

       if you didn't.

       If  running  as a CGI script, simply use the URL you would normally use for the CGI script, with the project name you wish to access tacked
       on if necessary, as above.

       For details of the default password, and why you should change it, read on!

Security and Setup
       Once CVSTrac is installed and running, you should immediately access it as the setup user, and change the password. The username and  pass-
       word  of the setup user are both "setup". Passwords, rather counterintuitively, are changed by following the "Logout" hyperlink at the bot-
       tom of the main menu on the start screen.

       The setup user is able, in normal operation, to configure the service in a way that can cause arbitrary code to be executed under the  same
       userid as CVSTrac itself. You should be aware of this, and the fact that this can easily lead to more serious exploits if the setup user is
       compromised.

       The chroot functionality described above is not a perfect fix for this, but can be used as an additional security measure. See the  section
       below entitled Runtime Dependencies for details of what binaries the chroot gaol will need.

Access to the CVS repository
       CVSTrac	should	be installed running as a user with read access to the CVS repository specified during the interactive setup. Certain com-
       mands, such as the ability to modify CVSROOT/passwd require the write permissions too.

Runtime Dependencies
       Besides its libraries, CVSTrac requires the following binaries by default: co, rcsdiff, rlog and diff.  If running cvstrac on a Debian sys-
       tem, these will have been installed as dependencies of the cvstrac package, or as part of the base system.

SEE ALSO

       The CVSTrac wiki http://www.cvstrac.org/cvstrac/wiki and /usr/share/doc/cvstrac/examples on this system.

AUTHOR

       This manual page was written by Andrew Chadwick <andrewc@piffle.org>, for the Debian GNU/Linux system (but may be used by others).

1.1.4								  6 October 2004							CVSTRAC(1)