29 <title>Step by step</title> |
29 <title>Step by step</title> |
30 <para> |
30 <para> |
31 mercurial-server authenticates users not using passwords but using <link |
31 mercurial-server authenticates users not using passwords but using <link |
32 xlink:href="http://sial.org/howto/openssh/publickey-auth/">SSH public |
32 xlink:href="http://sial.org/howto/openssh/publickey-auth/">SSH public |
33 keys</link>; everyone who wants access to a mercurial-server repository |
33 keys</link>; everyone who wants access to a mercurial-server repository |
34 will need such a key, so you'll need to familiarize yourself with them |
34 will need such a key. In combination with <command>ssh-agent</command> (or |
35 before proceeding. In combination with <command>ssh-agent</command> (or |
|
36 equivalents such as the Windows program <link |
35 equivalents such as the Windows program <link |
37 xlink:href="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">Pageant</link>), |
36 xlink:href="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">Pageant</link>), |
38 this means that users will not need to type in a password to access the |
37 this means that users will not need to type in a password to access the |
39 repository. |
38 repository. |
40 </para> |
39 </para> |
41 <section> |
40 <section> |
42 <title>Creating a repository host</title> |
41 <title>Installing mercurial-server</title> |
43 <para> |
42 <para> |
44 In what follows, we assume that your username is <systemitem |
43 In what follows, we assume that your username is <systemitem |
45 class="username">jay</systemitem>, that you usually sit at a machine called |
44 class="username">jay</systemitem>, that you usually sit at a machine called |
46 <systemitem class="systemname">my-workstation</systemitem> and you wish to |
45 <systemitem class="systemname">my-workstation</systemitem> and you wish to |
47 install mercurial-server on <systemitem |
46 install mercurial-server on <systemitem |
48 class="systemname">repository-host</systemitem>. First, you'll need to |
47 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 |
49 create an SSH public key if you haven't already. You should consult your |
48 class="systemname">repository-host</systemitem>. If you're not familiar with SSH public keys, the <link |
50 system documentation on how to do this, but it should look something like |
49 xlink:href="http://sial.org/howto/openssh/publickey-auth/">OpenSSH Public |
51 this. |
50 Key Authentication tutorial</link> may be helpful. |
52 </para> |
51 </para> |
|
52 <para>First install mercurial-server on <systemitem |
|
53 class="systemname">repository-host</systemitem>:</para> |
53 <screen> |
54 <screen> |
54 <computeroutput>jay@my-workstation:~$ </computeroutput><userinput>ssh-keygen</userinput> |
55 <computeroutput>jay@my-workstation:~$ </computeroutput><userinput>scp mercurial-server_0.6.1_amd64.deb repository-host:</userinput> |
55 <computeroutput>Generating public/private rsa key pair. |
|
56 Enter passphrase (empty for no passphrase): |
|
57 Enter same passphrase again: |
|
58 Your identification has been saved in /home/jay/.ssh/id_rsa. |
|
59 Your public key has been saved in /home/jay/.ssh/id_rsa.pub. |
|
60 The key fingerprint is: |
|
61 8b:aa:0a:98:fe:e7:84:48:a3:fe:5f:31:4b:16:e6:0b jay@my-workstation |
|
62 jay@my-workstation:~$ </computeroutput><userinput>ssh-add</userinput> |
|
63 <computeroutput>Enter passphrase for /home/jay/.ssh/id_rsa: |
|
64 Identity added: /home/jay/.ssh/id_rsa (/home/jay/.ssh/id_rsa) |
|
65 jay@my-workstation:~$ </computeroutput></screen> |
|
66 <para>Now copy the files you're going to need over to your target system, and install mercurial-server</para> |
|
67 <screen> |
|
68 <computeroutput>jay@my-workstation:~$ </computeroutput><userinput>ssh-copy-id repository-host</userinput> |
|
69 <computeroutput>jay@repository-host's password: |
|
70 Now try logging into the machine, with "ssh 'repository-host'", and check in: |
|
71 |
|
72 .ssh/authorized_keys |
|
73 |
|
74 to make sure we haven't added extra keys that you weren't expecting. |
|
75 jay@my-workstation:~$ </computeroutput><userinput>scp mercurial-server_0.6.1_amd64.deb repository-host:</userinput> |
|
76 <computeroutput>mercurial-server_0.6.1_amd64.deb 100% |
56 <computeroutput>mercurial-server_0.6.1_amd64.deb 100% |
77 jay@my-workstation:~$ </computeroutput><userinput>ssh -A repository-host</userinput> |
57 jay@my-workstation:~$ </computeroutput><userinput>ssh -A repository-host</userinput> |
78 <computeroutput>jay@repository-host:~$ </computeroutput><userinput>sudo dpkg -i ../mercurial-server_0.6.1_amd64.deb</userinput> |
58 <computeroutput>jay@repository-host:~$ </computeroutput><userinput>sudo dpkg -i ../mercurial-server_0.6.1_amd64.deb</userinput> |
79 <computeroutput>[sudo] password for jay: |
59 <computeroutput>[sudo] password for jay: |
80 Selecting previously deselected package mercurial-server. |
60 Selecting previously deselected package mercurial-server. |
93 <computeroutput>jay@repository-host:~$ </computeroutput><userinput>exit</userinput> |
73 <computeroutput>jay@repository-host:~$ </computeroutput><userinput>exit</userinput> |
94 <computeroutput>Connection to shell closed. |
74 <computeroutput>Connection to shell closed. |
95 jay@my-workstation:~$ </computeroutput></screen> |
75 jay@my-workstation:~$ </computeroutput></screen> |
96 <para> |
76 <para> |
97 You can now create repositories on the remote machine and have complete |
77 You can now create repositories on the remote machine and have complete |
98 read-write access to all of them; you need never log on to <systemitem |
78 read-write access to all of them. |
99 class="systemname">repository-host</systemitem> again. |
|
100 </para> |
79 </para> |
101 </section> |
80 </section> |
102 <section> |
81 <section> |
103 <title>Creating repositories</title> |
82 <title>Creating repositories</title> |
|
83 <para> |
|
84 To store a repository on the server, clone it over. |
|
85 </para> |
104 <screen> |
86 <screen> |
105 <computeroutput>jay@my-workstation:~$ </computeroutput><userinput>cd my-mercurial-project</userinput> |
87 <computeroutput>jay@my-workstation:~$ </computeroutput><userinput>cd my-mercurial-project</userinput> |
106 <computeroutput>jay@my-workstation:~/my-mercurial-project$ </computeroutput><userinput>hg clone . ssh://hg@repository-host/repository/name</userinput> |
88 <computeroutput>jay@my-workstation:~/my-mercurial-project$ </computeroutput><userinput>hg clone . ssh://hg@repository-host/repository/name</userinput> |
107 <computeroutput>searching for changes |
89 <computeroutput>searching for changes |
108 remote: adding changesets |
90 remote: adding changesets |
119 <title>Adding other users</title> |
101 <title>Adding other users</title> |
120 <para> |
102 <para> |
121 As things stand, no-one but you has any access to any repositories you |
103 As things stand, no-one but you has any access to any repositories you |
122 create on this system. In order to give anyone else access, you'll need a |
104 create on this system. In order to give anyone else access, you'll need a |
123 copy of their SSH public key; we'll assume you have that key in |
105 copy of their SSH public key; we'll assume you have that key in |
124 <filename>~/sam-key.pub</filename>. You could give them access by |
106 <filename>~/sam-key.pub</filename>. To manage access, you make changes to the special <literal>hgadmin</literal> repository. |
125 logging into <systemitem class="systemname">repository-host</systemitem>, |
|
126 putting the key in the right place under <filename |
|
127 class='directory'>/etc/mercurial-server/keys</filename>, and re-running |
|
128 <userinput>sudo -u hg /usr/share/mercurial-server/refresh-auth</userinput>. |
|
129 However, there's a more convenient way. |
|
130 </para> |
107 </para> |
131 <screen> |
108 <screen> |
132 <computeroutput>jay@my-workstation:~/my-mercurial-project$ </computeroutput><userinput>cd ..</userinput> |
109 <computeroutput>jay@my-workstation:~/my-mercurial-project$ </computeroutput><userinput>cd ..</userinput> |
133 <computeroutput>jay@my-workstation:~$ </computeroutput><userinput>hg clone ssh://hg@repository-host/hgadmin</userinput> |
110 <computeroutput>jay@my-workstation:~$ </computeroutput><userinput>hg clone ssh://hg@repository-host/hgadmin</userinput> |
134 <computeroutput>destination directory: hgadmin |
111 <computeroutput>destination directory: hgadmin |
154 <literal>ssh://hg@repository-host/repository/name</literal> repository. |
131 <literal>ssh://hg@repository-host/repository/name</literal> repository. |
155 Most other changes to access control can be made simply by making and |
132 Most other changes to access control can be made simply by making and |
156 pushing changes to <literal>hgadmin</literal>, and you can use Mercurial to |
133 pushing changes to <literal>hgadmin</literal>, and you can use Mercurial to |
157 cooperate with other root users in the normal way. |
134 cooperate with other root users in the normal way. |
158 </para> |
135 </para> |
|
136 <para> |
|
137 If you prefer, you could give them access by |
|
138 logging into <systemitem class="systemname">repository-host</systemitem>, |
|
139 putting the key in the right place under <filename |
|
140 class='directory'>/etc/mercurial-server/keys</filename>, and re-running |
|
141 <userinput>sudo -u hg /usr/share/mercurial-server/refresh-auth</userinput>. |
|
142 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. |
|
143 </para> |
159 </section> |
144 </section> |
160 <section> |
145 <section> |
161 <title>Basic access control</title> |
146 <title>Basic access control</title> |
162 <para> |
147 <para> |
163 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. |
148 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. |