SSH Troubleshooting Support Articles

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.

There are two prerequisites to troubleshooting SSH issues:

  1. Should I troubleshoot SSH? Determine whether troubleshooting is the right decision or if migration/redeployment is more appropriate.
  2. What should I do before troubleshooting SSH?. Make sure the issue is truly with SSH, then review the information and skills necessary to resolve SSH issues, like having root access to the server and understanding how to access and edit files.

This article covers these two prerequisites. The other parts of this series cover how to identify and resolve specific SSH errors.

When to Troubleshoot SSH or Consider Redeployment

You should consider migration or redeployment instead of troubleshooting SSH when there are issues with the file system or any startup failures that prevent a working console login session. These issues may seem like a problem with SSH at first, but in reality are more complicated issues with no clear resolution. Some examples include:

  • Accidental recursive rm or chmod
  • Corrupted file systems
  • Incorrect file system permissions or file ownership
  • Broken system packages or required libraries

You can typically identify these kinds of boot-up errors through the Recovery Console startup output.

In these situations, we recommend salvaging what you can. Focus on recovering your data for redeployment. In some cases, a good backup or snapshot strategy can be a fast route to permit a previous working environment.

What to Do Before Troubleshooting

If you’ve decided that troubleshooting is right for your situation, go through the following steps:

  1. Check the control panel. Before anything else, make sure there are no ongoing issues, like an outage in the region impacting your Droplet.

  2. Review setup and SSH usage. Use articles like how to connect to your Droplet with SSH and how to use SSH keys with your Droplet to review and avoid setup issues.

  3. Recover root access. If you do not have the current root password, reset it using the reset root password function in the control panel.

  4. Access the Recovery Console. While SSH is down, the Recovery Console is another way to gain access (as long as your Droplet is running and you have a working root password). Many steps in this troubleshooting series require the Recovery Console.

  5. Use verbose SSH output. The level of detail an SSH client provides about the SSH session is generally quiet by default. It’s helpful to have more information when debugging an issue.

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

  6. Review file management and permissions. Some of these solutions may require you to review or edit files on the system or manage permissions.

  7. Check logs. Once you can get into the Droplet, check the system’s log files for more information to identify the error 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

After you decide to troubleshoot an SSH issue instead of migrating or redeploying, you can identify and resolve specific SSH errors based on which phase of a successful SSH connection you need to debug:

Problems with SSH connectivity include hostname resolution errors and connections being refused or timing out.
Problems during SSH protocol initiation include the client suddenly getting dropped or closed, the client returning errors about cipher negotiation, or issues with an unknown or changed remote host.
Problems with SSH authentication includes permission denied with SSH keys and passwords.
Problems with SSH shell environments include being unable to fork a process, the system reporting it’s not a valid shell, or issues reaching the home directory.