-
Notifications
You must be signed in to change notification settings - Fork 69
/
config-ssh.html.md.erb
179 lines (133 loc) · 8.53 KB
/
config-ssh.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
---
title: Configuring SSH access for Cloud Foundry
owner: Diego
---
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. Generate a unique key pair for each deployment.
In recent versions of <code>cf-deployment</code>, this key pair is automatically generated and stored in <code>credhub</code>.
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">
<span class="note__title"><strong>Note</strong></span>
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
</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.
## <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. 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 AWS
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> Deactivate SSH
If you want to deactivate 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, see the following list to help troubleshoot the issue.
<table border="1" class="table">
<thead><tr>
<th><strong>Error</strong></th>
<th><strong>Reason</strong></th>
</tr></thead>
<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>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>