+
−<?xml version="1.0" encoding="utf-8"?>
+
−<article xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+
−<info>
+
−  <title>Sharing Mercurial repositories with mercurial-server</title>
+
−  <author><firstname>Paul</firstname><surname>Crowley</surname></author>
+
−  <copyright><year>2009</year><holder>Paul Crowley</holder></copyright>
+
−</info>
+
−<section>
+
−<title>About mercurial-server</title>
+
−<para>
+
−mercurial-server is software for Debian and Ubuntu systems which gives your
+
−developers remote read/write access to <ulink
+
−url="http://hg-scm.org/">Mercurial</ulink> repositories using SSH public
+
−key authentication; it provides convenient and fine-grained key management
+
−and access control.
+
−</para>
+
−<para>
+
−mercurial-server is the easiest and most secure way for several developers
+
−to have read/write access to a central repository, but that's not the only
+
−way for several people to work on the same project using Mercurial; you
+
−should be familiar with the <ulink
+
−url="http://mercurial.selenic.com/wiki/MultipleCommitters">other ways of
+
−handling multiple commiters</ulink> before deciding to use this.
+
−</para>
+
−<para>
+
−Though mercurial-server is currently targeted at Debian-based systems such
+
−as Ubuntu, other users have reported success getting it running on other
+
−Unix-based systems such as Red Hat. Running it on a non-Unix system such as
+
−Windows is not supported. You will need root privileges to install it.
+
−</para>
+
−<section>
+
−<title>Legalese</title>
+
−<para>
+
−This program is free software; you can redistribute it and/or modify it
+
−under the terms of the GNU General Public License as published by the Free
+
−Software Foundation; either version 2 of the License, or (at your option)
+
−any later version.
+
−</para>
+
−<para>
+
−This program is distributed in the hope that it will be useful, but
+
−WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+
−or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+
−more details.
+
−</para>
+
−<para>
+
−You should have received a copy of the GNU General Public License along
+
−with this program; if not, write to the Free Software Foundation, Inc., 51
+
−Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
−</para>
+
−</section>
+
−</section>
+
−<section>
+
−<title>Step by step</title>
+
−<para>
+
−mercurial-server authenticates users not using passwords but using <ulink url="http://sial.org/howto/openssh/publickey-auth/">SSH public keys</ulink>; 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 equivalents such as the Windows program <ulink url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">Pageant</ulink>), this means that users will not need to type in a password to access the repository.
+
−</para>
+
−<para>
+
−In what follows, we assume 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.
+
−</para>
+
−<screen>
+
−<computeroutput>user@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/user/.ssh/id_rsa.
+
−Your public key has been saved in /home/user/.ssh/id_rsa.pub.
+
−The key fingerprint is:
+
−8b:aa:0a:98:fe:e7:84:48:a3:fe:5f:31:4b:16:e6:0b user@my-workstation
+
−user@my-workstation:~$ </computeroutput><userinput>ssh-add</userinput>
+
−<computeroutput>Enter passphrase for /home/user/.ssh/id_rsa: 
+
−Identity added: /home/user/.ssh/id_rsa (/home/user/.ssh/id_rsa)
+
−user@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>user@my-workstation:~$ </computeroutput><userinput>ssh-copy-id repository-host</userinput>
+
−<computeroutput>user@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.
+
−user@my-workstation:~$ </computeroutput><userinput>scp mercurial-server_0.6.1_amd64.deb repository-host:</userinput>
+
−<computeroutput>mercurial-server_0.6.1_amd64.deb 100%
+
−user@my-workstation:~$ </computeroutput><userinput>ssh -A repository-host</userinput>
+
−<computeroutput>user@repository-host:~$ </computeroutput><userinput>sudo dpkg -i ../mercurial-server_0.6.1_amd64.deb</userinput>
+
−<computeroutput>[sudo] password for user: 
+
−Selecting previously deselected package mercurial-server.
+
−(Reading database ... 144805 files and directories currently installed.)
+
−Unpacking mercurial-server (from .../mercurial-server_0.6.1_amd64.deb) ...
+
−Setting up mercurial-server (0.6.1) ...
+
−user@repository-host:~$ </computeroutput></screen>
+
−<para>
+
−mercurial-server is now installed on the repository host.  Next, we need to give you permission to see its repositories.
+
−</para>
+
−<screen>
+
−<computeroutput>user@repository-host:~$ </computeroutput><userinput>ssh-add -L > my-key</userinput>
+
−<computeroutput>user@repository-host:~$ </computeroutput><userinput>sudo mkdir -p /etc/mercurial-server/keys/root/user</userinput>
+
−<computeroutput>user@repository-host:~$ </computeroutput><userinput>sudo cp my-key /etc/mercurial-server/keys/root/user/my-workstation</userinput>
+
−<computeroutput>user@repository-host:~$ </computeroutput><userinput>sudo -u hg /usr/share/mercurial-server/refresh-auth</userinput>
+
−<computeroutput>user@repository-host:~$ </computeroutput><userinput>exit</userinput>
+
−<computeroutput>Connection to shell closed.
+
−user@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.
+
−</para>
+
−<screen>
+
−<computeroutput>user@my-workstation:~$ </computeroutput><userinput>cd my-mercurial-project</userinput>
+
−<computeroutput>user@my-workstation:~/my-mercurial-project$ </computeroutput><userinput>hg clone . ssh://hg@repository-host/repository/name</userinput>
+
−<computeroutput>searching for changes
+
−remote: adding changesets
+
−remote: adding manifests
+
−remote: adding file changes
+
−remote: added 119 changesets with 284 changes to 61 files
+
−user@my-workstation:~/my-mercurial-project$ </computeroutput><userinput>hg pull ssh://hg@repository-host/repository/name</userinput>
+
−<computeroutput>pulling from ssh://hg@repository-host/repository/name
+
−searching for changes
+
−no changes found
+
−user@my-workstation:~/my-mercurial-project$ </computeroutput></screen>
+
−<para>
+
−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.  Once you have that key, you could give them access by logging into <systemitem class="systemname">repository-host</systemitem>, putting their keys 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.
+
−</para>
+
−<screen>
+
−<computeroutput>user@my-workstation:~/my-mercurial-project$ </computeroutput><userinput>cd ..</userinput>
+
−<computeroutput>user@my-workstation:~$ </computeroutput><userinput>hg clone ssh://hg@repository-host/hgadmin</userinput>
+
−<computeroutput>destination directory: hgadmin
+
−no changes found
+
−updating working directory
+
−0 files updated, 0 files merged, 0 files removed, 0 files unresolved
+
−user@my-workstation:~$ </computeroutput><userinput>cd hgadmin</userinput>
+
−<computeroutput>user@my-workstation:~/hgadmin$ </computeroutput><userinput>mkdir -p keys/users/other-user</userinput>
+
−<computeroutput>user@my-workstation:~/hgadmin$ </computeroutput><userinput>cp ~/other-users-key.pub keys/users/other-user/their-workstation</userinput>
+
−<computeroutput>user@my-workstation:~/hgadmin$ </computeroutput><userinput>hg add</userinput>
+
−<computeroutput>adding keys/users/other-user/their-workstation
+
−user@my-workstation:~/hgadmin$ </computeroutput><userinput>hg commit -m "Add other user"</userinput>
+
−<computeroutput>user@my-workstation:~/hgadmin$ </computeroutput><userinput>hg push</userinput>
+
−<computeroutput>pushing to ssh://hg@repository-host/hgadmin
+
−searching for changes
+
−remote: adding changesets
+
−remote: adding manifests
+
−remote: adding file changes
+
−remote: added 1 changesets with 1 changes to 1 files
+
−user@my-workstation:~/hgadmin$ </computeroutput></screen>
+
−<para>
+
−The new user can now read and write to your <literal>ssh://hg@repository-host/repository/name</literal> repository.
+
−</para>
+
−</section>
+
−</article>
+
−