How and When To Troubleshoot SSH Issues On Your Droplet
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:
Determining whether troubleshooting is the right decision (or if migration/redeployment is a more appropriate solution), and
Reviewing the resources and skills necessary to efficiently resolve SSH issues, like having root access to the server and being familiar with file manipulation.
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.
When to Consider Migration or Redeployment
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:
- Corrupted file systems
- Erroneous file system permissions and file ownerships
- Broken system packages and required libraries
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 balancer feature may make spinning up a new Droplet and re-deploying that faster solution to getting your deployment running again. You can alternatively open a ticket with our Support Team and request the recovery environment.
What to Know Before Troubleshooting
If you've decided that troubleshooting is right for your situation, you'll need to know a few things before you dive in.
Reviewing Related SSH Setup Guides
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.
Accessing The Web Console
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.
Recovering Root Access
If you do not have the current root password, you'll need to recover it. The DigitalOcean Cloud Panel tutorial describes how to find and use the Reset Root Password function. Make sure to follow the FreeBSD root password recovery tutorial if you use FreeBSD, as the reset process is slightly different.
Using Verbose Output
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 user@your_server_ip. 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.
Managing Files and Permissions
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:
- Troubleshooting SSH Connectivity. This deals with errors such as connections being refused or timing out.
- Troubleshooting SSH Protocol Initiation. This includes the client suddenly getting dropped or closed, the client complaining about cipher negotiation, or issues with an unknown or changed remote host.
- Troubleshooting SSH Authentication. This includes issues with password authentication or SSH key authentication denial.
- Troubleshooting SSH Shell Environment. 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.