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:
- Should I troubleshoot SSH? Determine whether troubleshooting is the right decision or if migration/redeployment is more appropriate.
- 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.
When to Consider Migration or Redeployment
To resolve your issue quickly, first determine whether troubleshooting the connection is the right solution for your problem or if you should instead focus on recovering your data for redeployment.
Some issues, such as an accidental recursive rm or chmod command or incorrect network configuration, can lock you out of a Droplet permanently. Other issues may seem like connection problems, but are actually more complex issues with no clear resolution, like corrupted file systems, incorrect file permissions and ownership, and broken system packages and required libraries.
You can typically identify boot errors through the Droplet console startup output. File system issues and startup failures that prevent a working console login session are signs that troubleshooting your network configuration 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 is the fastest way back to your previous working environment.
What to Do Before Troubleshooting
If you’ve decided that troubleshooting is right for your situation, go through the following steps:
Check the control panel. Before anything else, make sure there are no ongoing issues, like an outage in the region impacting your Droplet.
Check if Droplet is disabled because of abuse. Droplets are sometimes disabled due to the detection of abusive activity. If your Droplet has been disabled, an email has been sent to the email address linked to your DigitalOcean account with the title
Networking Disabled: <your-droplet-name>. You can also log in to the support portal to see if any support tickets have been created for your resources.If your Droplet has been disabled due to suspected abuse, contact our support team for further information.
Recover root access. If you do not have the current root password, reset it using the reset root password function in the control panel.
Access the Recovery Console. If you cannot log in to the Droplet, the Recovery Console is another way to gain access (as long as your Droplet is running and you have a working root password).
Reboot your Droplet. Many connectivity problems can be resolved after a reboot. If you’re experiencing connectivity issues, try rebooting the Droplet and see if this resolves the issue.
Before rebooting your Droplet, we highly recommend taking a snapshot of it. This allows you to redeploy your Droplet in its current configuration if rebooting the Droplet causes more serious problems.
To reboot your Droplet, log in to it and run the following command:
sudo rebootReview file management and permissions. Some of these solutions may require you to review or edit files on the system or manage permissions.
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.
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
-voption with multipleventries to increase the verbosity of the output, as inssh -v [emailprotected]. While most issues are revealed with a singlev, 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.
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.
When connecting an SSH client to an SSH server, the first step is establishing basic network connectivity. This article covers how to identify some common situations that would cause issues at this point in the process, how to resolve those situations, and additional resources to prevent them in the future.
Errors
Hostname Resolution
Most resolution errors occur when the reference to the SSH host can’t be mapped to a network address. While this is almost exclusively DNS related, the root cause isn’t always a DNS issue.
In an OpenSSH client, a command like ssh [emailprotected] may return an error like this:
ssh: Could not resolve hostname example.com: Name or service not knownIn PuTTY, you might see an error window with text like this:
Unable to open connection to example.com Host does not existHere are some steps you can take to troubleshoot this error.
- Verify the hostname is properly spelled. Typographical errors can strike at any time.
- Verify that you can resolve the hostname on your client machine using the system
pingcommand. Using third-party sites like WhatsMyDns.net to check beyond your own DNS caching can also help confirm the results.
If you’re having DNS resolution issues at any level, you can also use the Droplet IP address as an interim solution, as in ssh [emailprotected] instead of ssh [emailprotected].
The following tutorials are a good resource to begin working out DNS configuration errors:
- An Introduction to Managing DNS
- How to Point to DigitalOcean Name Servers From Common Domain Registrars
- How To Set Up a Host Name with DigitalOcean
Connection Timeout
A connection timeout means that the client attempted to establish a network socket to the SSH server, but the server failed to respond within the timeout period.
In an OpenSSH client, a command like ssh [emailprotected] may give an error like this:
ssh: connect to host 203.0.113.0 port 22: Connection timed outIn PuTTY, you might see an error window with text like this:
Network error: Connection timed outHere are some steps you can take to troubleshoot this error.
- Verify that the host IP address is correct for the Droplet.
- Verify that your network supports connectivity over the SSH port being used. Some public networks may block port
22or custom SSH ports. You can do this by, for example, testing other hosts using the same port with a known working SSH server. This can help you determine if the issue isn’t specific to your Droplet. - Verify the Droplet firewall rules. Check that they’re not set to a default policy of DROP and the port is not added to allow connections.
Connection Refused
A connection being refused has some subtle differences from a timeout. This means that the request is being routed to the SSH host, but the host does not successfully accept the request.
In an OpenSSH client, a command like ssh [emailprotected] may return an error like this:
ssh: connect to host 203.0.113.0 port 22: Connection refusedIn PuTTY, you might see an error window with text like this:
Network error: Connection refusedIn this situation, you may have the same root issue as with connection timeout errors, but there are some additional things you can check:
- Verify that the host IP address is correct for the Droplet.
- Verify that your network supports connectivity over the SSH port being used. Some public networks may block port
22or custom SSH ports. You can do this by, for example, testing other hosts using the same port with a known working SSH server. This can help you determine if the issue isn’t specific to your Droplet. - Verify the Droplet firewall rules. Check that they’re not set to a default policy of DROP and the port is not added to allow connections.
- Verify that the service is currently running and bound to the expected port.
Solutions
Checking Your Firewall
Some connectivity problems can be caused by firewall configurations. If your firewall is set up to block certain ports or services, it can prevent you from connecting. You can learn more about firewalls in What is a Firewall and How Does It Work?.
If you add a firewall rule that allows your local machine to connect by IP address, verify that the IP address assigned by your ISP has not changed. If it has, then you need to modify that firewall rule to permit the new IP address or address range.
How you check your firewall rules depends on which firewall your Droplet uses. Ubuntu servers usually run UFW; CentOS servers often use FirewallD. If you’re not using either, it’s likely that you’re using iptables.
For whichever firewall your system has, make sure to familiarize yourself with how to modify its rules. You also need to know which port your SSH service is using. By default, it’s 22, but you can follow the Checking the SSH Service Port section below to confirm.
- iptables
- FirewallD
- UFW
For Linux systems not running UFW or FirewallD, list your firewall rules using the iptables command with sudo or as the root user.
iptables -nLThe following output would indicate that there are no rules in place that would block SSH traffic:
Chain INPUT (policy ACCEPT)target prot opt source destination Chain FORWARD (policy ACCEPT)target prot opt source destination Chain OUTPUT (policy ACCEPT)target prot opt source destinationIf you see rules or a default policy of REJECT or DROP, you should ensure that the INPUT chain allows the port your SSH service is running on, which is 22 by default.
For FirewallD users, use the firewall-cmd command to list the services:
firewall-cmd --list-servicesThe output should reveal the list of services including SSH (default port 22) to indicate that the firewall supports SSH traffic:
dhcpv6-client http sshIf you are using a custom port for SSH, you can check with the --list-ports option. If you created a custom service definition, you should still see SSH normally with --list-services.
Users working with UFW should use ufw status to inspect their firewall:
ufw statusThe output similarly shows the ports available:
Status: activeTo Action From-- ------ ----22 LIMIT Anywhere 443 ALLOW Anywhere 80 ALLOW Anywhere Anywhere ALLOW 192.168.0.0 22 (v6) LIMIT Anywhere (v6) 443 (v6) ALLOW Anywhere (v6) 80 (v6) ALLOW Anywhere (v6)Make sure that your SSH port is on the list.
Checking the SSH Service Status
If you can’t SSH to your Droplet, you should check that the SSH service is running. How to very the service is running varies from system to system.
On older OS versions (Ubuntu 14 and below, CentOS 6, Debian 6) this may use the service command backed by Upstart. More modern distributions with systemd use the systemctl command. Red Hat-based distributions (for example, CentOS and Fedora) call the service sshd while Debian and Ubuntu call it ssh.
- Using systemctl
- Using service
Similarly, on a server using systemd (like CentOS 7), use the systemctl command to check the status:
systemctl status sshdA running service shows output like this, with active (running) on the Active: line.
sshd.service - OpenSSH server daemon Loaded: loaded (/usr/lib/systemd/system/sshd.service; enabled) Active: active (running) since Mon 2017-03-20 11:00:22 EDT; 1 months 1 days ago Process: 899 ExecStartPre=/usr/sbin/sshd-keygen (code=exited, status=0/SUCCESS) Main PID: 906 (sshd) CGroup: /system.slice/sshd.service ├ 906 /usr/sbin/sshd -D ├26941 sshd: [accepted] └26942 sshd: [net] If the service is not running, the Active line displays inactive followed by recent journal entries for the service:
sshd.service - OpenSSH server daemon Loaded: loaded (/usr/lib/systemd/system/sshd.service; enabled) Active: inactive (dead) since Fri 2017-04-21 08:36:13 EDT; 2s ago Process: 906 ExecStart=/usr/sbin/sshd -D $OPTIONS (code=exited, status=0/SUCCESS) Process: 899 ExecStartPre=/usr/sbin/sshd-keygen (code=exited, status=0/SUCCESS) Main PID: 906 (code=exited, status=0/SUCCESS) In this case, restart it with systemctl start sshd.
For systems using the service command, check the status of the SSH process with the following command (run as root or with sudo):
service ssh statusOutput like this, which includes the PID (process ID), indicates that the process is running as expected:
ssh start/running, process 1262If it isn’t running, you’ll see output indicating the process is stopped:
ssh stop/waitingIn this case, restart it with service ssh start.
Checking the SSH Service Port
There are two general ways to check which port the SSH service is running on. One is checking the SSH configuration file, and the other is examining the running process.
On most systems, the SSH configuration file is /etc/ssh/sshd_config. The default port is 22, but can be overridden by any configuration line in this file specifying a Port directive with a number.
You can search lines like this using grep:
grep Port /etc/ssh/sshd_configYou’ll see output like this with the port number:
Port 22If you know the service is running, you can confirm that the service is running on the expected port using ss (run with sudo or as the root user). Similar output is provided for the netstat -plnt command as well, but ss is the preferred command for querying socket information from the kernel.
ss -plntThe output you are looking for should reference the program name listening on the configured port. For example, this output shows that the SSH service is listening on all interfaces, *, on port 22.
State Recv-Q Send-Q Local Address:Port Peer Address:Port LISTEN 0 128 *:22 *:* users:(("sshd",pid=1493,fd=3))LISTEN 0 128 :::22 :::* users:(("sshd",pid=1493,fd=4))The interface references * and 0.0.0.0 indicate all interfaces on the Droplet. 127.0.0.1 indicates that the service is not publicly accessible. The relevant sshd_config directive is ListenAddress and should be commented out to default to all interfaces, or set to the public IP address of the Droplet.
Conclusion
If you need further help, you can open a support ticket. Make sure to include the following information:
- The username, host, and port you are using to connect.
- The authentication mechanism you expect to use.
- The full output of the errors linked to the stage of error, including verbose output of the SSH client
- All of the information you’ve gathered from troubleshooting so far.
- Anything you were unclear about while referencing this article.
Including all the above diagnostic information and clarifying where you are encountering the issue when trying to connect can help us quickly get up to speed with where your need on the issue is.
How to Troubleshoot SSH Authentication Issues
Problems with SSH authentication includes permission denied with SSH keys and passwords.
How to Troubleshoot SSH Protocol Issues
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.
How to Troubleshoot SSH Shell Environment Issues
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.
