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. |