From: R. Steve McKown Date: Fri, 28 Sep 2012 19:08:18 +0000 (-0600) Subject: Big README cleanup; add README.gitacls X-Git-Tag: 0.5~17 X-Git-Url: https://oss.titaniummirror.com/gitweb?p=repo_shell.git;a=commitdiff_plain;h=37b4fa8991194603aa19e3a7b5d24d768b776a6d Big README cleanup; add README.gitacls --- diff --git a/README b/README index 5226c0e..14db116 100644 --- a/README +++ b/README @@ -1,92 +1,165 @@ -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:/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 - -Repositories should be owned by the user identified in the owner field. For -example: - - sudo -iu owner - umask 077 - svnadmin create --fs-type fsfs /newreponame - git --git-dir /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 - -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 + +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 + +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: + + 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 + +To allow an existing user access to repositories via client-side tools: + + sudo chsh -s /usr/local/bin/repo_shell + +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.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 + +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 diff --git a/README.gitacls b/README.gitacls new file mode 100644 index 0000000..fc9315c --- /dev/null +++ b/README.gitacls @@ -0,0 +1,115 @@ +Git ACLs are defined in the git_acl_file, whose location is defined within the +/etc/repo_shell.cfg configuration file. This file is similar in passing to the +Subversion authz.conf file format as defined in +http://svnbook.red-bean.com/en/1.7/svn.serverconfig.pathbasedauthz.html. + +The file has three section types: + + [user_groups] + [repo_groups] + [repo ...] Multiple repo setions are allowed + +user_groups section defines userid's that denote groups of users. This can +greatly simplify the configuration file contents. For example, all developers +can be placed in one group, and all qa people placed in another, like so: + + [user_groups] + devs = bob mike susan frank + qa = denise tod + +repo_groups provide a similar functionality for repo names. Here, especially +for repositories placed in a tree of subdirectories, the wildcard character (the +asterisk, '*') can be used. In the example below, all repositories in the dev +subdirectory are assigned to the group 'dev_repos', all repos in the qa +subdirectory are assigned to the group 'qa_repos', and a select set of +repositories are placed in the 'special' group: + + [repo_groups] + dev_repos = dev/* + qa_repos = qa/* + special = git-utils.git deploy-utils.git repo_shell.git + +There should be one repo section for every repository or repository group to +which users and user groups will be assigned permission. The format of the +section is: + + [repo , but it may contain the wildcard +character. The first example assigns permissions to repos in the dev_repos +group,where users in the devs group have read-write access and all other users +get read access. Except for mary, which has for some reason been denied all +access. Note that the wildcard may also be used when specifying the userid. + + [repo dev_repos] + mary = + devs = rw + * = r + + += The first match is the match used + +The acl file is scanned until a match for the requesting user and repo are +found. Therefore, rules that are more specific should always be listed first. +for example, if this repo rule were the first one listed, then no one would have +access to any repository: + + [repo *] + * = + +Similarly, the following repo section prevents all user access to the bash.git +repository because the first user permissions assignment wildcard pattern will +match any user, rendering the user permissions assignments after it +irrevelevant: + + [repo bash.git] + * = + dvs = rw + qa = r + + += Wildcards patterns are limited + +1. The wildcard character can only be used at the end of a string, to denote + that the rest of the string may contain zero or more valid characters. To + this end the following wildcard patterns are valid: + + * (means all) + st* (means all tokens starting with st) + + while these tokens are invalid: + + *.git + mirrors/tinyos*.git + */mirrors/* + +2. Wildcard patterns are only valid in certain elements of the configuration + file. + + - As a token on the right hand side of a group assignment. For example: + + [user_groups] + group = * + + [repo_groups] + group = mirrors/* + + - As the token defining in a repo section. For example: + + [repo qa/*] + + - As the left hand side of a user permissions assignment within a repo + section. For example: + + [repo nesc.git] + bill = rw + * = r + + [repo repo_shell.git] + a* = rw + b* = r + * = + + Note that while the last example above is valid, it seems an unlikely use + case where one would want to define access permissions to a repsitory based + upo the first letter of the username.