Troubleshooting and FAQ

Contents:

Debug Messages: Your First Line of Defense
Problems and Solutions
Other SSH Resources
Reporting Bugs
SSH1, SSH2, and OpenSSH are complex products. When a problem occurs, your plan of action should be, in order:
  1. Run the client and server in debug mode.
  2. Consult archives of questions and answers to see if anyone else has encountered and solved this problem.
  3. Seek help.
Many people jump immediately to Step 3, posting questions in public forums and waiting hours or days for a reply, when a simple ssh -v or FAQ can clarify the problem in moments. Be a smart and efficient technologist, and use your available resources before seeking help from the community. (Although the SSH community is eager to help if you've done your homework.)

Debug Messages: Your First Line of Defense

SSH1/SSH2 clients and servers have debugging built-in. When invoked with appropriate options, these programs emit messages about their progress and failures. You can use these messages to isolate problems.

Client Debugging

Most clients print debug messages when invoked with the -v (verbose mode) option: ["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..."

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. ["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. ["Public-key authentication"]
  • 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. ["Public-key authentication"]
  • Public-key authentication isn't working.
  • Usessh -v, and check your keys, files, and permissions. ["Public-key authentication"]
  • Password authentication isn't working.
  • Usessh -v. There are a variety of possible causes. ["Password authentication"]
  • Trusted-host authentication isn't working (SSH1 RhostsRSA, SSH2 hostbased).
  • Usessh -v. Check your four control files, hostnames, and setuid status of the SSH client program or ssh-signer2. ["Trusted-host authentication"]
  • How do I authenticate without typing a password or passphrase?
  • ssh-agent, unencrypted keys, trusted-host authentication, or Kerberos. ["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. ["Port forwarding"]
  • forwarding isn't working.
  • Don't set your remote DISPLAY variable manually. (And there are other things to check.) ["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. ["scp"]
  • feature of ssh or scp isn't working, but I'm sure I'm using it correctly.
  • Usessh -v. Also the system configuration may be overriding your settings.