How To Troubleshoot SSH Shell Environment Issues On Your Droplet
This is a continuation of our SSH troubleshooting article series.
The first article will help you determine when to troubleshoot an issue instead of migrating or redeploying, and provides resources for the information you'll need to have to troubleshoot effectively. 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:
- 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, which is this tutorial. 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.
Once your SSH connection is established and you are authenticated, the remote shell environment is then executed. There are a couple of issues that can occur at this point as described below, followed by actions you can take to address them.
To troubleshoot SSH issues, you will need to make sure your Droplet is responding normally from the web console with a working network configuration. You can do this by following the How and When To Troubleshoot SSH Issues tutorial.
Before troubleshooting SSH, you should always check your cloud panel for ongoing issues in the region impacting your Droplet, the hypervisor status, and the state of the Droplet through the web console.
Below are some common SSH environment errors you might encounter.
chdir To Home Directory
In some cases, you may cause damage to directory ownership or permissions that can cause problems when trying to access the home directory. This can result in errors like the following:
ErrorCould not chdir to home directory /home/user: Permission denied
ErrorCould not chdir to home directory /home/user: Input/output error
ErrorCould not chdir to home directory /home/user: No such file or directory
Some issues might stem from the user home directory not existing, its ownership being incorrect, or its permissions being too restrictive. This also might happen when filesystem issues have corrupted the home directory.
To troubleshoot this issue, try checking the home directory's existence, permissions, and ownership.
This Account Is Currently Not Available
In some cases, users may be configured to not have a login shell. This can manifest in several ways in the shell not responding. You might see an error like this:
[secondary_label] This account is currently not available.
Here are some potential causes of this issue:
- The user is a system user and not intended for shell access.
- The user shell is assigned to
falseor another non-shell binary. In this case, you can update the user shell.
Resource Temporarily Unavailable
The SSH service, like any service, requires system resources to operate. This means that when your Droplet is under resource-constrained conditions, the service may fail to open a working shell environment. These conditions include exhausting the system memory, reaching the system's open file limit, or crashing the runtime environment.
You might see an error message like this:
Errorssh: connect to host example.com port 22: Resource temporarily unavailable
Resource issues can be difficult to debug, and depends on the kind of access you have to your Droplet. Read below on how to handle resource issues.
Below are some troubleshooting methods and solutions to common SSH environment errors.
Checking The Home Directory
In some cases, you may need to use the web console to log in as root to evaluate the home directory with sufficient permissions to address any issues. Make sure
/home and the path for the user's home directory exist using
stat or a similar utility.
If the directories exist, make sure the user's home directory has appropriate permissions (at least
700) and ownership (the user, not root).
Updating The User Shell
From the web console, log in as root or a user with
sudo access. You can review the
/etc/passwd file directly or use the
getent command to list the details:
- getent passwd user
You'll see output like this. Note the
To update this, you can use the system command
usermod and specify the correct shell to use, like
- usermod -s /bin/bash user
If you run the
getent command again, you'll see the change reflected in the output:
You can then try logging in again.
Dealing With Resource Issues
Dealing with resource issues is a very context specific situation.
If the source of resource contention is due to network requests (e.g. an attack against a web application), you may be able to disable the service or block traffic at the firewall from the web console. This may allow enough room for you to assess the impact of the situation and implement mitigation strategies or consider scaling your deployment.
If you cannot log in from the web console, the last resort option is to power cycle or reboot the Droplet. Depending on the cause of the resource exhaustion, this may simply hit the same environment or initially support a connection that gives an
Unable to fork process error when you attempt to run a command. Catching the web console or SSH connection to the Droplet after a reboot but before it becomes unresponsive is key to troubleshooting the root cause.
You can learn more about scaling, load balancing, and expanding your Droplet's resources in the following tutorials:
- How To Automate the Scaling of Your Web Application on DigitalOcean
- How To Resize Your Droplets on DigitalOcean
- An Introduction to HAProxy and Load Balancing Concepts
If you need further help establishing a working SSH connection to your Droplet, you can open a ticket with our Support Team. Make sure to include:
- 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.