vmware-marketplace

Bitnami How-To Guides for VMware Marketplace

Troubleshoot SSH Issues

Introduction

SSH (Secure Shell) access is an essential tool for performing server maintenance and administration tasks. Most of the pages in our documentation and support platforms require the user to access the server through SSH at some point. One of the most common use cases is to remove the Bitnami banner, which requires SSH access.

For security reasons, Bitnami configures most of our cloud instances to allow only certificate-based authentication. In most clouds, the user must connect using bitnami as the username, as explained in this guide.

You are running into an SSH issue when you can’t access your server via this protocol. This section also includes similar issues with SFTP (Secure File Transfer Protocol) access.

Another common operation is to create SSH tunnels. For security reasons, we configure some sensitive services to be only internally accessible (i.e. they accept requests only in the localhost - 127.0.0.1). One example of these services is the following:

  • phpMyAdmin

The only way to access these services from your local machine is by using SSH Tunnels. This guide also cover this kind of issues.

In this how-to guide, you will learn how Bitnami configures SSH access, what the common issues are, and how to those issues.

How to detect

You have an SSH issue when you can’t access your server using this protocol. You will see error messages like the following:

Permission denied (publickey)

Or:

ssh: connect to host [...] port 22: Connection refused

Or:

ssh: connect to host [...] port 22: Operation timed out

Or:

ssh_exchange_identification: read: Connection reset by peer

Or:

REMOTE HOST IDENTIFICATION HAS CHANGED

Or:

WARNING: UNPROTECTED PRIVATE KEY FILE!

In SSH tunneling, apart from the errors above, you might see errors like these:

bind: Address already in use

SSH tunnel error

Common issues

These are the most common SSH issues that Bitnami users face:

  • Wrong client configuration: A common mistake is to configure the SSH/SFTP client (SSH, PuTTY, Filezilla…) without setting all the necessary parameters correctly, such as host, port, username or private key. Another frequent problem occurs when you use a non-supported certificate, by trying to add a .pem keyfile in PuTTY instead of a .ppk keyfile, for example. This guide includes information on how to convert between keyfile formats.
  • Cloud firewall: Most cloud instances come with port 22 open by default. Some users change that configuration incorrectly, resulting it SSH being blocked.
  • No key-pair: You can create an instance without a key-pair, making SSH access impossible in most cloud platforms. Alternatively, you might have lost the SSH key-pair used to created the instance.
  • SSH server: Some users change the instance SSH server’s configuration (like adding a new authorized key) and accidentally break it. This is complex to fix as it’s very difficult to recover access without creating a new instance.
  • SSH tunnel: Issues here might include SSH client misconfigurations or server-side redirections that render the tunnel useless.
  • SSH in OVA virtual machines: Our local virtual machines have the SSH server disabled by default, so some users encounter problems when enabling it following this guide.

Troubleshooting checklist

The following checklist covers the majority of cases described above and will help you to find and debug most SSH issues.

Is the SSH Client configured correctly?

Some SSH issues occur because of a missing parameter in the connection settings. If you get an error like this:

Permission denied (publickey)

Make sure you have the following parameters set:

  • IP address of the server. Check that the IP address hasn’t changed by referring to your cloud provider control panel.
  • Username. Bitnami instances come with the user bitnami.
  • Key-pair used to create the instance.

Review the SSH connection section for information about how to configure the most popular SSH clients. If you’re trying to create an SSH tunnel, you need to follow this guide.

Was the instance created with an SSH key-pair?

In most cloud platforms, you’ll need to explicitly specify a key-pair when creating the instance. If no key-pair was specified, then you will not be able to gain access through SSH. If you want to maintain the changes already made in your instance, follow these steps:

  • Create a snapshot of your current instance using your cloud provider control panel.
  • Create a new instance using this snapshot, making sure that you select an SSH key-pair.

Now you have a new instance that you can access through SSH.

Can’t you find the SSH key-pair used to create the instance?

If you don’t have the key-pair the instance was created with, you will not able to connect through SSH. If you want to maintain your instance data, follow the steps described in this section.

Is port 22 open in the instance?

If, when connecting through SSH, you get errors like this:

 ssh: connect to host [...] port 22: Operation timed out

Then you may have cloud firewall rules that restrict access to port 22. To find out if that’s the case, follow the steps given in this guide.

Is the SSH tunnel redirecting to HTTPS?

If you created a tunnel correctly but, when accessing the tunnel via web browser you get this error:

SSH tunnel error

Check the URL in the browser bar. If you see that it is using HTTPS, then you probably configured HTTPS redirection in Apache following these instructions. If that’s the case, change the tunnel configuration to forward to port 443 instead of port 80. The example below uses the ssh command-line client (replace the PATH_TO_SSH_KEY and IP_ADDR placeholders):

  ssh -i PATH_TO_SSH_KEY -L 8080:localhost:443 bitnami@IP_ADDR

Have you enabled the SSH server in your OVA?

If you are using a Bitnami local virtual machine and you get this error when accessing through SSH:

  ssh: connect to host [...] port 22: Connection refused

That means that the SSH server is not running. In our virtual machines the SSH server is disabled by default. Enable it by following this guide.

Is your SSH server broken?

If you were able to access through SSH and you suddenly start getting errors like this:

Permission denied (publickey)

Or:

ssh: connect to host [...] port 22: Connection refused

Check that you did not change any of the SSH server settings, for example files like:

  • /etc/ssh/sshd_config
  • /home/bitnami/.ssh/authorized_keys

An error modifying these files could break the SSH server. If that happens, you will lose the connection to it. Depending on the cloud, you can fix the issue in two ways:

Easy way: Using an embedded SSH or VNC client

If your cloud console allows VNC connections or web-based SSH (like Google Cloud), then you can still connect to the instance and fix the issue manually.

Hard way: Launching a new instance

This method requires more advanced knowledge. Make sure you check your cloud provider documentation:

  • Launch a new instance.
  • Detach the virtual disk from the broken instance.
  • Attach the disk to the new instance.
  • Mount the new disk.
  • Now you have access to the broken system filesystem. Fix the issue in the SSH configuration.
  • Attach the disk back to the old instance.

Does your SSH key-pair have the proper permissions?

If you are in a Linux or macOS environment and encounter the following error:

WARNING: UNPROTECTED PRIVATE KEY FILE!

That means your key-pair is vulnerable. Set more restrictive permissions on your key-pair by executing this command (replace the PATH_TO_SSH_KEY placeholder):

chmod 0600 PATH_TO_SSH_KEY

Are you getting a remote host identification error?

If you get this error when accessing through SSH:

REMOTE HOST IDENTIFICATION HAS CHANGED

Check whether one of the following has occurred:

  • You just reassigned a static IP or DNS record from one instance to the one you are trying to connect to.
  • It is the first time you are trying to access the instance. In this case it may have reused an ephemeral IP.

If so, open your .ssh/known_hosts file:

  • Look for any entry that references the address you are trying to connect to.
  • Remove the line.
  • Save the file.

This should fix the identification error.

If none of the above applies, contact your cloud provider as it could be a man-in-the-middle attack.

The following resources may be of interest to you:

Last modification July 26, 2023