doc/source/en/TortoiseGit/tsvn_app_ssh.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE appendix SYSTEM "../../dtd/dblite.dtd">\r
   3 <appendix id="tsvn-ssh-howto">\r
   4         <title>Securing Svnserve using SSH</title>\r
   5         <simplesect>\r
   6                 <para>\r
   7                         This section provides a step-by-step guide to setting up\r
   8                         Git and TortoiseGit to use the <literal>svn+ssh</literal>\r
   9                         protocol. If you already use authenticated SSH connections to login\r
  10                         to your server, then you are already there and you can find more detail\r
  11                         in the Git book. If you are not using SSH but would like to do\r
  12                         so to protect your Git installation, this guide gives a simple\r
  13                         method which does not involve creating a separate SSH user account\r
  14                         on the server for every Git user.\r
  15                 </para>\r
  16                 <para>\r
  17                         In this implementation we create a single SSH user account for\r
  18                         all Git users, and use different authentication keys to\r
  19                         differentiate between the real Git users.\r
  20                 </para>\r
  21                 <para>\r
  22                         In this appendix we assume that you already have the Git tools\r
  23                         installed, and that you have created a repository as detailed elsewhere\r
  24                         in this manual. Note that you should <emphasis>not</emphasis> start\r
  25                         svnserve as a service or daemon when used with SSH.\r
  26                 </para>\r
  27                 <para>\r
  28                         Much of the information here comes from a tutorial\r
  29                         provided by Marc Logemann, which can be found at\r
  30                         <ulink url="http://www.logemann.org/2007/03/13/Git-TortoiseGit-ssh-howto/">\r
  31                                 <citetitle>www.logemann.org</citetitle>\r
  32                         </ulink>\r
  33                         Additional information on setting up a Windows server was\r
  34                         provided by Thorsten Müller. Thanks guys!\r
  35                 </para>\r
  36         </simplesect>\r
  37         <sect1 id="tsvn-ssh-linux-server">\r
  38                 <title>Setting Up a Linux Server</title>\r
  39                 <para>\r
  40                         You need to have SSH enabled on the server, and here we assume\r
  41                         that you will be using OpenSSH. On most distributions this will\r
  42                         already be installed. To find out, type:\r
  43 <screen>\r
  44 ps xa | grep sshd\r
  45 </screen>\r
  46                         and look for ssh jobs.\r
  47                 </para>\r
  48                 <para>\r
  49                         One point to note is that if you build Git from source and\r
  50                         do not provide any argument to <filename>./configure</filename>,\r
  51                         Git creates a <filename>bin</filename> directory under\r
  52                         <filename>/usr/local</filename> and places its binaries there.\r
  53                         If you want to use tunneling mode with SSH, you have to be aware\r
  54                         that the user logging in via SSH needs to execute the svnserve program \r
  55                         and some other binaries. For this reason, either place \r
  56                         <filename>/usr/local/bin</filename> into the <literal>PATH</literal> variable \r
  57                         or create symbolic links of your binaries to the <filename>/usr/sbin</filename>\r
  58                         directory, or to any other directory which is commonly in the\r
  59                         <literal>PATH</literal>.\r
  60                 </para>\r
  61                 <para>\r
  62                         To check that everything is OK, login in as the target user with SSH\r
  63                         and type:\r
  64 <screen>\r
  65 which svnserve\r
  66 </screen>\r
  67                         This command should tell you if svnserve is reachable.\r
  68                 </para>\r
  69                 <para>\r
  70                         Create a new user which we will use to access the svn repository:\r
  71 <screen>\r
  72 useradd -m svnuser\r
  73 </screen>\r
  74                         Be sure to give this user full access rights to the repository.\r
  75                 </para>\r
  76         </sect1>\r
  77         <sect1 id="tsvn-ssh-windows-server">\r
  78                 <title>Setting Up a Windows Server</title>\r
  79                 <para>\r
  80                         Install Cygwin SSH daemon as described here: \r
  81                         <ulink url="http://pigtail.net/LRP/printsrv/cygwin-sshd.html">\r
  82                                 <citetitle>http://pigtail.net/LRP/printsrv/cygwin-sshd.html</citetitle>\r
  83                         </ulink>\r
  84                 </para>\r
  85                 <para>\r
  86                         Create a new Windows user account <literal>svnuser</literal> which\r
  87                         we will use to access the repository.\r
  88                         Be sure to give this user full access rights to the repository.\r
  89                 </para>\r
  90                 <para>\r
  91                         If there is no password file yet then create one from the Cygwin console using:\r
  92 <screen>\r
  93 mkpasswd -l > /etc/passwd\r
  94 </screen>\r
  95                 </para>\r
  96         </sect1>\r
  97         <sect1 id="tsvn-ssh-client-tools">\r
  98                 <title>SSH Client Tools for use with TortoiseGit</title>\r
  99                 <para>\r
 100                         Grab the tools we need for using SSH on the windows client from this site:\r
 101                         <ulink url="http://www.chiark.greenend.org.uk/~sgtatham/putty/">\r
 102                                 <citetitle>http://www.chiark.greenend.org.uk/~sgtatham/putty/</citetitle>\r
 103                         </ulink>\r
 104                         Just go to the download section and get\r
 105                         <filename>Putty</filename>,\r
 106                         <filename>Plink</filename>,\r
 107                         <filename>Pageant</filename> and\r
 108                         <filename>Puttygen</filename>.\r
 109                 </para>\r
 110         </sect1>\r
 111         <sect1 id="tsvn-ssh-create-keys">\r
 112                 <title>Creating OpenSSH Certificates</title>\r
 113                 <para>\r
 114                         The next step is to create a key pair for authentication.\r
 115                         There are two possible ways to create keys. The first is to \r
 116                         create the keys with PuTTYgen on the client, upload the public\r
 117                         key to your server and use the private key with PuTTY.\r
 118                         The other is to create the key pair with the OpenSSH tool\r
 119                         ssh-keygen, download the private key to your client and\r
 120                         convert the private key to a PuTTY-style private key.\r
 121                 </para>\r
 122                 <sect2 id="tsvn-ssh-create-ssh-keygen">\r
 123                         <title>Create Keys using ssh-keygen</title>\r
 124                         <para>\r
 125                                 Login to the server as <literal>root</literal> or\r
 126                                 <literal>svnuser</literal> and type:\r
 127 <screen>\r
 128 ssh-keygen -b 1024 -t dsa -N passphrase -f keyfile\r
 129 </screen>\r
 130                                 substituting a real pass-phrase (which only you know) and key file.\r
 131                                 We just created a SSH2 DSA key with 1024 bit key-phrase.\r
 132                                 If you type\r
 133 <screen>\r
 134 ls -l keyfile*\r
 135 </screen>\r
 136                                 you will see two files, <filename>keyfile</filename> and\r
 137                                 <filename>keyfile.pub</filename>. As you might guess, the\r
 138                                 <filename>.pub</filename> file is the public key file, the\r
 139                                 other is the private one.\r
 140                         </para>\r
 141                         <para>\r
 142                                 Append the public key to those in the <filename>.ssh</filename>\r
 143                                 folder within the <literal>svnuser</literal> home directory:\r
 144 <screen>\r
 145 cat keyfile.pub &gt;&gt; /home/svnuser/.ssh/authorized_keys\r
 146 </screen>\r
 147                         </para>\r
 148                         <para>\r
 149                                 In order to use the private key we generated, we have to\r
 150                                 convert it to a putty format. This is because the private\r
 151                                 key file format is not specified by a standards body.\r
 152                                 After you download the private key file to your client PC,\r
 153                                 start PuTTYgen and use\r
 154                                 <menuchoice>\r
 155                                         <guimenu>Conversions</guimenu>\r
 156                                         <guimenuitem>Import key</guimenuitem>\r
 157                                 </menuchoice>.\r
 158                                 Browse to your file <filename>keyfile</filename> which you got\r
 159                                 from the server the passphrase you used when creating the key.\r
 160                                 Finally click on <guibutton>Save private key</guibutton> and\r
 161                                 save the file as <filename>keyfile.PPK</filename>.\r
 162                         </para>\r
 163                 </sect2>\r
 164                 <sect2 id="tsvn-ssh-create-puttygen">\r
 165                         <title>Create Keys using PuTTYgen</title>\r
 166                         <para>\r
 167                                 Use PuTTYgen to generate a public-key/private-key pair and\r
 168                                 save it. Copy the public key to the server and append it to\r
 169                                 those in the <filename>.ssh</filename> folder within the\r
 170                                 <literal>svnuser</literal> home directory:\r
 171 <screen>\r
 172 cat keyfile.pub &gt;&gt; /home/svnuser/.ssh/authorized_keys\r
 173 </screen>\r
 174                         </para>\r
 175                 </sect2>\r
 176         </sect1>\r
 177         <sect1 id="tsvn-ssh-test-putty">\r
 178                 <title>Test using PuTTY</title>\r
 179                 <para>\r
 180                         To test the connection we will use PuTTY. Start the program and\r
 181                         on the <guilabel>Session</guilabel> tab set the hostname to\r
 182                         the name or IP address of your server, the protocol to SSH and\r
 183                         save the session as <literal>SvnConnection</literal> or whatever\r
 184                         name you prefer. On the <guilabel>SSH</guilabel> tab set the\r
 185                         preferred SSH protocol version to 2 and from <guilabel>Auth</guilabel>\r
 186                         set the full path to the <literal>.PPK</literal> private key file you\r
 187                         converted earlier.\r
 188                         Go back to the <guilabel>Sessions</guilabel> tab and hit the\r
 189                         <guilabel>Save</guilabel> button. You will now see\r
 190                         <literal>SvnConnection</literal> in the list of saved sessions.\r
 191                 </para>\r
 192                 <para>\r
 193                         Click on <guilabel>Open</guilabel> and you should see a telnet\r
 194                         style login prompt. Use <literal>svnuser</literal> as the user name\r
 195                         and if all is well you should connect directly without being\r
 196                         prompted for a password.\r
 197                 </para>\r
 198                 <para>\r
 199                         You may need to edit <filename>/etc/sshd_config</filename> on the\r
 200                         server. Edit lines as follows and restart the SSH service afterwards.\r
 201 <screen>\r
 202 PubkeyAuthentication yes\r
 203 PasswordAuthentication no\r
 204 PermitEmptyPasswords no\r
 205 ChallengeResponseAuthentication no\r
 206 </screen>\r
 207                 </para>\r
 208         </sect1>\r
 209         <sect1 id="tsvn-ssh-testing-tsvn">\r
 210                 <title>Testing SSH with TortoiseGit</title>\r
 211                 <para>\r
 212                         So far we have only tested that you can login using SSH. Now we need\r
 213                         to make sure that the SSH connection can actually run svnserve.\r
 214                         On the server modify <filename>/home/svnuser/.ssh/authorized_keys</filename>\r
 215                         as follows to allow many Git authors to use the same system account,\r
 216                         <literal>svnuser</literal>. Note that every Git author uses the same\r
 217                         login but a different authentication key, thus you have to add one line for\r
 218                         every author.\r
 219                 </para>\r
 220                 <para>\r
 221                         Note: This is all on one very long line.\r
 222 <screen>\r
 223 command="svnserve -t -r &lt;ReposRootPath&gt; --tunnel-user=&lt;author&gt;",\r
 224             no-port-forwarding,no-agent-forwarding,no-X11-forwarding,\r
 225             no-pty ssh-rsa &lt;PublicKey&gt; &lt;Comment&gt;\r
 226 </screen>\r
 227                         There are several values that you need to set according to your setup.\r
 228                 </para>\r
 229                 <para>\r
 230                         <literal>&lt;ReposRootPath&gt;</literal> should be replaced with the\r
 231                         path to the directory containing your repositories. This avoids the\r
 232                         need to specify full server paths within URLs. Note that you must use\r
 233                         forward slashes even on a Windows server, e.g.\r
 234                         <filename>c:/svn/reposroot</filename>. In the examples below we assume\r
 235                         that you have a repository folder within the repository root called\r
 236                         <filename>repos</filename>.\r
 237                 </para>\r
 238                 <para>\r
 239                         <literal>&lt;author&gt;</literal> should be replaced with the svn author\r
 240                         that you want to be stored on commit. This also allows svnserve to use\r
 241                         its own access rights within <filename>svnserve.conf</filename>.\r
 242                 </para>\r
 243                 <para>\r
 244                         <literal>&lt;PublicKey&gt;</literal> should be replaced with the \r
 245                         public key that you generated earlier.\r
 246                 </para>\r
 247                 <para>\r
 248                         <literal>&lt;Comment&gt;</literal> can be any comment you like, but it is\r
 249                         useful for mapping an svn author name to the person's real name.\r
 250                 </para>\r
 251                 <para>\r
 252                         Right click on any folder in Windows Explorer and select\r
 253                         <menuchoice>\r
 254                                 <guimenu>TortoiseGit</guimenu>\r
 255                                 <guimenuitem>Repo-Browser</guimenuitem>\r
 256                         </menuchoice>.\r
 257                         You will be prompted to enter a URL, so enter one in this form:\r
 258 <screen>\r
 259 svn+ssh://svnuser@SvnConnection/repos\r
 260 </screen>\r
 261                         What does this URL mean? The Schema name is <literal>svn+ssh</literal>\r
 262                         which tells TortoiseGit how to handle the requests to the server. \r
 263                         After the double slash, you specify the user to connect to the server,\r
 264                         in our case <literal>svnuser</literal>. After the <literal>@</literal>\r
 265                         we supply our PuTTY session name. \r
 266                         This session name contains all details like where to find \r
 267                         the private key and the server's IP or DNS. Lastly we have to \r
 268                         provide the path to the repository, relative to the repository root\r
 269                         on the server, as specified in the <filename>authorized_keys</filename> file.\r
 270                 </para>\r
 271                 <para>\r
 272                         Click on <guibutton>OK</guibutton> and you should be able to browse\r
 273                         the repository content. If so you now have a running SSH tunnel in \r
 274                         conjunction with TortoiseGit.\r
 275                 </para>\r
 276                 <para>\r
 277                         Note that by default TortoiseGit uses its own version of Plink to\r
 278                         connect. This avoids a console window popping up for every authentication\r
 279                         attempt, but it also means that there is nowhere for error messages to\r
 280                         appear. If you receive the error <quote>Unable to write to standard output</quote>,\r
 281                         you can try specifying Plink as the client in TortoiseGit's network settings.\r
 282                         This will allow you to see the real error message generated by Plink.\r
 283                 </para>\r
 284         </sect1>\r
 285         <sect1 id="tsvn-ssh-configvariants">\r
 286                 <title>SSH Configuration Variants</title>\r
 287                 <para>\r
 288                         One way to simplify the URL in TortoiseGit is to set the \r
 289                         user inside the PuTTY session. For this you have to load \r
 290                         your already defined session <literal>SvnConnection</literal>\r
 291                         in PuTTY and in the <guilabel>Connection</guilabel> tab set\r
 292                         <guilabel>Auto login user</guilabel> to the user name, e.g.\r
 293                         <literal>svnuser</literal>. Save your PuTTY session as before\r
 294                         and try the following URL inside TortoiseGit:\r
 295 <screen>\r
 296 svn+ssh://SvnConnection/repos\r
 297 </screen>\r
 298                         This time we only provide the PuTTY session <literal>SvnConnection</literal>\r
 299                         to the SSH client TortoiseGit uses (TortoisePlink.exe). \r
 300                         This client will check the session for all necessary details.\r
 301                 </para>\r
 302                 <para>\r
 303                         At the time of writing PuTTY does not check all saved configurations,\r
 304                         so if you have multiple configurations with the same server name, it\r
 305                         will pick the first one which matches. Also, if you edit the default\r
 306                         configuration and save it, the auto login user name is\r
 307                         <emphasis>not</emphasis> saved.\r
 308                 </para>\r
 309                 <para>\r
 310                         Many people like to use Pageant for storing all their keys.\r
 311                         Because a PuTTY session is capable of storing a key, you don't\r
 312                         always need Pageant. But imagine you want to store keys for several \r
 313                         different servers; in that case you would have to edit the\r
 314                         PuTTY session over and over again, depending on the server you are \r
 315                         trying to connect with. In this situation Pageant makes perfect sense,\r
 316                         because when PuTTY, Plink, TortoisePlink or any other PuTTY-based tool\r
 317                         is trying to connect to an SSH server, it checks all private keys that\r
 318                         Pageant holds to initiate the connection.\r
 319                 </para>\r
 320                 <para>\r
 321                         For this task, simply run Pageant and add the private key. It should\r
 322                         be the same private key you defined in the PuTTY session above.\r
 323                         If you use Pageant for private key storage, you can delete the reference\r
 324                         to the private key file in your saved PuTTY session.\r
 325                         You can add more keys for other servers, or other users of course.\r
 326                 </para>\r
 327                 <para>\r
 328                         If you don't want to repeat this procedure after every reboot of your \r
 329                         client, you should place Pageant in the auto-start group of your\r
 330                         Windows installation. You can append the keys with \r
 331                         complete paths as command line arguments to Pageant.exe\r
 332                 </para>\r
 333                 <para>\r
 334                         The last way to connect to an SSH server is simply by using this URL\r
 335                         inside TortoiseGit:\r
 336 <screen>\r
 337 svn+ssh://svnuser@100.101.102.103/repos\r
 338 svn+ssh://svnuser@mydomain.com/repos\r
 339 </screen>\r
 340                         As you can see, we don't use a saved PuTTY session but an IP address\r
 341                         (or domain name) as the connection target. We also supply the user, \r
 342                         but you might ask how the private key file will be found. \r
 343                         Because TortoisePlink.exe is just a modified version of the standard\r
 344                         Plink tool from the PuTTY suite, TortoiseGit will also try all the keys\r
 345                         stored in Pageant.\r
 346                 </para>\r
 347                 <para>\r
 348                         If you use this last method, be sure you do not have a default username\r
 349                         set in PuTTY. We have had reports of a bug in PuTTY causing connections\r
 350                         to close in this case. To remove the default user, simply clear\r
 351                         <filename>HKEY_CURRENT_USER\Software\SimonTatham\Putty\Sessions\Default%20Settings\HostName</filename>\r
 352                 </para>\r
 353         </sect1>\r
 354 </appendix>\r