gitcreate: add option to set description

[repo_shell.git] / README

diff --git a/README b/README
index 8a5db3ab9179952fbd82414d8aadaf7bddc5fa76..6eb4764351d09b927d6f3d024a861526ee8c0ab5 100644 (file)
--- a/README
+++ b/README
@@ -25,15 +25,14 @@ server, only using the git or subversion client side tools.
 Please build from a repository clone, as the make script uses
 'git describe --tags' to generate the resulting executable's version string.
 
 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.cfg
+= Configure /etc/repo_shell.conf

 
 

-The file /etc/repo_shell.cfg must contain certain fields as shown in the example
-below.  The spaces surrounding the equal sign ('=') are optional.
+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
 
     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
     allowed_interactive =
 
 owner is the system account username which will own all repositories, and is


@@ -44,10 +43,6 @@ 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.
 
 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
 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


@@ -55,32 +50,69 @@ 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.
 
 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
 
 = Create owner and paths
 

-In accordance with the contents of /etc/repo_shell.cfg:
+In accordance with the settings in /etc/repo_shell.conf:

 
 

-    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
+    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
 
 = 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:
+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
 
 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
 
 = 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.
+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
 
 
 = Create a subversion repository
 


@@ -98,7 +130,7 @@ file as necesssary to allow access to the new repository.
 gitcreate is a helper script installed by make install.  To create a new git
 repository, simply type:
 
 gitcreate is a helper script installed by make install.  To create a new git
 repository, simply type:
 

-    sudo -u repo gitcreate <repopath>
+    sudo -u repo gitcreate <repopath> ["Short description"]

 
 Git repositories may be placed in subdirectories under {git_root}.  A
 subdirectory may be part of <repopath>.  So, for example, if one wishes to
 
 Git repositories may be placed in subdirectories under {git_root}.  A
 subdirectory may be part of <repopath>.  So, for example, if one wishes to


@@ -107,6 +139,16 @@ the create command would be:
 
     sudo -u repo gitcreate mirrors/tinyos/tinyos-main.git
 
 
     sudo -u repo gitcreate mirrors/tinyos/tinyos-main.git
 

+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:
+
+    sudo -u repo gitcreate -y mirrors/tinyos/tinyos-main.git
+
+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.
+

 = Configuring user accounts
 
 Each user to access repositories via client side tools need an account on the
 = Configuring user accounts
 
 Each user to access repositories via client side tools need an account on the


@@ -134,7 +176,7 @@ both subversion and git repositories.
 
 Users interact with subversion and git repositories using what we somewhat
 incorrectly call access paths.  In both cases, the access path is relative to
 
 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
+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:
 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:


@@ -143,6 +185,23 @@ examples:
     git clone server:my_repository.git
     git clone server:mirrors/tinyos/tinyos-main.git
 
     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
 = Repository access for other applications
 
 Local system applications, such as web based viewers, may gain read-only access


@@ -158,6 +217,34 @@ application use output from the repo_shell -c command to determine access.
 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.
 
 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:
 = References and links
 
 repo_shell owes great thanks to work shared by two other projects: