ssh-apps.html.md.erb

---
title: Accessing your apps with SSH
owner: Diego
---


The Cloud Foundry Command Line Interface (cf CLI) lets you securely log in to remote host virtual machines (VMs) running <%= vars.app_runtime_full %> (<%= vars.app_runtime_abbr %>) app instances. The commands that activate SSH access to apps, and activate, deactivate, and verify permissions for such access are described here.

<p class="note important">
The <code>cf ssh</code> command in cf CLI v7+ include the <code>all_proxy</code> environment variable, which allows you to specify a proxy server to activate proxying for all requests. For more information, see <a href="http://cli.cloudfoundry.org/en-US/v7/ssh.html">ssh</a> in the Cloud Foundry CLI Reference Guide and <a href="../../cf-cli/http-proxy.html#v3-ssh-socks5">Use SOCKS5 with cf v3-ssh</a> in <em>Using the cf CLI with a proxy server</em>.</p>

The cf CLI looks up the `app_ssh_oauth_client` identifier in the Cloud Controller `/v2/info` endpoint, and uses this identifier to query the UAA server for an SSH authorization code. On the target VM side, the SSH proxy contacts the Cloud Controller through the `app_ssh_endpoint` listed in `/v2/info` to confirm permission for SSH access.

<%= vars.mutual_tls_ssh %>


## <a id="ssh-commands"></a> App SSH commands

<table id='ssh-commands' class="table">
  <thead><tr>
    <th>cf CLI command</th>
    <th>Purpose</th>
  </tr></thead>
  <tr>
    <td>
      <code>cf enable-ssh</code><br/>
      <code>cf disable-ssh</code><br/>
      <code>cf allow-space-ssh</code><br/>
      <code>cf disallow-space-ssh</code>
    </td>
    <td><a href="#enable-disable-ssh">Activate and deactivate SSH access</a></td>
  </tr>
  <tr>
    <td>
      <code>cf ssh-enabled</code><br/>
      <code>cf space-ssh-allowed</code>
    </td>
    <td><a href="#check-ssh-permissions">Verify SSH access permissions</td>
  </tr>
  <tr>
    <td><code>cf ssh</code></td>
    <td><a href="#ssh-command">Log in to an application container with cf SSH</td>
  </tr>
  <tr>
    <td><code>cf ssh-code</code></td>
    <td><a href="#other-ssh-access">App SSH access without cf CLI</a> using non-<code>cf SSH</code> tools like <code>ssh</code>, <code>scp</code>, and <code>sftp</code></td>
  </tr>
</table>


## <a id="enable-disable-ssh"></a> Activate and deactivate SSH access

A cloud operator can deploy <%= vars.app_runtime_abbr %> to either allow or prohibit app SSH across the entire deployment. <%= vars.config_ssh_link %>

Within a deployment that permits SSH access to apps, Space Developers can activate or deactivate SSH access to individual apps, and Space Managers can activate or deactivate SSH access to all apps running within a space.

You must restart your app after enabling SSH access.

### <a id="config-ssh-access-apps"></a> Configuring SSH access at the app level

