-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 <owner>
+ sudo chsh -s /bin/bash <owner> # a shell is needed for 'sudo -iu'
+ sudo install -d -o <owner> -g <owner> -m 0750 <svn_root>/..
+ sudo install -d -o <owner> -g <owner> -m 0750 <svn_root>
+ sudo install -d -o <owner> -g <owner> -m 0750 <git_root>
+
+= 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 <reponame>
-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 <repopath> ["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 <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:
- [core]
- owner=repo
- git_root=/var/lib/git
- svn_root=/var/lib/svn/repositories
- git_acl_file=/var/lib/git/.gitacls
+ 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:<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
+ 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 <svn_root>/newreponame
- git --git-dir <git_root>/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 <newuser>
- sudo chsh -s /usr/local/bin/repo_shell <developername>
+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 <existinguser>
-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 <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.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 <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.
+
+= 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 <repohost>
+ 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 <repohost> 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
projects / repo_shell.git / blobdiff