How and When to Troubleshoot SSH Issues

DigitalOcean Droplets are Linux-based virtual machines (VMs) that run on top of virtualized hardware. Each Droplet you create is a new server you can use, either standalone or as part of a larger, cloud-based infrastructure.

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. This includes:

• Corrupted file systems
• Erroneous file system permissions and file ownership
• Broken system packages and required libraries

To get your deployment back online quickly, 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 Droplet 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 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 DigitalOcean Load Balancers may make spinning up a new Droplet and re-deploying that faster solution to getting your deployment running again.

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 Droplet Console

Many of the steps outlined in the detailed troubleshooting articles need to be completed from within the running Droplet. While SSH is down, the Droplet 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, reset it using the reset root password function in the control panel.

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 [email protected]113.0. While most issues are 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

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 typically has 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.

Next Steps

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: