97 <title>Adding other users</title> |
97 <title>Adding other users</title> |
98 <para> |
98 <para> |
99 At this stage, no-one but you has any access to any repositories you |
99 At this stage, no-one but you has any access to any repositories you |
100 create on this system. In order to give anyone else access, you'll need a |
100 create on this system. In order to give anyone else access, you'll need a |
101 copy of their SSH public key; we'll assume you have that key in |
101 copy of their SSH public key; we'll assume you have that key in |
102 <filename>~/sam-key.pub</filename>. To manage access, you make changes to the special <literal>hgadmin</literal> repository. |
102 <filename>~/sam-key.pub</filename>. To manage access, you make changes to the special <filename |
|
103 class='directory'>hgadmin</filename> repository. |
103 </para> |
104 </para> |
104 <screen><computeroutput>jay@my-workstation:~$ </computeroutput><userinput>hg clone ssh://hg@repository-host/hgadmin</userinput> |
105 <screen><computeroutput>jay@my-workstation:~$ </computeroutput><userinput>hg clone ssh://hg@repository-host/hgadmin</userinput> |
105 <computeroutput>destination directory: hgadmin |
106 <computeroutput>destination directory: hgadmin |
106 no changes found |
107 no changes found |
107 updating working directory |
108 updating working directory |
122 jay@my-workstation:~/hgadmin$ </computeroutput></screen> |
123 jay@my-workstation:~/hgadmin$ </computeroutput></screen> |
123 <para> |
124 <para> |
124 Sam can now read and write to your |
125 Sam can now read and write to your |
125 <literal>ssh://hg@repository-host/repository/name</literal> repository. |
126 <literal>ssh://hg@repository-host/repository/name</literal> repository. |
126 Most other changes to access control can be made simply by making and |
127 Most other changes to access control can be made simply by making and |
127 pushing changes to <literal>hgadmin</literal>, and you can use Mercurial to |
128 pushing changes to <filename |
|
129 class='directory'>hgadmin</filename>, and you can use Mercurial to |
128 cooperate with other root users in the normal way. |
130 cooperate with other root users in the normal way. |
129 </para> |
131 </para> |
130 <para> |
132 <para> |
131 If you prefer, you could give them access by |
133 If you prefer, you could give them access by |
132 logging into <systemitem class="systemname">repository-host</systemitem>, |
134 logging into <systemitem class="systemname">repository-host</systemitem>, |
133 putting the key in the right place under <filename |
135 putting the key in the right place under <filename |
134 class='directory'>/etc/mercurial-server/keys</filename>, and re-running |
136 class='directory'>/etc/mercurial-server/keys</filename>, and re-running |
135 <userinput>sudo -u hg /usr/share/mercurial-server/refresh-auth</userinput>. |
137 <userinput>sudo -u hg /usr/share/mercurial-server/refresh-auth</userinput>. |
136 However, using <literal>hgadmin</literal> is usually more convenient if you need to make more than a very few changes; it also makes it easier to share administration with others and provides a log of all changes. |
138 However, using <filename |
|
139 class='directory'>hgadmin</filename> is usually more convenient if you need to make more than a very few changes; it also makes it easier to share administration with others and provides a log of all changes. |
137 </para> |
140 </para> |
138 </section> |
141 </section> |
139 </section> |
142 </section> |
140 <section> |
143 <section> |
141 <title>Access control</title> |
144 <title>Access control</title> |
142 <para> |
145 <para> |
143 Out of the box, mercurial-server supports two kinds of users: "root" users and normal users. If you followed the steps above, you are a "root" user because your key is under <filename class='directory'>keys/root</filename>, while the other user you gave access to is a normal user since their key is under <filename class='directory'>keys/users</filename>. Keys that are not in either of these directories will by default have no access to anything. |
146 Out of the box, mercurial-server supports two kinds of users: "root" users and normal users. If you followed the steps above, you are a "root" user because your key is under <filename class='directory'>keys/root</filename>, while the other user you gave access to is a normal user since their key is under <filename class='directory'>keys/users</filename>. Keys that are not in either of these directories will by default have no access to anything. |
144 </para> |
147 </para> |
145 <para> |
148 <para> |
146 Root users can edit <literal>hgadmin</literal>, create new repositories and read and write to existing ones. Normal users cannot access <literal>hgadmin</literal> or create new repositories, but they can read and write to any other repository. |
149 Root users can edit <filename |
|
150 class='directory'>hgadmin</filename>, create new repositories and read and write to existing ones. Normal users cannot access <filename |
|
151 class='directory'>hgadmin</filename> or create new repositories, but they can read and write to any other repository. |
147 </para> |
152 </para> |
148 <section> |
153 <section> |
149 <title>Using access.conf</title> |
154 <title>Using access.conf</title> |
150 <para> |
155 <para> |
151 mercurial-server offers much more fine-grained access control than this division into two classes of users. Let's suppose you wish to give Pat access to the <literal>widget</literal> repository, but no other. We first copy Pat's SSH public key into the <filename |
156 mercurial-server offers much more fine-grained access control than this division into two classes of users. Let's suppose you wish to give Pat access to the <filename |
152 class='directory'>keys/pat</filename> directory in <literal>hgadmin</literal>. This tells mercurial-server about Pat's key, but gives Pat no access to anything because the key is not under either <filename |
157 class='directory'>widget</filename> repository, but no other. We first copy Pat's SSH public key into the <filename |
|
158 class='directory'>keys/pat</filename> directory in <filename |
|
159 class='directory'>hgadmin</filename>. This tells mercurial-server about Pat's key, but gives Pat no access to anything because the key is not under either <filename |
153 class='directory'>keys/root</filename> or <filename |
160 class='directory'>keys/root</filename> or <filename |
154 class='directory'>keys/users</filename>. To grant this key access, we must give mercurial-server a new access rule, so we create a file in <literal>hgadmin</literal> called <filename>access.conf</filename>, with the following contents:</para> |
161 class='directory'>keys/users</filename>. To grant this key access, we must give mercurial-server a new access rule, so we create a file in <filename |
|
162 class='directory'>hgadmin</filename> called <filename>access.conf</filename>, with the following contents:</para> |
155 <programlisting># Give Pat access to the "widget" repository |
163 <programlisting># Give Pat access to the "widget" repository |
156 write repo=widget user=pat |
164 write repo=widget user=pat |
157 </programlisting> |
165 </programlisting> |
158 <para> |
166 <para> |
159 Pat will have read and write access to the <literal>widget</literal> repository as soon as we add, commit, and push these files. |
167 Pat will have read and write access to the <filename |
|
168 class='directory'>widget</filename> repository as soon as we add, commit, and push these files. |
160 </para> |
169 </para> |
161 <para> |
170 <para> |
162 Each line of <filename>access.conf</filename> has the following syntax: |
171 Each line of <filename>access.conf</filename> has the following syntax: |
163 </para> |
172 </para> |
164 <programlisting><replaceable>rule</replaceable> <replaceable>condition</replaceable> <replaceable>condition...</replaceable> |
173 <programlisting><replaceable>rule</replaceable> <replaceable>condition</replaceable> <replaceable>condition...</replaceable> |
202 <code>projects/**</code> matches both. |
211 <code>projects/**</code> matches both. |
203 </para> |
212 </para> |
204 <para> |
213 <para> |
205 When considering a request, mercurial-server steps through all the rules in |
214 When considering a request, mercurial-server steps through all the rules in |
206 <filename>/etc/mercurial-server/access.conf</filename> and then all the |
215 <filename>/etc/mercurial-server/access.conf</filename> and then all the |
207 rules in <filename>access.conf</filename> in <literal>hgadmin</literal> |
216 rules in <filename>access.conf</filename> in <filename |
|
217 class='directory'>hgadmin</filename> |
208 looking for a rule which matches on every condition. The first match |
218 looking for a rule which matches on every condition. The first match |
209 determines whether the request will be allowed; if there is no match in |
219 determines whether the request will be allowed; if there is no match in |
210 either file, the request will be denied. |
220 either file, the request will be denied. |
211 </para> |
221 </para> |
212 <para> |
222 <para> |
283 <filename class='directory'>/etc/mercurial-server</filename> is suitable |
295 <filename class='directory'>/etc/mercurial-server</filename> is suitable |
284 for management with tools such as <link |
296 for management with tools such as <link |
285 xlink:href="http://reductivelabs.com/products/puppet">Puppet</link> |
297 xlink:href="http://reductivelabs.com/products/puppet">Puppet</link> |
286 </listitem> |
298 </listitem> |
287 <listitem> |
299 <listitem> |
288 If a change to <literal>hgadmin</literal> leaves you "locked out", <filename |
300 If a change to <filename |
|
301 class='directory'>hgadmin</filename> leaves you "locked out", <filename |
289 class='directory'>/etc/mercurial-server</filename> allows you a way back in. |
302 class='directory'>/etc/mercurial-server</filename> allows you a way back in. |
290 </listitem> |
303 </listitem> |
291 <listitem> |
304 <listitem> |
292 At install time, all users are "locked out", and so some mechanism to allow some users in is needed. |
305 At install time, all users are "locked out", and so some mechanism to allow some users in is needed. |
293 </listitem> |
306 </listitem> |
294 </itemizedlist> |
307 </itemizedlist> |
295 <para> |
308 <para> |
296 Rules in <filename>/etc/mercurial-server/access.conf</filename> are checked before those in <literal>hgadmin</literal>, and keys in <filename class='directory'>/etc/mercurial-server/keys</filename> will be present no matter how <literal>hgadmin</literal> changes. |
309 Rules in <filename>/etc/mercurial-server/access.conf</filename> are checked before those in <filename |
|
310 class='directory'>hgadmin</filename>, and keys in <filename class='directory'>/etc/mercurial-server/keys</filename> will be present no matter how <filename |
|
311 class='directory'>hgadmin</filename> changes. |
297 </para> |
312 </para> |
298 <para> |
313 <para> |
299 We anticipate that once mercurial-server is successfully installed and |
314 We anticipate that once mercurial-server is successfully installed and |
300 working you will usually want to use <literal>hgadmin</literal> for most |
315 working you will usually want to use <filename |
|
316 class='directory'>hgadmin</filename> for most |
301 access control tasks. Once you have the right keys and |
317 access control tasks. Once you have the right keys and |
302 <filename>access.conf</filename> set up in <literal>hgadmin</literal>, you |
318 <filename>access.conf</filename> set up in <filename |
|
319 class='directory'>hgadmin</filename>, you |
303 can delete <filename>/etc/mercurial-server/access.conf</filename> and all |
320 can delete <filename>/etc/mercurial-server/access.conf</filename> and all |
304 of <filename class='directory'>/etc/mercurial-server/keys</filename>, |
321 of <filename class='directory'>/etc/mercurial-server/keys</filename>, |
305 turning control entirely over to <literal>hgadmin</literal>. |
322 turning control entirely over to <filename |
|
323 class='directory'>hgadmin</filename>. |
306 </para> |
324 </para> |
307 <para> |
325 <para> |
308 <filename>/etc/mercurial-server/remote-hgrc</filename> is in the |
326 <filename>/etc/mercurial-server/remote-hgrc</filename> is in the |
309 <systemitem>HGRCPATH</systemitem> for all remote access to mercurial-server |
327 <systemitem>HGRCPATH</systemitem> for all remote access to mercurial-server |
310 repositories. This file contains the hooks that mercurial-server uses for |
328 repositories. This file contains the hooks that mercurial-server uses for |