SSH is the primary method available for managing DigitalOcean Droplets. Dealing with SSH errors or failures can be frustrating because the errors themselves often prohibit you from accessing your servers. This troubleshooting series covers some of the most common issues you may encounter with SSH, how to address them, when to consider re-deploying, and how to get further support.
This tutorial specifically covers two important prerequisites to troubleshooting your SSH issues:
The other parts of this series cover how to identify and resolve specific SSH errors, and are broken down by which phase of a successful SSH connection you need to debug.
In some cases, such as an accidental recursive
chmod command, issues with the SSH service cannot be resolved. Other issues may appear at the outset as SSH connectivity issues, but reveal much deeper issues with no clear resolution. Things like this include:
To get your deployment back online quickly, you will want to determine if trying to revive the SSH service is the right solution for your problem or if you should begin focusing on recovering your data for redeployment.
You can typically identify boot-up errors through the web console startup output. Issues pertaining to the file system or any startup failures that prevent a working console login session are signs that troubleshooting SSH may not be the better option. In situations like this, the best approach is to try to salvage what you can. In some cases, a good backup or snapshot strategy can permit a more rapid recovery of a previous working environment, or our Load Balancers may make spinning up a new Droplet and re-deploying that faster solution to getting your deployment running again.
If you’ve decided that troubleshooting is right for your situation, you’ll need to know a few things before you dive in.
To get familiar with SSH, you can read up on how to connect to your Droplet with SSH and how to use SSH keys with your Droplet. These guides can add some clarification to your setup process to help you avoid or understand some issues.
Many of the steps outlined in the detailed troubleshooting articles will need to be completed from within the running Droplet. While SSH is down, the Droplet web console is an alternative way to gain access, provided your Droplet is running and you have a working root password.
If you do not have the current root password, you’ll need to recover it using the Reset Root Password function in the Control Panel. Make sure to follow the FreeBSD root password recovery tutorial if you use FreeBSD, as the reset process is slightly different.
The level of detail a client provides about the SSH session is generally quiet by default. When you run into an issue, however, this relative silence can hide insight into the problem.
For the OpenSSH client, you can use the
-v option with multiple
v entries to increase the verbosity of the output, as in
ssh -v email@example.com. While most issues will be revealed with a single
v, some issues may benefit from
The PuTTY client supports an Event Log accessible from the context icon in the application window bar. There’s also an option for configuring session logging from the settings page when initiating the connection.
Note: Before editing any files, be sure to make a backup of the file prior to saving in case any mistakes in edits need to be quickly reverted.
In these articles, references to the current user’s home directory is listed
~. For the username sammy, the path
~/.ssh would usually translate to
/home/sammy/.ssh. The root user path is typically found at
Once you can get into the Droplet, the system will typically have logs available that can shed more light on the situation you may be facing on the server. It’s a good idea to look at log files to begin identifying what the error is so you can then look up a solution.
Now that you’ve decided if you should troubleshoot and you’re familiar with the skills you’ll need to do so, you can begin to resolve any SSH errors by following the appropriate tutorial:
This includes errors such as connections being refused or timing out.
This includes the client suddenly getting dropped or closed, the client complaining about cipher negotiation, or issues with an unknown or changed remote host.
This includes issues with password authentication or SSH key authentication denial.
This includes issues like being unable to fork a process, the system reporting it's not a valid shell, or issues reaching the home directory.