1. Chris Haubner
  2. hgssh3

Overview

hgssh3
-------

A python script to control ssh access to mercurial repositories.

modified from hg-ssh (http://www.selenic.com/repo/hg-stable/raw-file/tip/contrib/hg-ssh)
and hgssh2.py (https://github.com/dengzhp/hgssh2)

See https://bitbucket.org/painfulcranium/hgssh3 for more information.

How to
-------

copy hgssh3.py to your $PATH (e.g./usr/local/bin).

(We assume your user being created is named 'hg')

Create a new user `hg` with home directory `/home/hg`, all your repositories will go here. If 
you want to store your repositories elsewhere, you can do one of the following:

	1. Create your directory structure somewhere on your filesystem and ensure ownership
	   is given to hg user and hg group. Then create a symlink in the user home directory
	   to the top level folder of the repository location.
	   
	2. Use 'cd path/to/toplevel/repodir &&...' in your SSH command before calling this script. For example,
	   if the top level was in /usr/local/repos, create a symlink in /home/hg to /usr/local/repos and update
	   the confuguration file as necessary

Create a config file at `/home/hg/hgssh3.conf`:
    
    [reponame]
    location = repos/reponame
    user1 = read     
    user2 = write    
    
    [reponame2]
    location = repos/reponame2
    user1 = write

Add a new entry to ``/home/hg/.ssh/authorized_keys``
    
    NOTE: USERNAME in this example would be user1 or user2
	
    command="hgssh3.py USERNAME ~/hgssh3.conf",no-port-forwarding,no-X11-forwarding,no-agent-forwarding ssh-rsa your_ssh_rsa_public_key

Create the repositories:

    cd /home/hg/repos && hg init reponame && hg  init reponame2

Now you can access (only) these repositories using your ssh key:

    ssh://hg@example.com/reponame  (readonly to user1, read/write to user2)
    ssh://hg@example.com/reponame2 (read/write to user1only)
    
NOTES:

    If the username provided in authorized_keys does not exist in the ACL file, or if it is set to anything
    other than 'read' or 'write' (even if blank), then the access will be denied.
    *****

    The users defined in the ACL file DO NOT need to exist on the server being accessed. They simply need to match
    the entry that is provided in the command in the authorized_keys file for that user.
    *****

    The actual name of the repository folder in the location DOES NOT need to match the name in the [] section of the ACL file.
    [repo1]
    location=/path/to/repos/anothername
    user1=read
    user2=write

    SSH to run: ssh://hg@example.com/repo1
    *****

    This script allows the use of 'short/friendly' names in access/config:
    Example: ssh://hg@hg.myserver.com/myrepo1
    *****

    This ACL file serves as a mapping from friendly name to actual location. This removes the 
    need to defined multiple repo definitions on the "command" of the ssh key as in hgssh, 
    and also removes the need to redefine repos per user as in hgssh2.py. This configuration 
    allows one definition of the repository and one line per user to deny/grant access. This is very similar
    to how SVN grants access controls.
    *****