Introduction
============

svnauthcheck checks the syntax of a subversion authorization file and
generates apache-like permissions specifications to be used by other
tools as ViewVC

svnauthcheck in combination with subversion pre- and post- commit
hooks can be used to delegate the administration of a repository
authorization to the end users (see "Delegating access control to the
end users")

Usage
=====

usage: [OPTIONS] [AUTHFILE]

Options

       -a, --apache=htaccess
              generates an apache-style permission file to be used with ViewCV

       -h, --help
              this help message

       -h     help

       -s, --subtree=subtree
              the svnauth file is partial and is valid only for the given subtree

       -t, --template=template
              Apache authentication template to be used with -a

       -T, --trac=path
              the path of the trac project dir

       -u, --user=user
              specifies a user that should have write access to the top directory

       -v, --verbose
              verbose

       -V, --version
              prints the version of the program


Delegating access control to the end users
==========================================

To allow a user to access a given resource a subversion server usually
performs two steps: authentication and authorization. In the
authentication phase the server (in our case Apache) is responsible
for identifying the user as himself. In the authorization phase
Subversion decides if the given user is allowed to access the
specified resource.

When fine-grained permissions are needed (i.e., access control is
managed at directory level) the Subversion module (mod_authz_svn)
offers the possibility to specify a file (AuthzSVNAccessFile
/path/to/access/file) which contains a set of rules defining who can
access what. The files resides on the server and modifying it (e.g.,
adding and removing users, changing permissions) has to be performed
by a special user (the Subversion server administrator) which has
access to the server machine and permission to write the authorization
file.

When the users that have write access repository are trustworthy it
would be preferable to give them the possibility to decide who can do
what on the repository they can write to without having to involve the
Subversion repository administrator.

As an example you could think to a Subversion server for students
where each student has a valid account (i.e., he can be authenticated)
and where each student can decide on its own who can read and write
his own projects (without asking the administrator).

The idea behind svnauthcheck is to store the access file used by
AuthzSVNAccessFile in the repository itself. In this example we will
use for each repository a file called svnacces.

Example:

  $ svn co https://svn.id.ethz.ch/test
  $ ls test
  branches svnaccess tags  trunk
    
The svnaccess file can then be edited by any user which has write
access to the root of the repository.

Since the repository is not directly accessible on the server the file
has to be made accessible to Apache after each successful commit.

This can be achieved with the following post-commit hook:

  #!/bin/sh

  REPOS="$1"
  REV="$2"

  svn cat file://${REPOS}/svnaccess > ${REPOS}/svnaccess
    

In this way each time a commit is performed, the most recent svnaccess
file is written to the file system and made accessible to Apache (the
AuthzSVNAccessFile directive must be then set to point the location
where the file is checked out).

The operation describe above has certain risks: a user could submit a
syntactically incorrect file or could lock everybody out removing all
the users.

To avoid these problems svnauthcheck can be used to check the validity
of the committed svnaccess files before accepting them (svnauthcheck
can do a little more but for the moment let's consider just the
authorization file checks).

The following pre-commit hook allows to check the syntax of the
authorization files and to block erroneous submissions (the error
messages of svnauthcheck are reported to the user which can then
correct the problem).

  #!/bin/sh

  REPOS="$1"
  TXN="$2"

  if svnlook cat -t "$TXN" "$REPOS" "svnaccess" | svnauthcheck ; then
      exit 0
  else
      exit 1
  fi
    

ViewVC integration
==================

ViewVC (http://www.viewvc.org/) is popular tool that allows to browse
a Subversion repository with a web browser. It currently doesn't
support the possibility to rely on the same permission scheme as the
Subversion Apache module and supports only the classical Apache access
control.

We added an option to the svnauthcheck tool to generate an Apache
configuration file to be used with ViewVC containing the same
information in the svnaccess file rewritten in Apache-style.

As an example the svnaccess file for the repository test

  [/]
  user1 = rw
  [/public]
  user2 = rw
  user3 = rw
    
is automatically translated to

  <Location /viewvc/test/>
  Require user user1
  </Location>
  <Location /viewvc/test/public/>
  Require user user1 user2 user3
  </Location>

a template file can be supplied with the -t option to further
customize the Apache permissions.

trac
====

svnauthcheck can be also used to manage access to a trac project
corresponding to the handled Subversion repository.

Trac permissions can be specified in the svaccess file as follows

#trac PERMISSION = USER

Example:

#trac TRAC_ADMIN = someuser
#trac LOG_VIEW = anonymous
#trac FILE_VIEW = anonymous
#trac WIKI_VIEW = anonymous

and are applied to the project specified using the -T option

--------------------------------------------------------------------------------
Please report bugs to: Matteo Corti <matteo.corti@id.ethz.ch>