-
Notifications
You must be signed in to change notification settings - Fork 14
/
installing.html.md.erb
294 lines (232 loc) · 12.8 KB
/
installing.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
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
---
title: Installing the Pivotal Cloud Foundry IPSec Add-On
owner: Security Engineering
---
<strong><%= modified_date %></strong>
This topic describes how to prepare your network for IPsec, create an IPsec manifest, and add IPsec to your deployment.
##<a id="prereqs"></a>Prerequisites
To complete the IPsec installation, check that you have satisfied the following prerequisites before you begin:
* AWS, vSphere, or OpenStack as your IaaS
* Pivotal Cloud Foundry (PCF) operator administration rights
* BOSH deployed through Ops Manager 1.7 or higher
<p class="note"><strong>Note</strong>: You must install the IPsec add-on before installing any other tiles to enable
the IPsec functionality. Pivotal recommends installing IPsec immediately after Ops Manager, and before installing the
Elastic Runtime tile. </p>
<p class="note"><strong>Note</strong>: IPsec may affect the functionality of other service tiles. As a result, Pivotal recommends deploying Elastic Runtime and each service tile to different isolated subnets. Alternatively, you can minimally deploy all service tiles to a single isolated subnet, apart from the Elastic Runtime subnet.</p>
<p class="note"><strong>Note</strong>: For IPsec, Pivotal recommends any Ubuntu stemcells for vSphere and OpenStack, and HVM stemcells for AWS. These stemcells are available on <a href="https://network.pivotal.io/products/stemcells">Pivotal Network</a>. If you are using PV stemcells obtained from <a href="https://bosh.io">bosh.io</a>, see <a href="./troubleshooting.html#ipsec-installation-issues">Preventing Packet Loss</a> in the Troubleshooting topic to adjust MTU values. Pivotal recommends MTU values of 1354 on OpenStack, and the default values on AWS and vSphere.</p>
##<a id="config-network"></a>Configure Network Security
Refer to the appropriate section below for your IaaS network configuration details.
###<a id="aws"></a>AWS
Follow these steps:
1. Navigate to the **PCF VMs Security Group**.
2. Set up the following **Inbound Rules**. Adjust the source CIDR as needed for your environment.
<table border="1" class="nice">
<tr>
<th>Type</th>
<th>Protocol</th>
<th>Port Range</th>
<th>Source</th>
</tr>
<tr>
<td>Custom Protocol</td>
<td>AH (51)</td>
<td>All</td>
<td>0.0.0.0/0</td>
</tr>
<tr>
<td>Custom Protocol</td>
<td>ESP (50)</td>
<td>All</td>
<td>0.0.0.0/0</td>
</tr>
<tr>
<td>Custom UDP Rule</td>
<td>UDP(17)</td>
<td>500</td>
<td>0.0.0.0/0</td>
</tr>
</table>
###<a id="vsphere"></a>vSphere
Confirm that your network allows protocols 50 and 51 and UDP on port 500.
###<a id="openstack"></a>OpenStack
<p class="note"><strong>Note</strong>: The following network configuration is optimized for Mirantis OpenStack, but other OpenStack distributions have a similar workflow.</p>
For Mirantis OpenStack, follow these steps:
1. Navigate to **Project / Access & Security**.
1. Select the security group and click **Manage Rules**.
1. Set up the following **Ingress and Egress Rules**. Adjust the source CIDR as needed for your environment.
<table border="1" class="nice">
<tr>
<th>IP Protocol</th>
<th>Port Range</th>
<th>Source</th>
</tr>
<tr>
<td>50</td>
<td>Any</td>
<td>0.0.0.0/0</td>
</tr>
<tr>
<td>51</td>
<td>Any</td>
<td>0.0.0.0/0</td>
</tr>
<tr>
<td>UDP</td>
<td>500</td>
<td>0.0.0.0/0</td>
</tr>
</table>
##<a id="create-mfest"></a>Create the IPsec manifest
Follow these steps to create the IPsec manifest for your deployment:
1. Create an IPsec manifest file `ipsec-addon.yml` starting with the code below as a template.
<pre>releases:
\- {name: ipsec, <strong>version</strong>: 1.0.0}<br>
addons:
\- name: ipsec-addon
jobs:
\- <strong>name</strong>: ipsec
release: ipsec
properties:
ipsec:
<strong>ipsec\_subnets</strong>:
\- 10.0.1.1/20
<strong>no\_ipsec\_subnets</strong>:
\- 10.0.1.10/32 # bosh director
<strong>instance\_certificate</strong>: |
-----BEGIN CERTIFICATE-----
MIIEMDCCAhigAwIBAgIRAIvrBY2TttU/LeRhO+V1t0YwDQYJKoZIhvcNAQELBQAw
...
-----END CERTIFICATE-----
<strong>instance\_private\_key</strong>: |
-----BEGIN RSA PRIVATE KEY-----
MIIEogIBAAKCAQEAtAkBjrzr5x9g0aWgyDEmLd7m9u/ZzpK7UScfANLaN7JiNz3c
...
-----END RSA PRIVATE KEY-----
<strong>ca\_certificates</strong>:
\- |
-----BEGIN CERTIFICATE-----
MIIFCTCCAvGgAwIBAgIBATANBgkqhkiG9w0BAQsFADAUMRIwEAYDVQQDEwl0ZXN0
...
-----END CERTIFICATE-----
\- |
-----BEGIN CERTIFICATE-----
MIIFCTCCAvGgAwIBAgIBATAAYDVQQDEwl0ZXN0NBgkqhkiG9w0BAQsFADAUMRIwE
...
-----END CERTIFICATE-----
<strong>prestart\_timeout</strong>: 30 </pre>
2. Replace the properties listed in the file as follows:
* <code>releases: - version:</code> Specify the version number of your IPsec download from Pivotal Network.
* <code>jobs: - name:</code> Do not change the name of this job. It must be `ipsec`.
* <code>ipsec\_subnets:</code> List the subnets that you want to be encrypted. You can include the entire deployment or a portion of the network. Encrypt any network that handles business-sensitive data.
* <code>no\_ipsec\_subnets:</code> List the IP address of your BOSH director, and any other IPs in your PCF deployment that you want to communicate without encryption. Pivotal recommends that you list the subnets that are used for PCF managed services.
* <code>instance\_certificate:</code> Paste in the signed certificate for use by all your instance VMs. You must use one of the CAs in the ca\_certificates property to sign this certificate. For a development or test environment, you can use a self-signed certificate. See the [Generate a Self-Signed Certificate](#self-signed) section.
* <code>instance\_private\_key:</code> Paste in the private key that corresponds to the instance\_certificate above. The key must not use a pass phrase.
* <code>ca\_certificates:</code> Paste in CA certificates for the instance VM to trust during the validation process. In most cases, you only need the CA certificate used to sign the instance certificate. During CA credential rotation, you need two CA certificates.
* <code>prestart\_timeout:</code> You can optionally modify the 30 second default prestart timeout value. The value limits the number of seconds allowed for IPsec to start before failing the attempt.
<p class="note"><strong>Note:</strong> To modify <code>ipsec_subnets</code> or <code>no_ipsec_subnets</code> in an existing deployment, you must update the manifest file and redeploy.</p>
##<a id="download-deploy"></a>Download and Deploy the IPsec Add-on
1. Download the IPsec add-on software binary from the [Pivotal Network](https://network.pivotal.io/products/p-ipsec-addon) to your local machine.
2. Copy the software binary to your Ops Manager instance.
<pre class="terminal">$ scp -i PATH/TO/PRIVATE/KEY ipsec-release.tar.gz ubuntu@YOUR-OPS-MANAGER-VM-IP:</pre>
3. Copy the IPsec manifest file to your Ops Manager instance.
<pre class="terminal">$ scp -i PATH/TO/PRIVATE/KEY ipsec-addon.yml ubuntu@YOUR-OPS-MANAGER-VM-IP:</pre>
4. SSH into Ops Manager.
<pre class="terminal">$ ssh -i PATH-TO-PRIVATE-KEY ubuntu@YOUR-OPS-MANAGER-VM-IP</pre>
5. Navigate to the software binary location in your working directory.
<pre class="terminal">
$ cd PATH-TO-BINARY</pre>
6. Target your BOSH director instance with BOSH.<pre class="terminal">
$ bosh target YOUR-OPS-MANAGER-DIRECTOR-IP
Target set to 'Ops Manager'
Your username: director
Enter password: ******************
Logged in as 'director'
</pre>
7. Upload your release.<pre class="terminal">$ bosh upload release PATH-TO-BINARY/BINARY-NAME.tar</pre>
8. Optionally, from the command line, confirm that the upload of the IPsec software binary completed. You should see the IPsec binary file.
<pre class="terminal">$ bosh releases</pre>
9. Update your runtime configuration to include the IPsec add-on.
<pre class="terminal">$ bosh update runtime-config PATH/ipsec-addon.yml</pre>
10. Verify your runtime configuration changes match what you specified in the IPsec manifest file.
<pre class="terminal">
$ bosh runtime-config
Acting as user 'admin' on 'micro'
releases:
<span>-</span> {name: ipsec, version: 1.0.0}
addons:
name: ipsec-addon
jobs:
<span>-</span> name: ipsec
release: ipsec
...
</pre>
11. Navigate to your **Installation Dashboard** in Ops Manager.
<p class="note"><strong>Note:</strong> The following step cannot be undone. After you deploy IPsec, you cannot roll it back. </p>
12. Click **Apply Changes**.
13. Secure the sensitive information in the `ipsec-addon.yml` file. Pivotal recommends encrypting the file and/or moving it to a secure location.
##<a id="verify"></a>Verify Your IPsec Installation
1. Run `bosh vms` to list the job VMs in your deployment. Choose the job name and index of any VM. The exact VM does not matter, because installing the IPsec add-on loads IPsec on all VMs deployed by Ops Manager.
1. Run `bosh ssh JOB-NAME/INDEX` to open a SSH connection into the VM.
1. Run `sudo su -` to enter the root environment with root privileges.
1. Run `monit summary` to confirm that your `ipsec` job is listed as a `bosh` job.
<pre class="terminal">
The Monit daemon 5.2.5 uptime: 18h 32m
...
Process 'ipsec' running
System 'system\_localhost' running
</pre>
2. Run `PATH-TO-IPSEC/ipsec statusall` to confirm that IPsec is running. If IPsec is not running, this command produces no output.
<pre class="terminal">
$ /var/vcap/packages/strongswan-5.3.5/sbin/ipsec statusall
Status of IKE charon daemon (strongSwan 5.3.5, Linux 3.19.0-56-generic, x86\_64):
uptime: 18 hours, since Mar 16 23:58:50 2016
malloc: sbrk 2314240, mmap 0, used 1182400, free 1131840
worker threads: 11 of 16 idle, 5/0/0/0 working, job queue: 0/0/0/0, scheduled: 206
loaded plugins: charon aes sha1 sha2 random nonce x509 revocation constraints pubkey pkcs1 pkcs7 pkcs8 pkcs12 pem gmp xcbc cmac hmac attr kernel-netlink socket-default stroke
Listening IP addresses:
10.10.5.66
Connections:
ipsec-10.10.4.0/24: %any...%any IKEv1/2
ipsec-10.10.4.0/24: local: [CN=test-cert-1-ca-1] uses public key authentication
ipsec-10.10.4.0/24: cert: "CN=test-cert-1-ca-1"
ipsec-10.10.4.0/24: remote: uses public key authentication
ipsec-10.10.9.0/24: child: 10.10.5.66/32 === 10.10.9.0/24 TRANSPORT
no-ipsec-10.10.4.1/32: %any...%any IKEv1/2
no-ipsec-10.10.4.1/32: local: uses public key authentication
no-ipsec-10.10.4.1/32: remote: uses public key authentication
no-ipsec-10.10.4.1/32: child: dynamic === 10.10.4.1/32 PASS
Shunted Connections:
no-ipsec-10.10.4.1/32: dynamic === 10.10.4.1/32 PASS
no-ipsec-10.10.5.1/32: dynamic === 10.10.5.1/32 PASS
no-ipsec-10.10.6.1/32: dynamic === 10.10.6.1/32 PASS
Routed Connections:
ipsec-10.10.9.0/24{6}: ROUTED, TRANSPORT, reqid 6
ipsec-10.10.9.0/24{6}: 10.10.5.66/32 === 10.10.9.0/24
ipsec-10.10.8.0/24{5}: ROUTED, TRANSPORT, reqid 5
ipsec-10.10.4.0/24{1}: 10.10.5.66/32 === 10.10.4.0/24
Security Associations (45 up, 0 connecting):
ipsec-10.10.4.0/24[459]: ESTABLISHED 13 seconds ago, 10.10.5.66[CN=test-cert-1-ca-1]...10.10.4.38[CN=test-cert-1-ca-1]
ipsec-10.10.4.0/24{1527}: 10.10.5.66/32 === 10.10.4.38/32
...
</pre>
##<a name="self-signed"></a>Generate a Self-Signed Certificate
<p class="note"><strong>Note</strong>: Use a self-signed certificate only for development or test environments. Do not use a self-signed certificate for a production deployment. The scripts below generate private keys in a <code>certs</code> subdirectory.</p>
To generate a self-signed certificate for your IPsec manifest, you can use either `openssl` or `certstrap`. Follow the instructions for your preferred method below.
Rerunning the scripts overwrites your current keys and the certificates.
### Generate a Self-Signed Certificate with OpenSSL
1. [Download](./scripts/openssl-create-ipsec-certs.sh) the `openssl` bash script.
1. Change into the directory where you downloaded the script:
<pre class="terminal">$ cd ~/workspace</pre>
1. Change the permissions of the script:
<pre class="terminal">$ chmod u+x openssl-create-ipsec-certs.sh</pre>
1. Run the script:
<pre class="terminal">$ ./openssl-create-ipsec-certs.sh</pre>
### Generate a Self-Signed Certificate with Certstrap
1. Download and install [Go](https://golang.org/dl/).
1. [Download](./scripts/certstrap-create-ipsec-certs.sh) the `certstrap` bash script.
1. Change into the directory where you downloaded the script:
<pre class="terminal">$ cd ~/workspace</pre>
1. Change the permissions of the script:
<pre class="terminal">$ chmod u+x certstrap-create-ipsec-certs.sh</pre>
1. Run the script:
<pre class="terminal">$ ./certstrap-create-ipsec-certs.sh</pre>