Skip to main content
undefined
undefined

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

undefined

Secure .gov websites use HTTPS
A lock ( ) or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

Troubleshooting SSH Connections

May 17, 2021

UPDATE: As of November 28, 2022, cloud.gov only supports connecting to applications using SSH over port 2222. It is no longer possible to use port 22 to connect to applications over SSH.

This post will help you troubleshoot issues when connecting to your app using SSH.

Some things to check:

  • Check which version of the cf  CLI tool you are using. Currently v7 and v8 versions of the CLI tool are supported.
  • Make sure you have SSH access enabled. You can check to see if SSH is enabled by running cf ssh-enabled APP_NAME . Enable it by running cf enable-ssh APP_NAME .
  • If you recently enabled SSH access to your application using the approach above, ensure that you have also run cf restart APP_NAME  so that the changes can take effect.
  • Make sure you are not in an environment that blocks outgoing traffic on port 2222 (the default port for cf ssh  traffic). Some offices or corporate locations may block traffic on this port.

Working around port blocking

cf ssh  uses port 2222. If your network blocks port 2222, you may receive an error message such as Error opening SSH connection  or psql: could not connect to server: Connection refused .

It is possible your internet service provider or network provider will block traffic on port 2222. You can work around this by using a VPN (like the GSA VPN) or using a native ssh client and following the instructions below.

  1. Retrieve the APP_GUID for your app: cf app APP_NAME --guid .
  2. Retrieve a one-time ssh passcode using cf ssh-code . You will be prompted for this code below.
  3. Use ssh  (not cf ssh ) to connect to your app container. Substitute the value for your APP_GUID: ssh -p 22 cf:APP_GUID/0@ssh.fr.cloud.gov . You will be prompted to enter a password. Use the one-time ssh passcode you generated in step 2.

This will open an ssh connection using port 22 to your app instance with index of 0. If you need to connect to a different instance, replace the 0  in the command above.

Note - If this approach does not work for you, and you see an error that says Permission denied, please try again., then you should review the section below on changes to your application in the CAPI.

Changes to your app in the CAPI

If you are still experiencing trouble connecting to your app using SSH, it may be the result of some changes in a newer version of the Cloud Foundry API (CAPI). In prior versions of the CAPI, app instances used a single process. In version 3 of the CAPI, there can be more than 1 process that makes up an app. This may occasionally cause issues when trying to SSH to your app.

If a modification or update was made to an app using a v3 command or process - even if that change was made by someone else (e.g., another member of a development team) - the app’s schema in the Cloud Controller might have changed to version 3, and a standard cf ssh may no longer work.

Using supported versions of the cf CLI

You may want to upgrade your version of the CF CLI and ensure you are using either the v7 or v8 CF CLI. The v7 and v8 CF CLI automatically connects to the web process.

You may also want to upgrade your version of the CLI tool. v7 of this tool automatically connects to the web  process.

Using other utilities

If you need to use a tool like scp  or a native ssh  utility to connect to your application instance, you may need to take a slightly different approach. You want to obtain the GUID for the web process for your application.

  1. Retrieve the PROCESS_GUID for the web process for your app: cf curl /v3/apps/$(cf app APP_NAME --guid)/processes | jq --raw-output '.resources | .[] | select(.type == "web").guid'  (note - assumes that you have jq installed).

(The remaining steps are identical to those listed in the prior section, except instead of using the APP_GUID, you will use the PROCESS_GUID you just identified to connect to your application.)

  1. Retrieve a one-time ssh passcode using cf ssh-code . You will be prompted for this code below.
  2. Use ssh  (not cf ssh ) to connect to your app container. Substitute the value for your APP_GUID: ssh -p 22 cf:PROCESS_GUID/0@ssh.fr.cloud.gov . You will be prompted to enter a password. Use the one-time ssh passcode you generated in step 2.