Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
183 lines (139 sloc) 8.92 KB
---
title: Configuring SSH Access for Cloud Foundry
owner: Diego
---
<strong><%= modified_date %></strong>
This topic describes how to configure your Cloud Foundry deployment to allow SSH access to application instances, and includes details about load balancing SSH sessions.
## <a id='architecture-configuration'></a> Cloud Foundry Configuration
To enable SSH access to apps running on Diego, you must configure the properties in your deployment manifests by following the steps below.
To configure manifest properties, you can edit them directly or put them in stub files with [merge tags](https://github.com/cloudfoundry-incubator/spiff#-merge-) that you pass to `generate_deployment_manifest` or another spiff-based manifest-generation script.
### <a id='requirements'></a> Generate a Key Pair
Enabling SSH access requires generating a RSA key pair for your SSH proxy.
<p class="note"><strong>Note</strong>: You should generate a unique key pair for each deployment.</p>
1. Generate your key pair, entering an empty string for the passphrase when prompted.
<pre class="terminal">$ ssh-keygen -f ssh-proxy-host-key.pem
$ ssh-keygen -lf ssh-proxy-host-key.pem.pub | cut -d ' ' -f2 > ssh-proxy-host-key-fingerprint
</pre>
<p class="note"><strong>Note</strong>: Recent versions of ssh-keygen print the SHA256 fingerprint hashes of the keys.
To obtain MD5 hashes of the server key fingerprints, use the <code>-E</code> option to specify the hash algorithm.</p>
<pre class="terminal">$ ssh-keygen -f ssh-proxy-host-key.pem
$ ssh-keygen -E md5 -lf ssh-proxy-host-key.pem.pub | sed 's/MD5://' | cut -d ' ' -f2 > ssh-proxy-host-key-fingerprint
</pre>
1. Locate your PEM-encoded private key in `ssh-proxy-host-key.pem` and your public key fingerprint in `ssh-proxy-host-key-fingerprint`. You will need to copy the contents of these files into your Cloud Foundry and Diego manifests.
### <a id='cf-manifest'></a> Configure Your Cloud Foundry Manifest
Your manifest for Cloud Foundry should include the following properties:
<pre>properties:
app\_ssh:
host\_key\_fingerprint: HOST-KEY-FINGERPRINT
oauth\_client\_id: ssh-proxy
cc:
allow\_app\_ssh\_access: true
default\_app\_ssh\_access: SSH-ACCESS-FOR-NEW-APPS
uaa:
clients:
ssh-proxy:
authorized-grant-types: authorization\_code
autoapprove: true
override: true
redirect-uri: /login
scope: openid,cloud\_controller.read,cloud\_controller.write,cloud\_controller.admin
secret: SSH-PROXY-SECRET
</pre>
1. Change `HOST-KEY-FINGERPRINT` to the public key fingerprint of the RSA key pair that you generated. It should be located in your `ssh-proxy-host-key-fingerprint` file.
1. Replace `SSH-ACCESS-FOR-NEW-APPS` with `true` to enable SSH access for new apps by default in spaces that allow SSH. If you set this property to `false`, developers can still enable SSH after pushing their apps by running `cf enable-ssh APP-NAME`. If an app is already deployed and running, the developer must restart the app before being able to SSH into it.
1. For `SSH-PROXY-SECRET`, provide a client secret that Diego will use to register the `ssh-proxy` client with your User Account and Authentication (UAA) server.
### <a id='diego-manifest'></a> Configure Your Diego Manifest
Your manifest for Diego should include the following properties:
<pre>properties:
ssh\_proxy:
host\_key: |
-----BEGIN EXAMPLE RSA PRIVATE KEY-----
YOUR-PRIVATE-KEY
-----END EXAMPLE RSA PRIVATE KEY-----
enable\_cf\_auth: true
enable\_diego\_auth: false
diego\_credentials: ""
uaa\_secret: SSH-PROXY-SECRET
uaa\_token_url: <span>https</span>://uaa.YOUR-SYSTEM-DOMAIN/oauth/token
</pre>
1. `ssh_proxy.host_key`: Supply the PEM-encoded private key from the RSA key pair that you originally generated for your deployment. This key secures the SSH proxy that brokers connections to individual app containers.
1. Specify CF Authentication only by setting `enable_cf_auth` to `true` and `enable_diego_auth` to `false`, as in the example above.
1. For `SSH-PROXY-SECRET`, enter the same secret you provided in the `ssh-proxy.secret` field in your Cloud Foundry manifest.
1. To complete the `uaa_token_url` field, provide `YOUR-SYSTEM-DOMAIN`.
## <a id="ssh-load-balancer-configuration"></a> SSH Load Balancer Configuration
### <a id="ha-proxy"></a>Using HAProxy
If you are using the HAProxy job as the Gorouter load balancer and you set the `cc.allow_app_ssh_access` property in your Cloud Foundry manifest to `true`, HAProxy serves as the load balancer for Diego's SSH proxies. This configuration relies on the presence of the same consul server cluster that Diego components use for service discovery. Use this configuration for deployments where all traffic on the system domain and its subdomains is directed towards the HAProxy job, as is the case for a BOSH-Lite Cloud Foundry deployment on the default `bosh-lite.com` domain.
### <a id="aws"></a>Using Elastic Load Balancers on Amazon Web Services
For Amazon Web Services (AWS) deployments, where the infrastructure offers load-balancing as a service through Elastic Load Balancers (ELBs), the deployment operator can provision an ELB to load balance across the Diego SSH proxy instances. This ELB should be configured to listen to TCP traffic on the port given by the `app_ssh.port` property in the Cloud Foundry manifest and to send it to port `2222`.
In the Diego manifest, register the SSH proxies with your ELBs by editing the `cloud_properties` values.
* If you used the spiff-based manifest-generation templates to produce the Diego manifest, the `cloud_properties` hashes should be specified in the `iaas_settings.resource_pool_cloud_properties` section of the `iaas-settings.yml` stub.
* Otherwise, add the ELB identifier to the `elbs` property in the `cloud_properties` hash of the Diego manifest `access_zN` resource pools. For example:
<pre><code>resource\_pools:
- cloud\_properties:
elbs:
- test-SSHProxyEL-16O57T64U5UAL
name: access\_z1
network: diego1
- cloud\_properties:
elbs:
- test-SSHProxyEL-16O57T64U5UAL
name: access\_z2
network: diego2
- cloud\_properties:
elbs:
- test-SSHProxyEL-16O57T64U5UAL
name: access_z3
network: diego3
</code></pre>
## <a id="disable-ssh"></a> Disable SSH
If you want to disable SSH access for a deployment:
1. Set the `cc.allow_app_ssh_access` property in your Cloud Foundry manifest to `false`.
1. Redeploy Cloud Foundry.
If you want to reset your deployment to remove all SSH proxy configuration:
1. Set the `cc.allow_app_ssh_access` property in your Cloud Foundry manifest to `false`.
1. Delete the `ssh-proxy` properties within `uaa.clients` in your Cloud Foundry manifest.
1. Redeploy Cloud Foundry.
1. Install the UAA Command Line Interface (UAAC).
<pre class="terminal">$ gem install cf-uaac</pre>
1. Target your UAA server.
<pre class="terminal">$ uaac target uaa.YOUR-SYSTEM-DOMAIN</pre>
1. Authenticate and retrieve your admin client token. When prompted with `Client secret`, enter your admin credentials.
<pre class="terminal">$ uaac token client get admin
Client secret: ********************
Successfully fetched token via client credentials grant.
Target: <span>https</span>://uaa.YOUR-SYSTEM-DOMAIN
Context: admin, from client admin</pre>
1. Delete your `ssh-proxy` client.
<pre class="terminal">$ uaac token client delete ssh-proxy</pre>
## <a id="troubleshooting"></a>Troubleshooting
If you receive an error message attempting to SSH into an app container, refer to the following list to help troubleshoot the issue.
<table border="1" class="nice">
<tr>
<th><strong>Error</strong></th>
<th><strong>Reason</strong></th>
</tr>
<tr>
<td><code>Error getting one time auth code</code></td>
<td>Check that you have the <code>ssh-proxy</code> client registered with your UAA server.</td>
</tr>
<tr>
<td><code>Error getting one time auth code</code></td>
<td>Review the <code>uaa_secret</code> field in your Diego manifest and ensure that it matches the <code>Client secret</code> for the <code>ssh-proxy</code> client registered with your UAA server.</td>
</tr>
<tr>
<td><code>Error opening SSH connection</code></td>
<td>Verify that <code>enable_cf_auth</code> in your Diego manifest is set to <code>true</code>.</td>
</tr>
<tr>
<td><code>Error opening SSH connection</code></td>
<td>Confirm that you provided the correct UAA token URL for the <code>uaa_token_url</code> property in the Diego manifest.</td>
</tr>
<tr>
<td><code>Error opening SSH connection</code></td>
<td>Check that you provided the correct private key in your Diego manifest.</td>
</tr>
<tr>
<td><code>Server error, status code: 404</code></td>
<td>Ensure that the <code>oath_client_id</code> in your Cloud Foundry manifest matches the client ID of the SSH proxy client you registered with your UAA server. The default client ID is <code>ssh-proxy</code>.</td>
</tr>
</table>