10 |
10 |
11 WHAT IT GIVES YOU |
11 WHAT IT GIVES YOU |
12 |
12 |
13 These tools make it easier to provide a centralized repository host |
13 These tools make it easier to provide a centralized repository host |
14 with read/write access to many repositories for many developers. |
14 with read/write access to many repositories for many developers. |
15 Access control is managed with a special repository on the server |
15 |
16 called "hgadmin"; pushes to this repository immediately change the |
16 All of the repositories controlled by these tools are owned by a single user |
17 rules that are in effect. |
17 (the "hg" user in what follows), but many remote users can act on them, and |
18 |
18 different users can have different permissions. We don't use file permissions to |
19 Inside "hgadmin" is a "keys" directory containing the SSH keys of all |
19 achieve that - instead, developers log in as the "hg" user when they connect to |
20 developers who have access, and a file "hg-ssh-access.conf" which |
20 the repository host using ssh, using ssh URLs of the form |
21 gives a set of rules defining who can do what to what. |
21 "ssh://hg@repository-host/repository-name". A restricted shell prevents them |
22 |
22 from using this access for unauthorized purposes. Developers are authenticated |
23 All of the repositories controlled by these tools are owned by a |
23 only using SSH keys; no other form of authentication is supported. |
24 single user (the "hg" user in what follows), but many remote users can |
24 |
25 act on them. We don't use file permissions to achieve that - instead, |
25 To give a user access to the repository, place their key in an |
26 developers log in as the "hg" user when they connect to the repository |
26 appropriately-named subdirectory of "/etc/mercurial-server/keys" and run |
27 host using ssh, using ssh URLs of the form |
27 "/etc/mercurial-server/refresh-auth". You can then control what access they have |
28 "ssh://hg@repository-host/repository-name". A restricted shell |
28 to what repositories by editing the control file |
29 prevents them from using this access for unauthorized purposes. |
29 "/etc/mercurial-server/access.conf", which can match the names of these keys |
30 Developers are authenticated only using SSH keys; no other form of |
30 against a glob pattern. |
31 authentication is supported. |
31 |
|
32 For convenient remote control of access, you can instead (if you have the |
|
33 privileges) make changes to a special repository called "hgadmin", which |
|
34 contains its own "access.conf" file and "keys" directory. Changes pushed to this |
|
35 repository take effect immediately. The two "access.conf" files are |
|
36 concatenated, and the keys directories merged. |
32 |
37 |
33 QUICK START |
38 QUICK START |
34 |
39 |
35 You will need |
40 You and all developers using this system will need an SSH public key, and will |
36 |
41 almost certainly want to be running ssh-agent (or its equivalent, eg Pageant |
37 - "sudo" installed |
42 under Windows). If you're not familiar with ssh-agent, you should learn about |
38 - "sudo" root privileges |
43 that before using this. |
39 - an ssh-key set up with ssh-agent |
44 |
40 |
45 In what follows, certain operations (eg installing mercurial-server itself) have |
41 Ensure there is no user called "hg" on the repository host, and run |
46 to be done on the repository server (which we call "repository-host"), but any |
42 "./install" to create them. You are now the sole user able to change |
47 operation that involves checking in or out of Mercurial can be done wherever is |
43 and create repositories on this repository host. To give access to |
48 most convenient to you; the most usual arrangment would be that you'd do these |
44 others, check out hgadmin - as yourself, and on whichever host is most |
49 things at the machine you sit at, and on which you run ssh-agent, which is what |
45 convenient, but using the ssh-key with which you set up the |
50 authenticates you when you talk to the repository server. |
46 repository: |
51 |
47 |
52 Ensure there is no user called "hg" on the repository host, and run "./install". |
48 mkdir ~/hg |
53 This installs the mercurial-server files and control files, and creates and sets |
49 cd ~/hg |
54 up the "hg" user. |
50 hg clone ssh://hg@repository-host/hgadmin |
55 |
51 cd hgadmin |
56 Place your SSH public key in the directory "/etc/mercurial-server/keys/root". I |
52 |
57 suggest creating yourself a directory and naming the key after your hostname (ie |
53 You can now add other users by putting their keys in an appropriate |
58 the file is called something like |
54 subdirectory of the "keys" directory, and control their access by |
59 "/etc/mercurial-server/keys/root/yourname/yourhostname") so that you can easily |
55 editing hg-ssh-access.conf. Changes will take effect as soon as you |
60 manage users who have a different key on each host they use. Then run |
56 push them to "ssh://hg@repository-host/hgadmin". |
61 "/etc/mercurial-server/refresh-auth". |
57 |
62 |
58 Users authorized to do so can now also create new repositories on this |
63 The repository is now ready to use, and you are now the sole user able to change |
59 host with "clone": |
64 and create repositories on this repository host. |
60 |
65 |
61 hg clone . ssh://hg@repository-host/my-project-name |
66 CREATING REPOSITORIES |
62 |
67 |
63 HG-SSH-ACCESS.CONF |
68 To create a new repository, you clone a local repository onto the remote server. |
64 |
69 So if you want a new empty repository called "myproject", you can do (as |
65 Each line of hg-ssh-access.conf has the following syntax: |
70 yourself): |
|
71 |
|
72 hg init myproject |
|
73 hg clone myproject ssh://hg@repository-host/myproject |
|
74 |
|
75 ADDING OTHER USERS |
|
76 |
|
77 Because your key is in the "keys/root" subdirectory, you have the equivalent of |
|
78 "root privileges" over mercurial-server (not the whole computer, just |
|
79 mercurial-server). You can add other root users by putting their keys next to |
|
80 yours, or you can make less privileged users by putting their keys in the |
|
81 "keys/users" subdirectory - these users will be able to read and write to any |
|
82 repository (except one - see below) but will not be able to create new |
|
83 repositories. As always, when you change "/etc/mercurial-server/keys" you need |
|
84 to re-run "/etc/mercurial-server/refresh-auth". |
|
85 |
|
86 USING HGADMIN |
|
87 |
|
88 It can be inconvenient to log on to the repository server, become root, copy |
|
89 keys around, and run "refresh-auth" every time you want to change user |
|
90 privileges. This is where mercurial-server shines :-) Suppose you have another |
|
91 user's SSH public key in the file "/tmp/theirkey" (on the machine you sit at, |
|
92 not necessarily the repository server) and you want to give them user-level |
|
93 access to the repository server. Run these commands: |
|
94 |
|
95 hg clone ssh://hg@repository-server/hgadmin |
|
96 cd hgadmin |
|
97 mkdir keys/user/thatuser |
|
98 cp /tmp/theirkey keys/user/thatuser/theirhostname |
|
99 hg add |
|
100 hg commit -m "Added key for thatuser" |
|
101 hg push |
|
102 |
|
103 In other words, hgadmin is a version controlled version of |
|
104 "/etc/mercurial-server/keys", and changes to it take effect immediately. Only |
|
105 "keys/root" users can act on "hgadmin" - those with keys in "keys/users" are |
|
106 locked out. Multiple admins can use Mercurial's version control to cooperate on |
|
107 controlling access to the repository server in a natural way. You can also add |
|
108 "root" users by putting their key in the "keys/root" directory in just the same |
|
109 way - these users will now be able to control hgadmin and create new |
|
110 repositories just as you can. |
|
111 |
|
112 ACCESS.CONF |
|
113 |
|
114 Out of the box, there are just two kinds of users: the ones with keys in |
|
115 "keys/root" and those in "keys/users". However, you can change this by editing |
|
116 "access.conf". There are two "access.conf" files, one in "/etc/mercurial-server" |
|
117 and one in "hgadmin"; the two are simply concatenated before being read. |
|
118 |
|
119 Each line of access.conf has the following syntax: |
66 |
120 |
67 <rule> <condition> <condition> ... |
121 <rule> <condition> <condition> ... |
68 |
122 |
69 Rule is one of |
123 Rule is one of |
70 |
124 |
161 |
221 |
162 Finally, a hook in an extension is run for each changeset that is |
222 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 |
223 remotely committed, which uses the rules file to determine whether to |
164 allow the changeset. |
224 allow the changeset. |
165 |
225 |
166 LOCKING YOURSELF OUT |
226 LOCKED OUT? |
167 |
227 |
168 If you find yourself "locked out" - that is, that you no longer have |
228 Once you're working with "hgadmin", it can be convenient to remove all the keys |
169 the permissions needed in hgadmin - you can break back in again if |
229 in "/etc/mercurial-server/keys" and all the entries in |
170 you're able to become the "hg" user on the repository host. Once you |
230 "/etc/mercurial-server/access.conf" and use hgadmin to control everything. If |
171 are that user, delete ~hg/.ssh/authorized_keys (to stop any user who |
231 you find yourself locked out, you can get back in again by restoring some of the |
172 might have access but shouldn't from using the repository while you |
232 entries you removed from these files - remember, |
173 fix things). Then go into ~hg/repos/hgadmin, do an "hg update", edit |
233 "/etc/mercurial-server/access.conf" takes precedence over the "access.conf" in |
174 things to your satisfaction, and commit the change. Finally, run |
234 "hgadmin". |
175 |
|
176 ~hg/admin/mercurial-server/refresh-auth ~hg/.ssh/authorized_keys ./hg-ssh-wrapper |
|
177 |
|
178 to regenerate ~hg/.ssh/authorized_keys. |
|
179 |
235 |
180 THANKS |
236 THANKS |
181 |
237 |
182 Thanks for reading this far. If you use mercurial-server, please tell |
238 Thanks for reading this far. If you use mercurial-server, please tell |
183 me about it. |
239 me about it. |