Integrating Ketura with Subversion using SSH

This article describes how to configure SSH on a Ketura server so that Ketura can communicate with Subversion using the svn+ssh protocol. The information here is not required or relevant if you are using one of the other Subversion protocols (HTTP, HTTPS, svn) to integrate Ketura and Subversion.

The rest of this article assumes a significant degree of familiarity with both Subversion and SSH. If you are new to either of these technologies, it is recommended that you instead configure Ketura to connect to Subversion using the HTTP, HTTPS or svn protocol.

Background

Ketura can integrate with Subversion via several different protocols, including svn+ssh. The svn+ssh protocol uses SSH as the underlying transport and, unlike the other supported Subversion protocols, requires some additional configuration outside Ketura for it to work.

The Ketura server runs using a particular operating system user account. On Windows, Ketura runs as the system user; on Mac OS X, it runs as a user named ‘araxisketura’. Ketura issues any commands to SCM systems using this same account, and it will therefore also be used to open SSH connections when Ketura is configured to integrate with an SCM system of the type Subversion (SSH).

Ketura avoids the potential for extremely complex SSH configurations by supporting only one scenario for communicating via Subversion’s svn+ssh protocol. Ketura therefore mandates that SSH be configured to authenticate using a public-private key pair, with the private key not being password protected.

Information To maintain reasonable security, the private key file must have its permissions set so that it is readable only by the Ketura server’s user account (the system account on Windows, or ‘araxisketura’ on Mac OS X). It is also recommended that the SSH account used by Ketura on the Subversion server be configured with read-only access to the relevant repositories.

SSH configuration for both Mac OS X and Windows

To configure SSH on your Ketura server so that Ketura can use it to communicate with Subversion:

  1. Ensure that your Subversion server is configured to permit SSH connections.

  2. Create a new operating system user account on the Subversion server machine for use by Ketura to access Subversion. As a security precaution, it is sensible to limit this user to read-only access to your Subversion repository.

  3. Generate a public-private key pair, without a passphrase, for this account. Ketura will use the private key to authenticate its SSH connections with the machine hosting the Subversion server. Key pair generation can be carried out on either machine but, if you do it on the machine hosting Ketura, you can avoid transferring the private key across a network.

    Information The generated private key must not have a passphrase, otherwise Ketura will be unable to use it to open an SSH connection. See the documentation of your SSH implementation for details concerning the generation of public-private key pairs.

  4. On the machine hosting the Subversion server, append the contents of the public key file to the authorised_keys file in the SSH configuration directory of the new SSH user that you created earlier.

  5. See the relevant Further SSH configuration section below to ensure that the generated private key file is available to the Ketura user account.

    Information The precise steps required will depend upon the SSH implementation that you are using on the machine hosting Ketura. On Mac OS X, SSH client-side support is provided with the operating system. On Windows, SSH client-side support is typically provided using the PuTTY suite of SSH client tools. The Subversion client can be configured to use PuTTY’s plink.exe tool to open SSH connections to the Subversion server.

Further SSH configuration for Mac OS X

To make the private key file available on Mac OS X:

  1. Run the following commands in a Terminal window:

    cd /Library/Araxis/Ketura
sudo mkdir -p .ssh
sudo chown araxisketura:araxisketura .ssh
sudo chmod 700 .ssh

  2. Move the private key file you generated earlier (most likely id_rsa or id_dsa) into the /Library/Araxis/Ketura/.ssh directory.

  3. Run the following commands in a Terminal window:

    sudo chown araxisketura:araxisketura /Library/Araxis/Ketura/.ssh/<private-key-file><
sudo chmod 600 /Library/Araxis/Ketura/.ssh/<private-key-file>
sudo -u araxisketura ssh <ssh-user>@<subversion-host>

    where:

    • is the name of your private key file;
    • is the name of the SSH user account you have created for Ketura on your Subversion server;
    • is the hostname of your Subversion server.

    If prompted, verify the fingerprint of the Subversion host and confirm to continue.

  4. Log out of your SSH session by pressing Ctrl+D.

Further SSH configuration for Windows

To configure PuTTY for Ketura:

  1. Log on as a Windows system administrator to the machine running the Ketura server.

  2. Run the puttygen.exe tool. This will be used to convert the private key you generated earlier into PuTTy’s own format for private keys.

  3. Under the Conversions menu, select Import key. The key will be imported.

  4. Click the Save private key button to save the private key to a .ppk file. If a warning is shown asking whether you want to save the key without a passphrase, click the Yes button. When saving the file, select a location that can be accessed by the Windows system user and administrators only, such as C:\WINDOWS\system32\config\systemprofile\Application Data\PuTTY\keys\ on Windows XP and Windows Server 2003, or C:\WINDOWS\system32\config\systemprofile\AppData\Roaming\PuTTY\keys\ on Windows Vista and later. You will need to create the PuTTY and keys directories before saving the file.

  5. Run the the putty.exe tool. This will be used to create a saved session to the machine hosting your Subversion server.

  6. Under the Session category, set the Host Name field to the address of the machine hosting the Subversion server.

  7. Check that the selected protocol is SSH.

  8. Under the Connection▸SSH▸Auth category, add the full path of the .ppk file that you created earlier.

  9. Return to the Session category, enter a name in the Saved Sessions field before clicking the Save button.

  10. At this point, it should be possible to use putty.exe to open an SSH connection to the machine hosting Subversion. In putty.exe, select the session that you created and click the Open button.

  11. A PuTTY terminal should open and a dialog will appear, asking you to add the server’s host key to the registry. Click the Yes button to continue.

    Log out of your SSH session by pressing Ctrl+D.

    Information Recall that Ketura runs as the non-login system user. The saved SSH session that you have just created using PuTTY must therefore be made available to this user. Because PuTTY stores its settings in the Windows registry, this requires manipulation of the registry. The next few steps will guide you through this process.

  12. Launch the Windows registry editor (regedit.exe).

  13. Navigate to the key HKEY_CURRENT_USER\Software\SimonTatham\PuTTY and export it to a file on your desktop.

  14. Open the exported file in a text editor and replace every instance of [HKEY_CURRENT_USER\ with [HKEY_USERS\S-1-5-18\.

  15. Save the file.

  16. In Windows Explorer, double-click the registry file on your desktop. This will merge the file’s contents into the registry.

  17. Subversion must be configured to use PuTTY’s plink.exe tool for establishing SSH connections. If this has not already been done, open the Subversion config file for the System user account. This file will typically be located at C:\WINDOWS\system32\config\systemprofile\Application Data\Subversion\config on Windows XP and Windows Server 2003, or at C:\Windows\system32\config\systemprofile\AppData\Roaming\Subversion\config on Windows Vista and later.

  18. Find the section labelled ‘[tunnels]’ and add the following line beneath it:

    ssh = $SVN_SSH "C:/Program Files/PuTTY/plink.exe" -ssh -batch

    where C:/Program Files/PuTTY/ is the location of your PuTTY installation.

Ketura configuration

To configure Ketura to connect to a Subversion server using SSH:

  1. Log onto Ketura as an administrator.

  2. Add a new SCM System for your SSH Subversion server. Choose Subversion (SSH) as the Type and enter Unused for the Username field. Leave the Password field blank.

    Information Due to the way Subversion uses SSH, the name of the SSH user account you created on the Subversion server must be provided in the Server address field. The value has syntax:

    username@server[:port]/path/to/repository

    For example, you might enter:

    ketura@myserver.domain.name/repos/

    If using a saved PuTTY session on Windows, specify the name of of the saved session in place of the server and port.