18 |
18 |
19 Inside "hgadmin" is a "keys" directory containing the SSH keys of all |
19 Inside "hgadmin" is a "keys" directory containing the SSH keys of all |
20 developers who have access, and a file "hg-ssh-access.conf" which |
20 developers who have access, and a file "hg-ssh-access.conf" which |
21 gives a set of rules defining who can do what to what. |
21 gives a set of rules defining who can do what to what. |
22 |
22 |
23 HOW IT WORKS |
|
24 |
|
25 All of the repositories controlled by these tools are owned by a |
23 All of the repositories controlled by these tools are owned by a |
26 single user (the "hg" user in what follows), but many remote users can |
24 single user (the "hg" user in what follows), but many remote users can |
27 act on them. We don't use file permissions to achieve that - instead, |
25 act on them. We don't use file permissions to achieve that - instead, |
28 developers log in as the "hg" user when they connect to the repository |
26 developers log in as the "hg" user when they connect to the repository |
29 host using ssh, using ssh URLs of the form |
27 host using ssh, using ssh URLs of the form |
30 "ssh://hg@repository-host/repository-name". A restricted shell |
28 "ssh://hg@repository-host/repository-name". A restricted shell |
31 prevents them from using this access for unauthorized purposes. |
29 prevents them from using this access for unauthorized purposes. |
|
30 Developers are authenticated only using SSH keys; no other form of |
|
31 authentication is supported. |
32 |
32 |
33 Developers are authenticated only using SSH keys; no other form of |
33 QUICK START |
34 authentication is supported. When a developer attempts to connect to |
|
35 a repository via ssh, the SSH daemon searches for a match for that |
|
36 user's key in ~hg/.ssh/authorized_keys. If the developer is |
|
37 authorised to connect to the repository they will have an entry in |
|
38 this file. The entry includes a "command" prefix which specifies that |
|
39 the restricted shell should be used; this shell is passed an argument |
|
40 identifying the developer. The shell parses the command the developer |
|
41 is trying to execute, and consults a rules file to see if that |
|
42 developer is allowed to perform that action on that repository. The |
|
43 bulk of the work of the restricted shell is done by the Python program |
|
44 "hg-ssh", but the shell script "hg-ssh-wrapper" sets up some |
|
45 configuration so that you can change it to suit your local |
|
46 installation. |
|
47 |
34 |
48 The file ~hg/.ssh/authorized_keys is generated by "refresh-auth", |
35 You will need |
49 which recurses through a directory of files containing SSH keys and |
|
50 generates an entry in authorized_keys for each one, using the name of |
|
51 the key file as the identifier for the developer. These keys will |
|
52 live in the "keys" subdirectory of a repository called "hgadmin". A |
|
53 hook in this repository re-runs "refresh-auth" on the most recent |
|
54 version after every push. |
|
55 |
36 |
56 Finally, a hook in an extension is run for each changeset that is |
37 - "sudo" installed |
57 remotely committed, which uses the rules file to determine whether to |
38 - "sudo" root privileges |
58 allow the changeset. |
39 - an ssh-key set up with ssh-agent |
59 |
40 |
60 GETTING STARTED |
41 Ensure there is no user called "hg" on the repository host, and run |
61 |
42 "./install" to create them. You are now the sole user able to change |
62 This is only one setup - it can be tweaked in many ways, and is as |
43 and create repositories on this repository host. To give access to |
63 specific as it is only in the interests of brevity. |
44 others, check out hgadmin - as yourself, and on whichever host is most |
64 |
45 convenient, but using the ssh-key with which you set up the |
65 You, and all users of this repository host, will need SSH public key |
46 repository: |
66 authentication set up, preferably working with ssh-agent so you don't |
|
67 have to type in your passphrase all the time. I assume you've done |
|
68 that in what follows, so if you've done something different you'll |
|
69 need to change it appropriately. |
|
70 |
|
71 Issue these commands to get the repository host started. These are |
|
72 written out here rather than encapsulated in a script because many of |
|
73 them may need to be different for your local setup. You will need |
|
74 root access on the repository host, because you need to create a new |
|
75 user. |
|
76 |
|
77 ssh -A repository-host |
|
78 ssh-add -L >> /tmp/my-ssh-public-key |
|
79 sudo adduser --system --shell /bin/sh --group --disabled-password \ |
|
80 --gecos "Mercurial repositories" hg |
|
81 sudo -u hg -H -s |
|
82 cd |
|
83 mkdir -p admin repos/hgadmin/keys/admin .ssh |
|
84 cd admin |
|
85 hg clone http://hg.opensource.lshift.net/hg-admin-tools |
|
86 cp hg-admin-tools/hg-ssh-wrapper hg-admin-tools/remote-hgrc ~ |
|
87 cd ../repos/hgadmin |
|
88 hg init . |
|
89 echo "init user=admin/*" > hg-ssh-access.conf |
|
90 cp /tmp/my-ssh-public-key keys/admin/myname |
|
91 hg add |
|
92 hg commit -m "initial commit" |
|
93 cp ~/admin/hg-admin-tools/hgadmin-hgrc .hg/hgrc |
|
94 ../../admin/hg-admin-tools/refresh-auth ./hg-ssh-wrapper |
|
95 exit |
|
96 exit |
|
97 |
|
98 You are now the sole user able to change and create repositories on |
|
99 this repository host. To administer these controls (and test your |
|
100 access), check out hgadmin: |
|
101 |
47 |
102 mkdir ~/hg |
48 mkdir ~/hg |
103 cd ~/hg |
49 cd ~/hg |
104 hg clone ssh://hg@repository-host/hgadmin |
50 hg clone ssh://hg@repository-host/hgadmin |
105 cd hgadmin |
51 cd hgadmin |
188 |
134 |
189 write user=docs/* branch=docs |
135 write user=docs/* branch=docs |
190 write user=docs/* file=docs/* |
136 write user=docs/* file=docs/* |
191 read user=docs/* |
137 read user=docs/* |
192 |
138 |
|
139 HOW IT WORKS |
|
140 |
|
141 When a developer attempts to connect to a repository via ssh, the SSH |
|
142 daemon searches for a match for that user's key in |
|
143 ~hg/.ssh/authorized_keys. If the developer is authorised to connect |
|
144 to the repository they will have an entry in this file. The entry |
|
145 includes a "command" prefix which specifies that the restricted shell |
|
146 should be used; this shell is passed an argument identifying the |
|
147 developer. The shell parses the command the developer is trying to |
|
148 execute, and consults a rules file to see if that developer is allowed |
|
149 to perform that action on that repository. The bulk of the work of |
|
150 the restricted shell is done by the Python program "hg-ssh", but the |
|
151 shell script "hg-ssh-wrapper" sets up some configuration so that you |
|
152 can change it to suit your local installation. |
|
153 |
|
154 The file ~hg/.ssh/authorized_keys is generated by "refresh-auth", |
|
155 which recurses through a directory of files containing SSH keys and |
|
156 generates an entry in authorized_keys for each one, using the name of |
|
157 the key file as the identifier for the developer. These keys will |
|
158 live in the "keys" subdirectory of a repository called "hgadmin". A |
|
159 hook in this repository re-runs "refresh-auth" on the most recent |
|
160 version after every push. |
|
161 |
|
162 Finally, a hook in an extension is run for each changeset that is |
|
163 remotely committed, which uses the rules file to determine whether to |
|
164 allow the changeset. |
|
165 |
193 LOCKING YOURSELF OUT |
166 LOCKING YOURSELF OUT |
194 |
167 |
195 If you find yourself "locked out" - that is, that you no longer have |
168 If you find yourself "locked out" - that is, that you no longer have |
196 the permissions needed in hgadmin - you can break back in again if |
169 the permissions needed in hgadmin - you can break back in again if |
197 you're able to become the "hg" user on the repository host. Once you |
170 you're able to become the "hg" user on the repository host. Once you |