Mercurial_ The Definitive Guide - Bryan O'Sullivan [45]
Simply generating a key pair isn’t enough, however. You’ll need to add the public key to the set of authorized keys for whatever user you’re logging in remotely as. For servers using OpenSSH (the vast majority), this will mean adding the public key to a list in a file called authorized_keys in their .ssh directory.
On a Unix-like system, your public key will have a .pub extension. If you’re using puttygen on Windows, you can save the public key to a file of your choosing, or paste it from the window it’s displayed in straight into the authorized_keys file.
Using an Authentication Agent
An authentication agent is a daemon that stores passphrases in memory (so it will forget passphrases if you log out and log back in again). An ssh client will notice if it’s running, and query it for a passphrase. If there’s no authentication agent running, or the agent doesn’t store the necessary passphrase, you’ll have to type your passphrase every time Mercurial tries to communicate with a server on your behalf (e.g., whenever you pull or push changes).
The downside of storing passphrases in an agent is that it’s possible for a well-prepared attacker to recover the plain text of your passphrases, in some cases even if your system has been power-cycled. You should make your own judgment as to whether this is an acceptable risk. It certainly saves a lot of repeated typing.
On Unix-like systems, the agent is called ssh-agent, and it’s often run automatically for you when you log in. You’ll need to use the ssh-add command to add passphrases to the agent’s store.
On Windows, if you’re using TortoiseHg, the pageant command acts as the agent. As with puttygen, you’ll need to download pageant from the PuTTY website and read its documentation. The pageant command adds an icon to your system tray that will let you manage stored passphrases.
Configuring the Server Side Properly
Because ssh can be fiddly to set up if you’re new to it, a variety of things can go wrong. Add Mercurial on top, and there’s plenty more scope for head-scratching. Most of these potential problems occur on the server side, not the client side. The good news is that once you’ve gotten a configuration working, it will usually continue to work indefinitely.
Before you try using Mercurial to talk to an ssh server, it’s best to make sure that you can use the normal ssh or putty command to talk to the server first. If you run into problems with using these commands directly, Mercurial surely won’t work. Worse, it will obscure the underlying problem. Any time you want to debug ssh-related Mercurial problems, you should drop back to making sure that plain ssh client commands work first, before you worry about whether there’s a problem with Mercurial.
The first thing to be sure of on the server side is that you can actually log in from another machine at all. If you can’t use ssh or putty to log in, the error message you get may give you a few hints as to what’s wrong. The most common problems are as follows:
If you get a “connection refused” error, either there isn’t an ssh daemon running on the server at all, or it’s inaccessible due to firewall configuration.
If you get a “no route to host” error, you either have an incorrect address for the server or a seriously locked-down firewall that won’t admit its existence at all.
If you get a “permission denied” error, you may have mistyped the username on the server, or you could have mistyped your key’s passphrase or the remote user’s password.
In summary, if you’re having trouble talking to the server’s ssh daemon, first make sure that one is running at all. On many systems it will be installed, but disabled, by default. Once you’re done with this step, you should then check that the server’s firewall is configured to allow incoming connections on the port the ssh daemon is listening on (usually 22). Don’t worry about more exotic possibilities for misconfiguration until you’ve checked these two first.
If