We hope you find this tutorial helpful. In addition to guides like this one, we provide simple cloud infrastructure for developers. Learn more →

How and When To Troubleshoot SSH Issues On Your Droplet

PostedApril 28, 2017 9.5k views Linux Basics DigitalOcean Arch Arch Linux CentOS CoreOS Debian FreeBSD RHEL Ubuntu Ubuntu 12.04 Ubuntu 16.04


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:

  1. Determining whether troubleshooting is the right decision (or if migration/redeployment is a more appropriate solution), and

  2. 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 rm or 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.

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 -vvv.

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

Some of these solutions may require you to review or edit files on the system or manage 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 /root/.

Checking Logs

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.

You can learn more about the logs on your server with this Linux logging tutorial and this journalctl and systemd logging tutorial.


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:


Creative Commons License