X-Git-Url: https://oss.titaniummirror.com/gitweb?a=blobdiff_plain;f=README;h=33cb71c7e92ebb2ea1f7497862962bce8a5487db;hb=d044b519a1b2faebcd1654c8fb0df4741f241dfa;hp=b20c859eeac5465ccf3a8788723568e2e5b42d82;hpb=8a41466007c7ee650aead4baf41017fd7a6f3ff6;p=repo_shell.git diff --git a/README b/README index b20c859..33cb71c 100644 --- a/README +++ b/README @@ -1,93 +1,174 @@ -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 + +Please build from a repository clone, as the make script uses +'git describe --tags' to generate the resulting executable's version string. + += Configure /etc/repo_shell.conf + +The file /etc/repo_shell.conf 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 --home /var/lib/svn \ + --shell /usr/local/bin/repo_shell + sudo install -d -o -g -m 0755 + sudo install -d -o -g -m 0755 + += 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. -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. += Create a subversion repository - make repo_shell +svncreate is a helper script installed by make install. To create a new +subversion repository, simply type: -To install repo_shell: + sudo -u repo svncreate - 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 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. -The /etc/repo_shell.cfg configuration file is straightforward: += Create a git repository - [core] - owner=repo - git_root=/var/lib/git - svn_root=/var/lib/svn/repositories - git_acl_file=/var/lib/git/.gitacls +gitcreate is a helper script installed by make install. To create a new git +repository, simply type: -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. + sudo -u repo gitcreate - git clone server:repo.git -> server:/repo.git - git clone server:/repo.git -> server:/repo.git - git clone server:/subdir/repo.git -> server:/subdir/repo.git - svn checkout svn+ssh://server/repo -> server:/repo +Git repositories may be placed in subdirectories under {git_root}. A +subdirectory may be part of . So, for example, if one wishes to +create a repository tinyos-main.git under a subdirectory mirrors/tinyos, then +the create command would be: -Repositories should be owned by the user identified in the owner field. For -example: + sudo -u repo gitcreate mirrors/tinyos/tinyos-main.git - sudo -iu owner - umask 077 - svnadmin create --fs-type fsfs /newreponame - git --git-dir /newrepopath.git init --bare += Configuring user accounts -Please see the svncreate for an example helper script for subversion repository -creation. +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 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. +To create a new user: -For users to have access to repositories, they need only have repo_shell set as -their login shell: + sudo adduser --shell /usr/local/bin/repo_shell - sudo chsh -s /usr/local/bin/repo_shell +To allow an existing user access to repositories via client-side tools: -And of course the user must be associated for appropriate access in subversion -and get access control lists. + sudo chsh -s /usr/local/bin/repo_shell -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. +To completely disable repository access for an existing user, return their shell +to /bin/bash: + + sudo chsh -s /bin/bash + +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.conf. 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 + +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. -Access controls for git repositories uses a feature built-into repo_shell. -The /etc/repo_shell.cfg file lists a core 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. +- Subversion's authz file + http://svnbook.red-bean.com/en/1.7/svn.serverconfig.pathbasedauthz.html