Chapter 12. Troubleshooting and FAQ

12.1.1. Client Debugging

Most clients print debug messages when invoked with the -v (verbose mode) option: [Section 7.4.15, "Logging and Debugging"]

$ ssh -v server.example.com
$ scp -v myfile server.example.com:otherfile

So many problems can be identified in verbose mode. This should be your first instinct whenever you encounter a problem.

TIP: Please take a deep breath and repeat after us:

"ssh -v is my friend..."

"ssh -v is my friend..."

"ssh -v is my friend..."

12.1.2. Server Debugging

The SSH1, SSH2, and OpenSSH servers also print debug messages when asked:

# SSH1, OpenSSH
$ sshd -d

# SSH2 only
$ sshd2 -v

In either case, the server enters a special debugging mode. It accepts a single connection, operates normally until the connection terminates, and then exits. It doesn't go into the background or create a child process to handle the connection, and it prints information on its progress to the screen (that is, to the standard error stream).

SSH2 has a more complicated system for debugging: numeric debugging levels, specified with the -d option, where a higher number means more information. [Section 5.8.2, "Logging and SSH2"] In fact, -v for verbose mode is actually just a shorthand for -d2. At higher debug levels, the output is so huge that only SSH developers will likely find it of use in tracking down obscure problems. But you may need to crank up the level beyond 2 to see the information you need. For example, to have it report which algorithms are negotiated for a connection, use -d3. If you get the error message "TCP/IP Failure", turning up to -d5 shows the more specific OS-level error message returned from the connection attempt.

When debugging a server, remember to avoid port conflicts with any other running SSH server. Either terminate the other server or use an alternative port number for debugging:

$ sshd1 -d -p 54321

Use the -p option in the client when testing this debugging instance of the server:

$ ssh -p 54321 localhost

This way, you don't interrupt or affect another sshd in use.

The Top Ten SSH Questions How do I install my public key file on the remote host the first time? Connect by password authentication and use your terminal program's copy and paste feature. [Section 12.2.2.4, "Public-key authentication"] I put my SSH public key file mykey.pub into my remote SSH directory, but public-key authentication doesn't work. The public key must be referenced in your remote authorization file. [Section 12.2.2.4, "Public-key authentication"] Public-key authentication isn't working. Use ssh -v, and check your keys, files, and permissions. [Section 12.2.2.4, "Public-key authentication"] Password authentication isn't working. Use ssh -v. There are a variety of possible causes. [Section 12.2.2.2, "Password authentication"] Trusted-host authentication isn't working (SSH1 RhostsRSA, SSH2 hostbased). Use ssh -v. Check your four control files, hostnames, and setuid status of the SSH client program or ssh-signer2. [Section 12.2.2.3, "Trusted-host authentication"] How do I authenticate without typing a password or passphrase? ssh-agent, unencrypted keys, trusted-host authentication, or Kerberos. [Section 12.2.2.1, "General authentication problems"] How do I secure FTP with port forwarding? Forward a local port to port 21 on the FTP server for the control connection; the data connection is much harder. [Section 12.2.5.6, "Port forwarding"] X forwarding isn't working. Don't set your remote DISPLAY variable manually. (And there are other things to check.) [Section 12.2.5.6, "Port forwarding"] Why don't wildcards or shell variables work on the scp command line? Your local shell expands them before scp runs. Escape the special characters. [Section 12.2.5.4, "scp"] A feature of ssh or scp isn't working, but I'm sure I'm using it correctly. Use ssh -v. Also the system configuration may be overriding your settings.