README
changeset 12 834426fcbada
parent 10 524b4a45ef0a
child 13 1206ed37090a
equal deleted inserted replaced
11:f3c73c9fc0ff 12:834426fcbada
     1 hg-admin-tools version 0.1
     1 hg-admin-tools version 0.1
     2 
     2 
     3 A set of tools for managing authorization and access control for
     3 A set of tools for managing authorization and access control for
     4 ssh-based Hg repositories
     4 ssh-based Mercurial repositories
     5 
     5 
     6 Paul Crowley, paul@lshift.net, 2008-04-15
     6 Paul Crowley, paul@lshift.net, 2008
     7 
     7 
     8 This software may be used and distributed according to the terms
     8 This software may be used and distributed according to the terms
     9 of the GNU General Public License, incorporated herein by reference.
     9 of the GNU General Public License, incorporated herein by reference.
    10 
    10 
    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
    12 
    54 
    13 This is only one setup - it can be tweaked in many ways, and is as
    55 This is only one setup - it can be tweaked in many ways, and is as
    14 specific as it is only in the interests of brevity.
    56 specific as it is only in the interests of brevity.
    15 
    57 
    16 You, and all users of your Hg repository, will need SSH public key
    58 You, and all users of your Hg repository, will need SSH public key
    23 live.  I used the command
    65 live.  I used the command
    24 
    66 
    25   sudo adduser --system --shell /bin/sh --group --disabled-password \
    67   sudo adduser --system --shell /bin/sh --group --disabled-password \
    26     --gecos "Mercural repository" hg
    68     --gecos "Mercural repository" hg
    27 
    69 
    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
       
    45 
    72 
    46    sudo -u hg -s
    73    sudo -u hg -s
    47    cd ~hg
    74    cd ~hg
    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
    54    ../../admin/hg-admin-tools/refresh-auth
    85    ../../admin/hg-admin-tools/refresh-auth
    55     exit
    86    exit
    56 
    87 
    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:
    59 
    90 
    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.
       
    68 
    95 
    69 You can now add other users by putting their keys in an appropriate
    96 You can now add other users by putting their keys in an appropriate
    70 subdirectory of the "keys" directory, and control their access by
    97 subdirectory of the "keys" directory, and control their access by
    71 editing hg-ssh-access.conf.  Changes will take effect as soon as you
    98 editing hg-ssh-access.conf.  Changes will take effect as soon as you
    72 push them to the remote ssh server.
    99 push them to the remote ssh server.
    81 "repositorypattern" is a pattern matched againt the repository name -
   108 "repositorypattern" is a pattern matched againt the repository name -
    82 so "hgadmin" matches "*".  Only boring characters are allowed in
   109 so "hgadmin" matches "*".  Only boring characters are allowed in
    83 patterns and key and repository names - see the source for details.
   110 patterns and key and repository names - see the source for details.
    84 Blank lines and lines that start with "#" are ignored.
   111 Blank lines and lines that start with "#" are ignored.
    85 
   112 
    86