]> oss.titaniummirror.com Git - repo_shell.git/blobdiff - README
Big README cleanup; add README.gitacls
[repo_shell.git] / README
diff --git a/README b/README
index 5226c0e9375de1af42f67cae13a0325841256b4d..14db116d35606c399de95841e6275edc0a4cedbd 100644 (file)
--- a/README
+++ b/README
-repo_shell provides a login shell for servers hosting subversion and/or git
-centralized repositories.  Unlike gitolite, which is a more full-featured and
-powerful solution for git, repo_shell requires user accounts to be set up on the
-server for each developer.  This allows a critical feature that we needed: the
-option to allow access to a repository via a user's password in addition to an
-SSH key pair.  This feature is useful when needing to check out objects from a
-repository where copying the user's private key to some machine is either
-undesirable or a waste of time.
+= About repo_shell
 
-repo_shell owes great thanks to work shared by two other projects:
+repo_shell provides a login shell simplifying hosting of centralized subversion
+and git repositories.  Repositories are accessed via SSH as the requesting
+user.  SSH key authentication is activated when a user adds their SSH private
+key to their ~username:.ssh/authorized_keys file on the server.
 
-- 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.
+repo_shell supports authorization on a per user and per repository basis.  For
+git, repo_shell authorizes using an internal algorithm against a server-wide git
+acl file.  For subversion, repo_shell leverages the already existing path based
+access control functionality.
 
-- 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.
+To increase integrity of the repositories and to simplify filesystem
+permissions, repo_shell expects all repository files to be owned by a single,
+configurable system user.  Users cannot access repository files directly on the
+server, only using the git or subversion client side tools.
 
-To acquire repo_shell:
+= Acquire, build and install
 
     git clone git://oss.titaniummirror.com/repo_shell.git
+    cd repo_shell
+    make
+    sudo make install
 
-To build repo_shell, use make.  Please build from a clone of the above
-repository, as the make script uses 'git describe --tags' to generate the
-resulting executable's version string.
-
-    make repo_shell
+Please build from a repository clone, as the make script uses
+'git describe --tags' to generate the resulting executable's version string.
 
-To install repo_shell:
+= Configure /etc/repo_shell.cfg
 
-    sudo cp repo_shell /usr/local/bin/
-    sudo chown root:root /usr/local/bin/repo_shell
-    sudo chmod u+s /usr/local/bin/repo_shell
-    vi /etc/repo_shell.cfg
-
-The /etc/repo_shell.cfg configuration file is straightforward:
+The file /etc/repo_shell.cfg must contain certain fields:
 
     owner=repo
-    git_root=/var/lib/git
     svn_root=/var/lib/svn/repositories
+    git_root=/var/lib/git
     git_acl_file=/var/lib/git/.gitacls
 
-The owner field denotes the user that owns all repositories.  The git_root and
-svn_root fields identify the path to the respective repositories.  The latter
-two fields allow repo_shell to automatically add the appropriate repository root
-path to repository access commands, obviating the need for developers to know
-exactly where repositories are stored.  Note that git repositories can be nested
-within directories, as the examples show below.
-
-    git clone server:repo.git          -> server:<git_root>/repo.git
-    git clone server:/repo.git         -> server:<git_root>/repo.git
-    git clone server:/subdir/repo.git  -> server:<git_root>/subdir/repo.git
-    svn checkout svn+ssh://server/repo -> server:<svn_root>/repo
-
-Repositories should be owned by the user identified in the owner field.  For
-example:
-
-    sudo -iu owner
-    umask 077
-    svnadmin create --fs-type fsfs <svn_root>/newreponame
-    git --git-dir <git_root>/newrepopath.git init --bare
-
-Please see the svncreate for an example helper script for subversion repository
-creation.
-
-To use external viewers that directly interrogate the repository, the simplest
-solution is to have those viewers run as another user belonging to the owner's
-primary group.  In this case, in the examples above, a umask of 027 is
-appropriate when creating repositories.  However, please note that such external
-programs are able to read all repositories independent of access controls.
-
-For users to have access to repositories, they need only have repo_shell set as
-their login shell:
-
-    sudo chsh -s /usr/local/bin/repo_shell <developername>
-
-And of course the user must be associated for appropriate access in subversion
-and get access control lists.
-
-Access controls for subversion repositories uses subversion's built-in features,
-using svnserve.conf.  A good way to go is to have each repository's
-svnserve.conf set a global authz.conf file, using the standard hooks and
-activating svnperms.conf for branch-based commit control.  These are suggestions
-outside the scope of the repo_shell program itself.
-
-Access controls for git repositories uses a feature built-into repo_shell.  The
-/etc/repo_shell.cfg file lists a parameter git_acl_file, which should be set to
-the name of the git acl file.  A recommended name is /var/lib/git/.gitacls, with
-permissions 0400.  See git_acl.cfg.example for information on the format of this
-file, which is similar in concept, but different, than subversion's authz.conf
-file format.
+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
+
+= Create owner and paths
+
+In accordance with the contents of /etc/repo_shell.cfg:
+
+    adduser --system --group repo --home /var/lib/svn \
+       --shell /usr/local/bin/repo_shell repo
+    sudo install -d -o repo -g repo -m 0755 /var/lib/svn/repositories
+    sudo install -d -o repo -g repo -m 0755 /var/lib/git
+
+= 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