X-Git-Url: https://oss.titaniummirror.com/gitweb?a=blobdiff_plain;f=README;h=33cb71c7e92ebb2ea1f7497862962bce8a5487db;hb=d044b519a1b2faebcd1654c8fb0df4741f241dfa;hp=d6cabcb8e32a9cec186f5c1c530ce6ca691d5d68;hpb=d58942318a1b66039b1e5f1b9ed5a108fc7b1107;p=repo_shell.git diff --git a/README b/README index d6cabcb..33cb71c 100644 --- a/README +++ b/README @@ -1,29 +1,174 @@ -Build ------ += About repo_shell -make repo_shell +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. -Install -------- +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. -sudo cp repo_shell /usr/local/bin/ +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. -Configure ---------- += Acquire, build and install -cat <+EOF+ > repo_shell.cfg -[core] -owner=repo -git_root=/var/lib/git -svn_root=/var/lib/svn/repositories -+EOF+ -sudo mv repo_shell.cfg /etc/ + git clone git://oss.titaniummirror.com/repo_shell.git + cd repo_shell + make + sudo make install -Notes ------ -The inih library comes from: -URL: http://inih.googlecode.com/svn/trunk -Repository Root: http://inih.googlecode.com/svn -Repository UUID: f5d6dc10-6d35-11de-b131-07d8e4d3762e -Revision: 22 +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. + += 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.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. + +- Subversion's authz file + http://svnbook.red-bean.com/en/1.7/svn.serverconfig.pathbasedauthz.html