Sharing Mercurial repositories with mercurial-server

+ + Sharing Mercurial repositories with mercurial-server + PaulCrowley + 2009Paul Crowley + +

+About mercurial-server + +mercurial-server is software for Debian and Ubuntu systems which gives your +developers remote read/write access to Mercurial repositories using SSH public +key authentication; it provides convenient and fine-grained key management +and access control. + + +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 other ways of +handling multiple commiters before deciding to use this. + + +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. + +

+Legalese + +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. + + +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. + + +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. + +

+Step by step + +mercurial-server authenticates users not using passwords but using SSH public keys; 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 ssh-agent (or equivalents such as the Windows program Pageant), this means that users will not need to type in a password to access the repository. + + +In what follows, we assume that you usually sit at a machine called my-workstation and you wish to install mercurial-server on repository-host. 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. + + +user@my-workstation:~$ ssh-keygen +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:~$ ssh-add +Enter passphrase for /home/user/.ssh/id_rsa: +Identity added: /home/user/.ssh/id_rsa (/home/user/.ssh/id_rsa) +user@my-workstation:~$ +Now copy the files you're going to need over to your target system, and install mercurial-server + +user@my-workstation:~$ ssh-copy-id repository-host +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:~$ scp mercurial-server_0.6.1_amd64.deb repository-host: +mercurial-server_0.6.1_amd64.deb 100% +user@my-workstation:~$ ssh -A repository-host +user@repository-host:~$ sudo dpkg -i ../mercurial-server_0.6.1_amd64.deb +[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:~$ + +mercurial-server is now installed on the repository host. Next, we need to give you permission to see its repositories. + + +user@repository-host:~$ ssh-add -L > my-key +user@repository-host:~$ sudo mkdir -p /etc/mercurial-server/keys/root/user +user@repository-host:~$ sudo cp my-key /etc/mercurial-server/keys/root/user/my-workstation +user@repository-host:~$ sudo -u hg /usr/share/mercurial-server/refresh-auth +user@repository-host:~$ exit +Connection to shell closed. +user@my-workstation:~$ + +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 repository-host again. + + +user@my-workstation:~$ cd my-mercurial-project +user@my-workstation:~/my-mercurial-project$ hg clone . ssh://hg@repository-host/repository/name +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$ hg pull ssh://hg@repository-host/repository/name +pulling from ssh://hg@repository-host/repository/name +searching for changes +no changes found +user@my-workstation:~/my-mercurial-project$ + +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 repository-host, putting their keys in the right place under /etc/mercurial-server/keys, and re-running sudo -u hg /usr/share/mercurial-server/refresh-auth. However, there's a more convenient way. + + +user@my-workstation:~/my-mercurial-project$ cd .. +user@my-workstation:~$ hg clone ssh://hg@repository-host/hgadmin +destination directory: hgadmin +no changes found +updating working directory +0 files updated, 0 files merged, 0 files removed, 0 files unresolved +user@my-workstation:~$ cd hgadmin +user@my-workstation:~/hgadmin$ mkdir -p keys/users/other-user +user@my-workstation:~/hgadmin$ cp ~/other-users-key.pub keys/users/other-user/their-workstation +user@my-workstation:~/hgadmin$ hg add +adding keys/users/other-user/their-workstation +user@my-workstation:~/hgadmin$ hg commit -m "Add other user" +user@my-workstation:~/hgadmin$ hg push +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$ + +The new user can now read and write to your ssh://hg@repository-host/repository/name repository. + +