4 ssh-based Hg repositories

     4 ssh-based Mercurial repositories

     6 Paul Crowley, paul@lshift.net, 2008-04-15

     6 Paul Crowley, paul@lshift.net, 2008

    11 INSTRUCTIONS FOR USE:

    11 WHAT IT GIVES YOU

    12 

    13 You maintain a local Mercurial repository called "hgadmin" which

    14 controls what access is allowed to whom.  When you push a new version

    15 of this repository to the repository host, changes take effect

    16 immediately, so familiar "hg" commands are all that are needed to

    17 maintain it.  A "keys" directory contains the SSH keys of all the

    18 developers who have access, while "hg-ssh-access.conf" gives a set of

    19 rules defining who can do what to what.

    20 

    21 HOW IT WORKS

    22 

    23 The repository is owned by a single user (the "hg" user in what

    24 follows), but many remote users can act on it.  We don't use file

    25 permissions to achieve that - instead, developers log in as the "hg"

    26 user when they connect to the repository host using ssh, using ssh

    27 URLs of the form "ssh://hg@repository-host/repository-name".  A

    28 restricted shell prevents them from using this access for unauthorized

    29 purposes.

    30 

    31 Developers are authenticated only using SSH keys; no other form of

    32 authentication is supported.  When a developer attempts to connect to

    33 a repository via ssh, the SSH daemon searches for a match for that

    34 user's key in ~hg/.ssh/authorized_keys.  If the developer is

    35 authorised to connect to the repository they will have an entry in

    36 this file.  The entry includes a "command" prefix which specifies that

    37 the restricted shell should be used; this shell is passed an argument

    38 identifying the developer.  The shell parses the command the developer

    39 is trying to execute, and consults a rules file to see if that

    40 developer is allowed to perform that action on that repository.  The

    41 bulk of the work of the restricted shell is done by the Python program

    42 "hg-ssh", but the shell script "hg-ssh-wrapper" sets up some

    43 configuration so that you can change it to suit your local installation.

    44 

    45 The file ~hg/.ssh/authorized_keys is generated by "refresh-auth",

    46 which recurses through a directory of files containing SSH keys and

    47 generates an entry in authorized_keys for each one, using the name of

    48 the key file as the identifier for the developer.  These keys will

    49 live in the "keys" subdirectory of a repository, "hgadmin".  A hook in

    50 this repository re-runs "refresh-auth" on the most recent version

    51 after every push.

    52 

    53 INSTRUCTIONS FOR USE

    28 Now create a basic access control setup.  

    70 Issue these commands to become the hg user and set up the repository.

    29 

    71 Use your own name in place of "myname".

    30    cd

    31    mkdir hg

    32    cd hg

    33    hg clone ssh://hg.opensource.lshift.net/hg-admin-tools hg-admin-tools

    34    mkdir -p hgadmin/keys/admin

    35    cd hgadmin

    36    ssh-add -L > keys/admin/myname

    37    echo "init admin/* *" > hg-ssh-access.conf

    38    hg init .

    39    hg add

    40    hg commit -m "Initial configuration"

    41 

    42 You can use whatever you want in place of "myname" and indeed "admin".

    43 The files in ~/hg must be readable by the hg user.  Issue these

    44 commands to become the hg user and set up the repository

    48    mkdir admin repos

    75    mkdir -p admin repos/hgadmin/keys/admin

    49    hg clone ~/hg/hg-admin-tools admin/hg-admin-tools

    76    cd admin

    50    hg clone ~/hg/hgadmin repos/hgadmin

    77    tar xvzf /tmp/hg-admin-tools.tar.gz

    51    cp admin/hg-admin-tools/hgadmin-hgrc repos/hgadmin/.hg/hgrc

    78    mv hg-admin-tools* hg-admin-tools

    52    cp admin/hg-admin-tools/hg-ssh-wrapper hg-ssh-wrapper

    79    cp hg-admin-tools/hg-ssh-wrapper ~

    53    cd repos/hgadmin

    80    cd ../repos/hgadmin

    81    hg init .

    82    echo "init admin/* *" > hg-ssh-access.conf

    83    cp /tmp/my-ssh-public-key keys/admin/myname

    84    cp ~/admin/hg-admin-tools/hgadmin-hgrc .hg/hgrc

    55     exit

    86    exit

    57 You should now have SSH access to this repository and full control,

    88 You should now have SSH access to this repository and full control.

    58 which you can test like so:

    89 To administer these controls (and test your access), check out hgadmin:

    60    cd ~/hg/hgadmin

    91    mkdir ~/hg

    61    echo "[paths]" >> .hg/hgrc

    92    cd ~/hg

    62    echo "default = ssh://hg@localhost/hgadmin"  >> .hg/hgrc

    93    hg clone ssh://hg@repository-host-name/hgadmin

    63    hg pull

    94    cd hgadmin

    64    hg push

    65 

    66 These attempts to push and pull should report no new changes but

    67 otherwise work.