doc/manual.docbook
changeset 154 45dac87ae794
parent 153 aa57f48c7585
child 155 3bff97f72a33
equal deleted inserted replaced
153:aa57f48c7585 154:45dac87ae794
    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>
   217 deny repo=hgadmin
   227 deny repo=hgadmin
   218 write user=users/**
   228 write user=users/**
   219 </programlisting>
   229 </programlisting>
   220 <para>
   230 <para>
   221 These rules ensure that root users can do any operation on any repository,
   231 These rules ensure that root users can do any operation on any repository,
   222 that no other users can access the <literal>hgadmin</literal> repository,
   232 that no other users can access the <filename
       
   233 class='directory'>hgadmin</filename> repository,
   223 and that those with keys in <filename
   234 and that those with keys in <filename
   224 class='directory'>keys/users</filename> can read or write to any repository
   235 class='directory'>keys/users</filename> can read or write to any repository
   225 but not create repositories.  Some examples of how these rules work:
   236 but not create repositories.  Some examples of how these rules work:
   226 </para>
   237 </para>
   227 <itemizedlist>
   238 <itemizedlist>
   270 </section>
   281 </section>
   271 <section>
   282 <section>
   272 <title>/etc/mercurial-server and hgadmin</title>
   283 <title>/etc/mercurial-server and hgadmin</title>
   273 <para>
   284 <para>
   274 mercurial-server consults two distinct locations to collect information about what to allow: <filename
   285 mercurial-server consults two distinct locations to collect information about what to allow: <filename
   275 class='directory'>/etc/mercurial-server</filename> and its own <literal>hgadmin</literal> repository.  This is useful for several reasons:
   286 class='directory'>/etc/mercurial-server</filename> and its own <filename
       
   287 class='directory'>hgadmin</filename> repository.  This is useful for several reasons:
   276 </para>
   288 </para>
   277 <itemizedlist>
   289 <itemizedlist>
   278 <listitem>
   290 <listitem>
   279 Some users may not need the convenience of access control via mercurial; for these users updating <filename
   291 Some users may not need the convenience of access control via mercurial; for these users updating <filename
   280 class='directory'>/etc/mercurial-server</filename> may offer a simpler route.
   292 class='directory'>/etc/mercurial-server</filename> may offer a simpler route.
   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
   436 </para>
   454 </para>
   437 <para>
   455 <para>
   438 <command>refresh-auth</command> recurses through the <filename
   456 <command>refresh-auth</command> recurses through the <filename
   439 class='directory'>/etc/mercurial-server/keys</filename> and the <filename
   457 class='directory'>/etc/mercurial-server/keys</filename> and the <filename
   440 class='directory'>keys</filename> directory in the
   458 class='directory'>keys</filename> directory in the
   441 <literal>hgadmin</literal> repository, creating an entry in
   459 <filename
       
   460 class='directory'>hgadmin</filename> repository, creating an entry in
   442 <filename>~hg/.ssh/authorized_keys</filename> for each one. This is redone
   461 <filename>~hg/.ssh/authorized_keys</filename> for each one. This is redone
   443 automatically whenever a change is pushed to <literal>hgadmin</literal>.
   462 automatically whenever a change is pushed to <filename
       
   463 class='directory'>hgadmin</filename>.
   444 </para>
   464 </para>
   445 </section>
   465 </section>
   446 <section>
   466 <section>
   447 <title>Security</title>
   467 <title>Security</title>
   448 <para>
   468 <para>