+= Configure /etc/repo_shell.cfg
+
+The file /etc/repo_shell.cfg must contain certain fields as shown in the example
+below. The spaces surrounding the equal sign ('=') are optional.
+
+ owner = repo
+ svn_root = /var/lib/svn/repositories
+ git_root = /var/lib/git
+ git_acl_file = /var/lib/git/.gitacls
+ allowed_interactive =
+
+owner is the system account username which will own all repositories, and is
+preferaby a system account used for no other purpose. Use the adduser or
+another similar system script to assist in creating the user account. The
+account home directory can be one of the repository root paths
+
+svn_root and git_root are self-explanatory, being the longest filesystem path
+shared by repositories of that type, e.g. their shared root directory.
+
+git_acl_file is the pathname of a file providing ACL information for git
+repository access, as implemented internally bit repo_shell. A recommended
+pathname is /var/lib/git/.gitacls
+
+allow_interactive contains a list of users that may log into the server via SSH,
+or that may issue arbitrary commands to the server via SSH. Instead of a list,
+the wildcard character '*' can be used to indicate all users. Note that this
+only affects users that have /usr/local/bin/repo_shell as their login shell.
+If the server is only hosting repositories, there is no reason for users to be
+allowed 'interactive' access.
+
+= Create owner and paths
+
+In accordance with the settings in /etc/repo_shell.conf:
+
+ adduser --system --group <owner> --home /var/lib/svn \
+ --shell /usr/local/bin/repo_shell <owner>
+ sudo install -d -o <owner> -g <owner> -m 0755 <svn_root>
+ sudo install -d -o <owner> -g <owner> -m 0755 <git_root>
+
+= Configure subversion repository ACLs
+
+Subversion repositories created with the svncreate command have their
+conf/svnserve.conf file pointing to the global {svn_root}/../authz.conf file.
+It is this file that is used to set access control permissions for repositories.
+Subversion's authz file allows path based control as well. For more
+information, please see the Subversion Red Bean guide at:
+http://svnbook.red-bean.com/en/1.7/svn.serverconfig.pathbasedauthz.html
+
+= Configure git repository ACLs
+
+Git repository access control is managed by the git acl file, nominally located
+at {git_root}/.gitacls. This file has a format similar but not exactly like
+Subversion's authz file. The file defines one of three levels of access for
+various combinations of users and repositories, then compared to the git command
+arriving via SSH to determine if the access will be allowed. Please see
+README.gitacls for more information.
+
+= Create a subversion repository
+
+svncreate is a helper script installed by make install. To create a new
+subversion repository, simply type:
+
+ sudo -u repo svncreate <reponame>
+
+The script creates an fsfs type repository with proper permissions, and
+referencing the {svn_root}/../authz.conf file for access control. Edit this
+file as necesssary to allow access to the new repository.
+
+= Create a git repository
+
+gitcreate is a helper script installed by make install. To create a new git
+repository, simply type:
+
+ sudo -u repo gitcreate <repopath>
+
+Git repositories may be placed in subdirectories under {git_root}. A
+subdirectory may be part of <repopath>. So, for example, if one wishes to
+create a repository tinyos-main.git under a subdirectory mirrors/tinyos, then
+the create command would be:
+
+ sudo -u repo gitcreate mirrors/tinyos/tinyos-main.git
+
+= Configuring user accounts
+
+Each user to access repositories via client side tools need an account on the
+server. This was a purposeful design decision to allow password authentication
+as well as key authentication via SSH. Accounts for repository users must have
+/usr/local/bin/repo_shell set as their shell.
+
+To create a new user:
+
+ sudo adduser --shell /usr/local/bin/repo_shell <newuser>
+
+To allow an existing user access to repositories via client-side tools:
+
+ sudo chsh -s /usr/local/bin/repo_shell <existinguser>
+
+To completely disable repository access for an existing user, return their shell
+to /bin/bash:
+
+ sudo chsh -s /bin/bash <existinguser>
+
+or, instead, ensure their access permissions to repositories is set to none for
+both subversion and git repositories.
+
+= Access paths for client side access
+
+Users interact with subversion and git repositories using what we somewhat
+incorrectly call access paths. In both cases, the access path is relative to
+the respective repository type root, as defined in /etc/repo_shell.cfg. In
+other words, the user does not need to know where the repository is stored. In
+the case of git, a repository can be under a subdirectory. A couple of
+examples:
+
+ svn checkout svn+ssh://server/my_repository/trunk my_repository
+ git clone server:my_repository.git
+ git clone server:mirrors/tinyos/tinyos-main.git
+
+= Repository access for other applications
+
+Local system applications, such as web based viewers, may gain read-only access
+to repositories by adding the user which runs such a tool to the repository
+owner's group. However, such an access method bypasses access control
+functionality and all repositories will be viewable by the application.
+
+A better solution, requiring some scripting work, would be to have the other
+application use output from the repo_shell -c command to determine access.
+
+ repo_shell -c <username> <reponame>
+
+This command returns one of three results. An empty return string means no
+access, an "r" means read-only, and "rw" means read-write access.
+
+= References and links
+
+repo_shell owes great thanks to work shared by two other projects:
+
+- The GIT stupid content tracker - http://git-scm.org
+ Some useful information was gleaned from git's git-shell program.
+ GIT is licensed under the GPLv2.
+
+- The inih .ini parser library - http://code.google.com/p/inih/
+ This is a great little library for handling simple configuration files.
+ inih is licensed under a modified BSD license, available in inih/LICENSE.txt.
+
+- Subversion's authz file
+ http://svnbook.red-bean.com/en/1.7/svn.serverconfig.pathbasedauthz.html