-- March 23, 2012

Overview

SSH support is added to licensed Kiln 2.8 in response to customer demand for secure data exchange. Hg client connects directly to SSH service without going through Kiln frontend, which is expected to resolve the connectivity problem with a large number of concurrent clients.

When SSH is enabled, the repository URL protocol can be selected from HTTP or SSH.

Information

Mercurial command line, or client tools operations like clone, pull, and push, can use either SSH or HTTP server addresses. There is no difference in regular "everyday" use. However, there are additional configuration steps required on the client side to start using SSH.

1. Install and configure Kiln client tools.
2. Generate client SSH key, configure hg to use it.
3. Share client key with the server.

Initial Client Configuration

1. Install and configure Kiln client tools

   1. Install TortoiseHG packaged with KilnClientTools. Kiln 2.8 tools include an updated TortoiseHG to resolve known SSH issues in the older versions of TortoiseHG. If you have KilnClientTools coming from an earlier version, please make sure to remove them and install the latest version.

   2. If you run ClientTools on Windows2003 or earlier versions of Windows, it will be necessary to update Pageant.exe, since the version 0.60 coming with TortoiseHG is not fully compatible with Windows2003. By default, it is installed in C:\Program Files\TortoiseHg\pageant.exe. The latest version of pageant can be obtained from PuTTY's download page.

2. Generate client SSH key, configure HG to use it

   1. Create a new key with PuttyGen using SSH-2 RSA and other default parameters.
      PuttyGen.exe is available from PuTTY's download page.

   2. Save the private key to a file.

   3. Launch Pageant.exe (the default location is C:\Program Files\TortoiseHg\).

   4. Double-click the Pageant icon in the tray and load (Add Key) private key from the file.

   5. The Pageant will stay in memory and automatically provide a full key to TortoiseHG and hg command line tools.

3. Share client key with the server

   1. Back in the PuttyGen, copy the text in the "Public key for pasting..." text box to the clipboard.

   2. In Kiln's website open the SSH Keys page:
      
      
      
      Note: SSH can be disabled by the system administrator. In this case, the SSH Keys page and the SSH repository URL links are not available.

   3. Click on Add a New Key and paste the public key there. Click Save Key when you are finished. 
      
      

Advanced Client Configuration and Troubleshooting Q&A

Q: What if I do not want to run Pageant on the client?

The client's private key can be loaded with Pageant.exe or specified in the Mercurial.ini configuration file using SSH value in the [ui] section. Add the SSH key if it is not there, and make sure it points to TortoisePLink and provide a path to the client's private key in -i switch:

[ui]
ssh="C:\Program Files\TortoiseHg\TortoisePLink.exe" -ssh -2 -C -i "C:\your path to\myprivatekey.ppk"

Q: Where can I find mercurial.ini?

• C:\Users\{username} on Windows 7
• C:\Documents and Settings\{username} on earlier versions of Windows

Q: What is PuTTY?

Q: How can I get detailed client-side SSH information?

[ui]
ssh="C:\Program Files\TortoiseHg\TortoisePLink.exe" -v -ssh -2 -C

[ui]
ssh="C:\Program Files\TortoiseHg\TortoisePLink.exe" -ssh -2 -C

Error: "Disconnected: No supported authentication methods available (server sent: publickey)"

• A "PuTTY Fatal Error" dialog box pops up with an error message "Disconnected: No supported authentication methods available (server sent: publickey)"
• Cause: server could not receive any client key.
• Fix: Make sure pageant is running and has client key loaded. If the error persists, turn on verbose client-side information to get more details on the issue.

Error: "Failed to get reply from Pageant."

• When troubleshooting other errors, detailed client-side information contains lines "Pageant is running. Requesting keys.", "Failed to get reply from Pageant." The pageant is running and has private key loaded.
• Cause: There is a known issue with TortoiseHG running on Windows versions other that Windows 7.
• Fix: Upgrade Pageant to v0.62.
• Workaround: If Pageant update is not possible, the client SSH key can be provided via mercurial.ini as shown earlier in this article.

Back-end Configuration Summary

• Installation

The SSH server is built-in into Kiln 2.8 package and automatically launches with Kiln back-end. After the installation, though it can be re-configured to use a different port, change server keys or completely disable SSH.

• Configuration

The key "EnableSSH" in web.config controls the availability of the SSH Keys page and the HTTP/SSH switch in repository Clone URL on the web site.

<appSettings>
<add key="EnableSSH" value="True" />

The Clone URL selector on the web site requires an SSH server on the back-end to be online. If EnableSSH is set to True, but the SSH server is down for any reason, Clone URL will display only the default HTTP link.

The SSH server references server-side keys and port in the registry:

After the installation, the Kiln administrator can change keys or port number to adhere to network configuration and security requirements. It is recommended to generate new keys for each server to improve security.

When updating the server's keys, make sure to keep only "public key for pasting" in the public key file and use 1024-bit SSH-2 RSA.

Changing the port or keys requires back-end restart to take effect.