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
       execution 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  password
       of    the    setup   user   are   both   "setup".   Passwords,   rather
       counterintuitively, are changed by following the "Logout" hyperlink  at
       the bottom 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
       commands, 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
       system,  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).