--- a/doc/manual.docbook Wed Oct 14 16:43:36 2009 +0100
+++ b/doc/manual.docbook Wed Oct 14 17:06:53 2009 +0100
@@ -31,48 +31,28 @@
mercurial-server authenticates users not using passwords but using <link
xlink:href="http://sial.org/howto/openssh/publickey-auth/">SSH public
keys</link>; everyone who wants access to a mercurial-server repository
-will need such a key, so you'll need to familiarize yourself with them
-before proceeding. In combination with <command>ssh-agent</command> (or
+will need such a key. In combination with <command>ssh-agent</command> (or
equivalents such as the Windows program <link
xlink:href="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">Pageant</link>),
this means that users will not need to type in a password to access the
repository.
</para>
<section>
-<title>Creating a repository host</title>
+<title>Installing mercurial-server</title>
<para>
In what follows, we assume that your username is <systemitem
class="username">jay</systemitem>, that you usually sit at a machine called
<systemitem class="systemname">my-workstation</systemitem> and you wish to
install mercurial-server on <systemitem
-class="systemname">repository-host</systemitem>. First, you'll need to
-create an SSH public key if you haven't already. You should consult your
-system documentation on how to do this, but it should look something like
-this.
+class="systemname">repository-host</systemitem>. We assume that you have created your SSH public key, set up your SSH agent with this key, and that this key gives you access to <systemitem
+class="systemname">repository-host</systemitem>. If you're not familiar with SSH public keys, the <link
+xlink:href="http://sial.org/howto/openssh/publickey-auth/">OpenSSH Public
+Key Authentication tutorial</link> may be helpful.
</para>
+<para>First install mercurial-server on <systemitem
+class="systemname">repository-host</systemitem>:</para>
<screen>
-<computeroutput>jay@my-workstation:~$ </computeroutput><userinput>ssh-keygen</userinput>
-<computeroutput>Generating public/private rsa key pair.
-Enter passphrase (empty for no passphrase):
-Enter same passphrase again:
-Your identification has been saved in /home/jay/.ssh/id_rsa.
-Your public key has been saved in /home/jay/.ssh/id_rsa.pub.
-The key fingerprint is:
-8b:aa:0a:98:fe:e7:84:48:a3:fe:5f:31:4b:16:e6:0b jay@my-workstation
-jay@my-workstation:~$ </computeroutput><userinput>ssh-add</userinput>
-<computeroutput>Enter passphrase for /home/jay/.ssh/id_rsa:
-Identity added: /home/jay/.ssh/id_rsa (/home/jay/.ssh/id_rsa)
-jay@my-workstation:~$ </computeroutput></screen>
-<para>Now copy the files you're going to need over to your target system, and install mercurial-server</para>
-<screen>
-<computeroutput>jay@my-workstation:~$ </computeroutput><userinput>ssh-copy-id repository-host</userinput>
-<computeroutput>jay@repository-host's password:
-Now try logging into the machine, with "ssh 'repository-host'", and check in:
-
- .ssh/authorized_keys
-
-to make sure we haven't added extra keys that you weren't expecting.
-jay@my-workstation:~$ </computeroutput><userinput>scp mercurial-server_0.6.1_amd64.deb repository-host:</userinput>
+<computeroutput>jay@my-workstation:~$ </computeroutput><userinput>scp mercurial-server_0.6.1_amd64.deb repository-host:</userinput>
<computeroutput>mercurial-server_0.6.1_amd64.deb 100%
jay@my-workstation:~$ </computeroutput><userinput>ssh -A repository-host</userinput>
<computeroutput>jay@repository-host:~$ </computeroutput><userinput>sudo dpkg -i ../mercurial-server_0.6.1_amd64.deb</userinput>
@@ -95,12 +75,14 @@
jay@my-workstation:~$ </computeroutput></screen>
<para>
You can now create repositories on the remote machine and have complete
-read-write access to all of them; you need never log on to <systemitem
-class="systemname">repository-host</systemitem> again.
+read-write access to all of them.
</para>
</section>
<section>
<title>Creating repositories</title>
+<para>
+To store a repository on the server, clone it over.
+</para>
<screen>
<computeroutput>jay@my-workstation:~$ </computeroutput><userinput>cd my-mercurial-project</userinput>
<computeroutput>jay@my-workstation:~/my-mercurial-project$ </computeroutput><userinput>hg clone . ssh://hg@repository-host/repository/name</userinput>
@@ -121,12 +103,7 @@
As things stand, 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>. 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, there's a more convenient way.
+<filename>~/sam-key.pub</filename>. To manage access, you make changes to the special <literal>hgadmin</literal> repository.
</para>
<screen>
<computeroutput>jay@my-workstation:~/my-mercurial-project$ </computeroutput><userinput>cd ..</userinput>
@@ -156,6 +133,14 @@
pushing changes to <literal>hgadmin</literal>, 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.
+</para>
</section>
<section>
<title>Basic access control</title>