doc/manual.docbook
changeset 131 e8bf13d06582
parent 130 850d46ca28ca
child 132 a5850a63390f
equal deleted inserted replaced
130:850d46ca28ca 131:e8bf13d06582
    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.