[cf enable-ssh](http://cli.cloudfoundry.org/en-US/cf/enable-ssh.html) activates SSH access to all instances of an app:
<pre class="terminal">
$ cf enable-ssh MY-AWESOME-APP
</pre>

[cf disable-ssh](http://cli.cloudfoundry.org/en-US/cf/disable-ssh.html) deactivates SSH access to all instances of an app:
<pre class="terminal">
$ cf disable-ssh MY-AWESOME-APP
</pre>

### <a id="config-ssh-access-spaces"></a> Configuring SSH access at the space level

[cf allow-space-ssh](http://cli.cloudfoundry.org/en-US/cf/allow-space-ssh.html) allows SSH access into all apps in a space:
<pre class="terminal">
$ cf allow-space-ssh SPACE-NAME
</pre>

[cf disallow-space-ssh](http://cli.cloudfoundry.org/en-US/cf/disallow-space-ssh.html) disallows SSH access into all apps in a space:
<pre class="terminal">
$ cf disallow-space-ssh SPACE-NAME
</pre>


## <a id="check-ssh-permissions"></a> Verify SSH permissions

[cf ssh-enabled](http://cli.cloudfoundry.org/en-US/cf/ssh-enabled.html) verifies whether an app is accessible with SSH:
<pre class="terminal">$ cf ssh-enabled MY-AWESOME-APP
ssh support is disabled for 'MY-AWESOME-APP'
</pre>

[cf space-ssh-allowed](http://cli.cloudfoundry.org/en-US/cf/space-ssh-allowed.html) verifies whether all apps running within a space are accessible with SSH:
<pre class="terminal">
$ cf space-ssh-allowed SPACE-NAME
ssh support is enabled in space 'SPACE-NAME'
</pre>


## <a id="ssh-command"></a> Log in to an application container with cf SSH

If SSH access is allowed at the deployment, space, and app level, you can run the `cf ssh APP-NAME` command to start an interactive SSH session with a VM hosting an app. By default, the command accesses the container running the first instance of the app, the instance with index **0**.
<pre class="terminal">
$ cf ssh MY-AWESOME-APP
</pre>

<%= vars.cfdot_kb %>

### <a id="ssh-common-flags"></a> Common cf SSH flags

You can tailor [cf ssh](http://cli.cloudfoundry.org/en-US/cf/ssh.html) commands with the following flags, most of which mimic flags for the UNIX or Linux `ssh` command. Run the `cf ssh --help` command for more details.

* The `-i` flag targets a specific instance of an app. To log in to the VM container hosting the third instance, `index=2`,  of MY-AWESOME-APP, run:

    <pre class="terminal">
    $ cf ssh MY-AWESOME-APP -i 2
    </pre>

* The `-L` flag activates local port forwarding, binding an output port on your machine to an input port on the app VM. Pass in a local port, and your app VM port and port number, all colon-separated. You can prepend your local network interface, or use the default `localhost`.

    <pre class="terminal">
    $ cf ssh MY-AWESOME-APP -L [LOCAL-NETWORK-INTERFACE:]LOCAL-PORT:REMOTE-HOST-NAME:REMOTE-HOST-PORT
    </pre>

* The `-N` flag skips returning a command prompt on the remote machine. This sets up local port forwarding if you do not need to run commands on the host VM.

* The `--process` flag in cf CLI v7+ allows you to SSH into the container for a specific process running as part of your app.

* The `--request-pseudo-tty` and `--force-pseudo-tty ` flags allow you run an SSH session in pseudo-tty mode rather than generate terminal line output.


## <a id="ssh-env"></a> SSH session environment

To make the environment of your interactive SSH session match the environment of
your buildpack-based app, with the same environment variables and working directory, run
the following command after starting the session:

<pre class="terminal">
/tmp/lifecycle/shell
</pre>

After running the previous command, the value of the `VCAP_APPLICATION` environment variable differs
slightly from its value in the environment of the app process, because it does not have the `host`,
`instance_id`, `instance_index`, or `port` fields set. These fields are available in other
environment variables, as described in
[VCAP_APPLICATION](environment-variable.html#VCAP-APPLICATION) in
_<%= vars.app_runtime_abbr %> Environment Variables_.


## <a id="other-ssh-access"></a> App SSH access without cf CLI

In addition to `cf ssh`, you can use other SSH clients such as `ssh`, `scp`, or `sftp` to access
your app via its process GUID, if you have SSH permissions.

> **Note** Previous versions of <%= vars.app_runtime_abbr %> supported SSH access to apps via the app GUID, as archived at <a href="https://web.archive.org/web/20241224221352/https://docs.cloudfoundry.org/devguide/deploy-apps/ssh-apps.html#app-guid">Access app SSH using app GUID</a>

To securely connect to an app instance using its process GUID:

1. Query the `/v2/info` endpoint of the Cloud Controller in your deployment. Record the domain name
and port number of the `app_ssh_endpoint` field, and the `app_ssh_host_key_fingerprint` field. You
can compare the `app_ssh_host_key_fingerprint` with the fingerprint returned by the SSH proxy on
your target VM. For example:

    <pre class="terminal">
    $ cf curl /v2/info
    {
         ...
         "app_ssh_endpoint": "ssh.example.com:2222",
         "app_ssh_host_key_fingerprint": "a6:14:c0:ea:42:07:b2:f7:53:2c:0b:60:e0:00:21:6c",
         ...
    }
    </pre>

    In this example:
    <ul>
      <li>The domain name is <code>ssh.example.com</code>.</li>
      <li>The port number is <code>2222</code>.</li>
      <li>The fingerprint is <code>a6:14:c0:ea:42:07:b2:f7:53:2c:0b:60:e0:00:21:6c</code>.</li>
    </ul>

1. Run:

    ```
    ssh -p PORT-NUMBER cf:$(cf curl /v3/apps/$(cf app APP-NAME --guid)/processes | jq -r '.resources[] | select(.type=="web") | .guid')/0@SSH-ENDPOINT
    ```

    Where:
    <ul>
      <li><code>PORT-NUMBER</code> is the port number of the <code>app_ssh_endpoint</code> field that you recorded in an earlier step.</li>
      <li><code>APP-NAME</code> is the name of your target app.</li>
      <li><code>SSH-ENDPOINT</code> is the domain name of the <code>app_ssh_endpoint</code> field that you recorded in an earlier step.</li>
    </ul>

    For example:
    <pre class="terminal">
    ssh -p 2222 cf:$(cf curl /v3/apps/$(cf app my-app --guid)/processes | jq -r '.resources[] | select(.type=="web") | .guid')/0&#64;ssh.example.com
    </pre>

2. Run `cf ssh-code` to obtain a one-time authorization code that substitutes for an SSH password.
You can run `cf ssh-code | pbcopy` to copy the code to the clipboard. For example:

    <pre class="terminal">
    $ cf ssh-code
    E1x89n
    </pre>

1. When the SSH proxy reports its RSA fingerprint, confirm that it matches the
`app_ssh_host_key_fingerprint` recorded previously. When prompted for a password, paste in the
authorization code returned by `cf ssh-code`. For example:

    <pre class="terminal">
    $ ssh -p 2222 cf:abcdefab-1234-5678-abcd-1234abcd1234/0<span>@</span>ssh.MY-DOMAIN.com
    The authenticity of host '[ssh.example.com]:2222 ([203.0.113.5]:2222)' can't be established.
    RSA key fingerprint is a6:14:c0:ea:42:07:b2:f7:53:2c:0b:60:e0:00:21:6c.
    Are you sure you want to continue connecting (yes/no)? yes
    Warning: Permanently added '[ssh.example.com]:2222 [203.0.113.5]:2222' (RSA) to the list of known hosts.
    cf:d0a2e11d-e6ca-4120-b32d-140<span>@</span>ssh.ketchup.cf-app.com's password:
    vcap@ce4l5164kws:~$
    </pre>

    You have now securely connected to the app instance.


## <a id="ssh-proxy-security-config"></a> SSH proxy security configuration

The SSH proxy has these SSH security configuration by default:

<table id='ssh-proxy-security-configuration-values' class="table">
  <thead><tr>
    <th>Security parameter</th>
    <th>Values</th>
  </tr></thead>
  <tr>
    <td>Ciphers</td>
    <td>
      <code>chacha20-poly1305@openssh.com</code><br/>
      <code>aes128-gcm@openssh.com</code><br/>
      <code>aes256-ctr</code><br/>
      <code>aes192-ctr</code><br/>
      <code>aes128-ctr</code>
    </td>
  </tr>
  <tr>
    <td><abbr title="Message Authentication Codes">MACs</abbr></td>
    <td>
      <code>hmac-sha2-256-etm@openssh.com</code><br/>
      <code>hmac-sha2-256</code>
    </td>
  </tr>
  <tr>
    <td>Key exchanges</td>
    <td>
      <code>curve25519-sha256@libssh.org</code>
    </td>
  </tr>
</table>

The `cf ssh` command is compatible with this security configuration. If you use a different SSH client to access apps over SSH, you can ensure that you configure your client to be compatible with these ciphers, MACs, and key exchanges. For more information about other SSH clients, see [App SSH access without cf CLI](#other-ssh-access).

<% if vars.platform_code == 'CF' %>
Cloud Foundry deployment operators can also change these default values in the SSH proxy configuration. Changing these default values might require a change to the SSH client configuration.
<% end %>


## <a id="proxy-to-container-auth"></a> Proxy to container authentication

A second layer of SSH security runs within each container. When the SSH proxy attempts to handshake with the SSH daemon inside the target container, it uses the following fields associated with the `diego-ssh` key in its route to the app instance. This inner layer works invisibly and requires no user action, but is described here to complete the SSH security picture.

### CONTAINER_PORT (required)

`container_port` indicates which port inside the container the SSH daemon is listening on. The proxy attempts to connect to host side mapping of this port after authenticating the client.

### HOST_FINGERPRINT (optional)

When present, `host_fingerprint` declares the expected fingerprint of the SSH daemon's host public key. When the fingerprint of the actual target's host key does not match the expected fingerprint, the connection is stopped. The fingerprint must only contain the hex string generated by `ssh-keygen -l`.

### USER (optional)

`user` declares the user ID to use during authentication with the container's SSH daemon. While this is not a required part of the routing data, it is required for password authentication and might be required for public key authentication.

### PASSWORD (optional)

`password` declares the password to use during password authentication with the container's SSH daemon.

### PRIVATE_KEY (optional)

`private_key` declares the private key to use when authenticating with the container's SSH daemon. If present, the key must be a PEM encoded RSA or DSA public key.

#### Example app process

```json
{
  "process_guid": "ssh-process-guid",
  "domain": "ssh-experiments",
  "rootfs": "preloaded:cflinuxfs3",
  "instances": 1,
  "start_timeout": 30,
  "setup": {
    "download": {
      "artifact": "diego-sshd",
      "from": "http://file-server.service.cf.internal.example.com:8080/v1/static/diego-sshd/diego-sshd.tgz",
      "to": "/tmp",
      "cache_key": "diego-sshd"
    }
  },
  "action": {
    "run": {
      "path": "/tmp/diego-sshd",
      "args": [
          "-address=0.0.0.0:2222",
          "-authorizedKey=ssh-rsa ..."
      ],
      "env": [],
      "resource_limits": {}
    }
  },
  "ports": [ 2222 ],
  "routes": {
    "diego-ssh": {
      "container_port": 2222,
      "private_key": "PEM encoded PKCS#1 private key"
    }
  }
}
```

<p class="note important">
To avoid security exposure, migrate your apps and custom buildpacks to use the <code>cflinuxfs4</code> stack based on Ubuntu 22.04 LTS (Jammy Jellyfish). The <code>cflinuxfs3</code> stack is based on Ubuntu 18.04 (Bionic Beaver), which reaches end of standard support in April 2023.</p>

### Daemon discovery

To be accessible through the SSH proxy, containers must host an SSH daemon, expose it through a mapped port, and advertise the port in a `diego-ssh` route. If a proxy cannot find the target process or a route, user authentication fails.

```
  "routes": {
    "diego-ssh": { "container_port": 2222 }
  }
```

The Diego system generates the appropriate process definitions for <%= vars.app_runtime_abbr %> apps to reflect the policies in effect.