# HG changeset patch
# User Paul Crowley <paul@lshift.net>
# Date 1255536413 -3600
# Node ID e8bf13d06582679d44674df934bc59f0b00fb278
# Parent  850d46ca28cafe63744aed9f4683eababbe12c44
Assume they have SSH set up; talk about hgadmin first

diff -r 850d46ca28ca -r e8bf13d06582 doc/manual.docbook
--- 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>