X-Git-Url: https://oss.titaniummirror.com/gitweb?a=blobdiff_plain;f=README;h=6eb4764351d09b927d6f3d024a861526ee8c0ab5;hb=HEAD;hp=f46578e0c1f145287e68f72226861cc9b8d6ca24;hpb=48bb944690580b2a89405cca9a2feb1d8c053308;p=repo_shell.git diff --git a/README b/README index f46578e..6eb4764 100644 --- a/README +++ b/README @@ -1,89 +1,261 @@ -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 + 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. + +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. + +== allowed_interactive and sudo == + +For users that use repo_shell as a login shell and that also need to run +commands via sudo as other users, those other users must also be listed in the +allowed_interactive user list. Otherwise, sudo functionality is effectively +disabled for such users. + += Create owner and paths + +In accordance with the settings in /etc/repo_shell.conf: + + sudo adduser --system --group --home /var/lib/svn --shell /bin/false + sudo chsh -s /bin/bash # a shell is needed for 'sudo -iu' + sudo install -d -o -g -m 0750 /.. + sudo install -d -o -g -m 0750 + sudo install -d -o -g -m 0750 + += Configure subversion repository ACLs + +Subversion repositories created with the svncreate command have their +conf/svnserve.conf as a symbolic link pointing to the global +{svn_root}/../svnserve.conf file, which then references internally the global +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 + +A simple and secure svnserve.conf file: + + [general] + anon-access = none + auth-access = write + authz-db = /var/lib/svn/authz.conf + +A simple and secure authz.conf file: + + [groups] + devs = user1, user2, user3 + + [/] # All repositories, all paths + @devs = rw + * = + +For path-based controls, consider using the pre-commit hook that uses +svnperms.py. The ability to prevent update of tags, which my definition is +almost always an accident, is itself worth the price of admission. + += Configure git repository ACLs + +Git repository access control is managed by the git acl file, located at +{git_root}/.gitacls (git_root is defined in /etc/repo_shell.conf). 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. +A simple .gitacls might look like: + + [user_groups] + devs = user1 user2 user3 + + [repo *] + devs = rw + * = + += 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 -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. +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. - make repo_shell += Create a git repository -To install repo_shell: +gitcreate is a helper script installed by make install. To create a new git +repository, simply type: - 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 + sudo -u repo gitcreate ["Short description"] -The /etc/repo_shell.cfg configuration file is straightforward: +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: - [core] - owner=repo - git_root=/var/lib/git - svn_root=/var/lib/svn/repositories + sudo -u repo gitcreate mirrors/tinyos/tinyos-main.git -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. +If a subdirectory path being requested doesn't already exist, the script will +ask the operator if it is OK to create it. To automatically create non-existent +subdirectory paths, add the -y option: - 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 + sudo -u repo gitcreate -y mirrors/tinyos/tinyos-main.git -Repositories should be owned by the user identified in the owner field. For -example: +If the optional extra argument is provided, it will be used to populate the +description file of the new repository. Because the script takes only one +argument for this purpose, enclose the description in double quotes. - 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 gitweb + +The following steps can allow gitweb to filter the available repositories +according to the authenticated user and the contents of the .gitacl file. + +- The web server must require authorization and a valid user for URI's starting + with /gitweb. Recommend using a PAM module, since repo_shell also works of + the system user credentials. +- The web server needs to pass the REMOTE_USER environment variable to + gitweb.cgi. +- The contents of the file gitweb.conf.addon must be added to the server's + gitweb.conf file, usually found in /etc. + +The contents of gitweb.conf.addon essentially define an $export_auth_hook that +uses repo_shell's test mode to validate read access for the web server +authenticated user for each repository gitweb can see. + += 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. + += Allow other users to create repositories + +With the following configuration, other users could be configured to run the +`gitcreate` command using sudo. + +First, run `visudo` as root to edit the `/etc/sudoers` file. These entries +should appear before less specific rules. The Runas_Alias REPOUSER should be +set to the value of the `owner` variable defined in `/etc/repo_shell.conf`. + + # Allow select users to run gitcreate + User_Alias REPOCREATORS = user1, user2, user3 + Runas_Alias REPOUSER = repo + REPOCREATORS ALL = (REPOUSER) NOPASSWD: /usr/local/bin/gitcreate + +Now any users listed in the User_Alias REPOCREATORS can run the gitcreate +command. The command would be invoked as follows: + + ssh + sudo -u repo gitcreate path/to/newrepo.git + +Note that as of right now, repo_shell cannot be used to run this command in a +single ssh invocation, such as: + + ssh sudo gitcreate path/to/newrepo.git + +This is because repo_shell does not implement a full tty needed by sudo if it +must ask the user for a password to authenticate the action. + += 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 are envisioned to be incorporated into repo_shell. They -aren't at this time, and any developer has read-write access to any git -repository. +- Subversion's authz file + http://svnbook.red-bean.com/en/1.7/svn.serverconfig.pathbasedauthz.html