mercurial-server: comparison doc/manual.docbook

equal deleted inserted replaced

-:aa57f48c7585
+:45dac87ae794
 <title>Adding other users</title>
 <para>
 At this stage, no-one but you has any access to any repositories you
 create on this system. In order to give anyone else access, you'll need a
 copy of their SSH public key; we'll assume you have that key in
-<filename>~/sam-key.pub</filename>.  To manage access, you make changes to the special <literal>hgadmin</literal> repository.
+<filename>~/sam-key.pub</filename>.  To manage access, you make changes to the special <filename
+class='directory'>hgadmin</filename> repository.
 </para>
 <screen><computeroutput>jay@my-workstation:~$ </computeroutput><userinput>hg clone ssh://hg@repository-host/hgadmin</userinput>
 <computeroutput>destination directory: hgadmin
 no changes found
 updating working directory
 jay@my-workstation:~/hgadmin$ </computeroutput></screen>
 <para>
 Sam can now read and write to your
 <literal>ssh://hg@repository-host/repository/name</literal> repository.
 Most other changes to access control can be made simply by making and
-pushing changes to <literal>hgadmin</literal>, and you can use Mercurial to
+pushing changes to <filename
+class='directory'>hgadmin</filename>, and you can use Mercurial to
 cooperate with other root users in the normal way.
 </para>
 <para>
 If you prefer, you could give them access by
 logging into <systemitem class="systemname">repository-host</systemitem>,
 putting the key in the right place under <filename
 class='directory'>/etc/mercurial-server/keys</filename>, and re-running
 <userinput>sudo -u hg /usr/share/mercurial-server/refresh-auth</userinput>.
-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.
+However, using <filename
+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.
 </para>
 </section>
 </section>
 <section>
 <title>Access control</title>
 <para>
 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.
 </para>
 <para>
-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.
+Root users can edit <filename
+class='directory'>hgadmin</filename>, create new repositories and read and write to existing ones.  Normal users cannot access <filename
+class='directory'>hgadmin</filename> or create new repositories, but they can read and write to any other repository.
 </para>
 <section>
 <title>Using access.conf</title>
 <para>
-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
+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
-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
+class='directory'>widget</filename> repository, but no other.  We first copy Pat's SSH public key into the <filename
+class='directory'>keys/pat</filename> directory in <filename
+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
 class='directory'>keys/root</filename> or <filename
-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>
+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
+class='directory'>hgadmin</filename> called <filename>access.conf</filename>, with the following contents:</para>
 <programlisting># Give Pat access to the "widget" repository
 write repo=widget user=pat
 </programlisting>
 <para>
-Pat will have read and write access to the <literal>widget</literal> repository as soon as we add, commit, and push these files.
+Pat will have read and write access to the <filename
+class='directory'>widget</filename> repository as soon as we add, commit, and push these files.
 </para>
 <para>
 Each line of <filename>access.conf</filename> has the following syntax:
 </para>
 <programlisting><replaceable>rule</replaceable> <replaceable>condition</replaceable> <replaceable>condition...</replaceable>
 <code>projects/**</code> matches both.
 </para>
 <para>
 When considering a request, mercurial-server steps through all the rules in
 <filename>/etc/mercurial-server/access.conf</filename> and then all the
-rules in <filename>access.conf</filename> in <literal>hgadmin</literal>
+rules in <filename>access.conf</filename> in <filename
+class='directory'>hgadmin</filename>
 looking for a rule which matches on every condition. The first match
 determines whether the request will be allowed; if there is no match in
 either file, the request will be denied.
 </para>
 <para>
 deny repo=hgadmin
 write user=users/**
 </programlisting>
 <para>
 These rules ensure that root users can do any operation on any repository,
-that no other users can access the <literal>hgadmin</literal> repository,
+that no other users can access the <filename
+class='directory'>hgadmin</filename> repository,
 and that those with keys in <filename
 class='directory'>keys/users</filename> can read or write to any repository
 but not create repositories.  Some examples of how these rules work:
 </para>
 <itemizedlist>
 </section>
 <section>
 <title>/etc/mercurial-server and hgadmin</title>
 <para>
 mercurial-server consults two distinct locations to collect information about what to allow: <filename
-class='directory'>/etc/mercurial-server</filename> and its own <literal>hgadmin</literal> repository.  This is useful for several reasons:
+class='directory'>/etc/mercurial-server</filename> and its own <filename
+class='directory'>hgadmin</filename> repository.  This is useful for several reasons:
 </para>
 <itemizedlist>
 <listitem>
 Some users may not need the convenience of access control via mercurial; for these users updating <filename
 class='directory'>/etc/mercurial-server</filename> may offer a simpler route.
 <filename class='directory'>/etc/mercurial-server</filename> is suitable
 for management with tools such as <link
 xlink:href="http://reductivelabs.com/products/puppet">Puppet</link>
 </listitem>
 <listitem>
-If a change to <literal>hgadmin</literal> leaves you "locked out", <filename
+If a change to <filename
+class='directory'>hgadmin</filename> leaves you "locked out", <filename
 class='directory'>/etc/mercurial-server</filename> allows you a way back in.
 </listitem>
 <listitem>
 At install time, all users are "locked out", and so some mechanism to allow some users in is needed.
 </listitem>
 </itemizedlist>
 <para>
-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.
+Rules in <filename>/etc/mercurial-server/access.conf</filename> are checked before those in <filename
+class='directory'>hgadmin</filename>, and keys in <filename class='directory'>/etc/mercurial-server/keys</filename> will be present no matter how <filename
+class='directory'>hgadmin</filename> changes.
 </para>
 <para>
 We anticipate that once mercurial-server is successfully installed and
-working you will usually want to use <literal>hgadmin</literal> for most
+working you will usually want to use <filename
+class='directory'>hgadmin</filename> for most
 access control tasks. Once you have the right keys and
-<filename>access.conf</filename> set up in <literal>hgadmin</literal>, you
+<filename>access.conf</filename> set up in <filename
+class='directory'>hgadmin</filename>, you
 can delete <filename>/etc/mercurial-server/access.conf</filename> and all
 of <filename class='directory'>/etc/mercurial-server/keys</filename>,
-turning control entirely over to <literal>hgadmin</literal>.
+turning control entirely over to <filename
+class='directory'>hgadmin</filename>.
 </para>
 <para>
 <filename>/etc/mercurial-server/remote-hgrc</filename> is in the
 <systemitem>HGRCPATH</systemitem> for all remote access to mercurial-server
 repositories. This file contains the hooks that mercurial-server uses for
 </para>
 <para>
 <command>refresh-auth</command> recurses through the <filename
 class='directory'>/etc/mercurial-server/keys</filename> and the <filename
 class='directory'>keys</filename> directory in the
-<literal>hgadmin</literal> repository, creating an entry in
+<filename
+class='directory'>hgadmin</filename> repository, creating an entry in
 <filename>~hg/.ssh/authorized_keys</filename> for each one. This is redone
-automatically whenever a change is pushed to <literal>hgadmin</literal>.
+automatically whenever a change is pushed to <filename
+class='directory'>hgadmin</filename>.
 </para>
 </section>
 <section>
 <title>Security</title>
 <para>

changeset 154	45dac87ae794
parent 153	aa57f48c7585
child 155	3bff97f72a33