installing.html.md.erb

---
title: Installing the IPsec Add-on for PCF
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, verify that you have satisfied the following prerequisites before you begin:

* Google Cloud Platform (GCP), vSphere, Azure, Amazon Web Services (AWS), or OpenStack as your IaaS

* Pivotal Cloud Foundry (PCF) operator administration rights

* BOSH deployed through Ops Manager v1.8 or later

* Set the MTU for your IaaS in the Pivotal Application Service (PAS) or Elastic Runtime tile, under **Networking**.
  Pivotal recommends MTU values of 1354 on GCP, 1438 on Azure,
  and the default values on AWS and vSphere.
  For OpenStack, follow the recommendations of your [Neutron/ML2](https://wiki.openstack.org/wiki/Neutron/ML2) plugin provider,
  or empirically test the correct MTU for your environment.

##<a id="bestpractices"></a>Best Practices
  * IPsec may affect the functionality of other service tiles.
    As a result, Pivotal recommends deploying PAS
    (or 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 PAS (or Elastic Runtime) subnet.
    Some service tiles do not support IPsec
    and must be placed in a non-IPsec subnet. 
  * For IPsec on Linux VMs, Pivotal recommends any Ubuntu stemcells for vSphere, OpenStack, and HVM stemcells for AWS. These stemcells are available on <a href="https://network.pivotal.io/products/stemcells">Pivotal Network</a>. If you use PV stemcells obtained from <a href="https://bosh.io">bosh.io</a>, see the <a href="./troubleshooting.html#ipsec-installation-issues">Packet Loss</a> section of the Troubleshooting the IPsec Add-on for PCF topic to adjust MTU values.
  * For IPsec on Windows VMs, Pivotal recommends the Windows stemcells for AWS, GCP, or Azure available on <a href="https://network.pivotal.io/products/stemcells-windows-server">Pivotal Network</a>.  

##<a id="config-network"></a>Step 1: Configure Network Security

Perform the steps in the appropriate section below to configure your IaaS network security.

###<a id="gcp"></a>Google Cloud Platform

To configure your Google Cloud Platform (GCP) environment for IPsec, perform the following steps:

1. Navigate to the **Networking** section of the GCP Console. 
1. Click **Firewall rules**.
1. Click **Create Firewall Rule**.
1. For **Name**, enter `ipsec`.
1. For **Network**, select the network where Ops Manager is deployed. For example, **opsmgr**.
1. For **Source filter**, select **Allow from any source (0.0.0.0/0)**.
1. For **Allowed protocols and ports**, enter `udp:500; ah; esp`.
1. Click **Create**. 
1. Adjust the MTU value to `1354` by performing the procedure in the <a href="./troubleshooting.html#ipsec-installation-issues">Packet Loss</a> section of the Troubleshooting the IPsec Add-on for PCF topic.

###<a id="vsphere"></a>vSphere

Confirm that your network allows the protocols listed in the table below.

<table>
  <tr>
    <th width="33%">Protocol Name</th>
    <th width="33%">Protocol Number</th>
    <th width="33%">Port(s)</th>
  </tr>
  <tr>
    <td>AH</td>
    <td>51</td>
    <td>Any</td>
  </tr>
  <tr>
    <td>ESP</td>
    <td>50</td>
    <td>Any</td>
  </tr>
  <tr>
    <td>UDP</td>
    <td>17</td>
    <td>500</td>
  </tr>
</table>


###<a id="azure"></a>Azure

1. Confirm that your network allows the protocols listed in the table below.
  <table>
    <tr>
      <th width="33%">Protocol Name</th>
      <th width="33%">Protocol Number</th>
      <th width="33%">Port(s)</th>
    </tr>
    <tr>
      <td>AH</td>
      <td>51</td>
      <td>Any</td>
    </tr>
    <tr>
      <td>ESP</td>
      <td>50</td>
      <td>Any</td>
    </tr>
    <tr>
      <td>UDP</td>
      <td>17</td>
      <td>500</td>
    </tr>
  </table>

1. Adjust the MTU value to `1438`. For instructions, see <a href="./troubleshooting.html#ipsec-installation-issues">Explanation: Packet Loss</a>.

###<a id="aws"></a>AWS

To configure your AWS environment for IPsec, perform the following steps:

1. Navigate to **EC2 Dashboard > Security Groups**.

2. Select the Security Group with the description **PCF VMs Security Group** and click **Edit**.

3. Create the following **Inbound Rules**.
  <table border="1" class="nice">
  <tr>
    <th>Type</th>
    <th>Protocol Name</th>
    <th>Protocol Number</th>
    <th>Port Range</th>
    <th>Source</th>
  </tr>
  <tr>
    <td>Custom Protocol</td>
    <td>AH</td>
    <td>51</td>
    <td>All</td>
    <td>10.0.0.0/16</td>
  </tr>
  <tr>
    <td>Custom Protocol</td>
    <td>ESP</td>
    <td>50</td>
    <td>All</td>
    <td>10.0.0.0/16</td>
  </tr>
  <tr>
    <td>Custom UDP Rule</td>
    <td>UDP</td>
    <td>17</td>
    <td>500</td>
    <td>10.0.0.0/16</td>
  </tr>
  </table>

<p class="note"><strong>Note</strong>: The default <strong>PCF VMs Security Group</strong> is typically specified with a subnet of <code>10.0.0.0/16</code>. If your PCF subnet is deployed to a different CIDR block, adjust the source as needed.</p>

###<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>

To configure your Mirantis OpenStack environment for IPsec, perform the following steps:

1. Navigate to **Project / Access & Security**.

1. Select the security group and click **Manage Rules**.

1. Create the following **Ingress and Egress Rules**. Adjust the source CIDR as needed for your environment.
  <table border="1" class="nice">
  <tr>
    <th>Protocol Name</th>
    <th>Protocol Number</th>
    <th>Port Range</th>
    <th>Source</th>
  </tr>
  <tr>
    <td>ESP</td>
    <td>50</td>
    <td>Any</td>
    <td>0.0.0.0/0</td>
  </tr>
  <tr>
    <td>AH</td>
    <td>51</td>
    <td>Any</td>
    <td>0.0.0.0/0</td>
  </tr>
  <tr>
    <td>UDP</td>
    <td>17</td>
    <td>500</td>
    <td>0.0.0.0/0</td>
  </tr>
  </table>

##<a id="create-mfest"></a>Step 2: Create the IPsec Manifest

To add IPsec to VMs in your deployment, you must create a manifest file named `ipsec-addon.yml` that configures IPsec add-on properties for Linux VMs, Windows VMs, or both. Perform the following steps:

1. Create an IPsec manifest file named `ipsec-addon.yml`, with the code below as a template.
<pre>releases:
\- name: ipsec
&nbsp; version: 1.X.X
addons:
</pre>
1. Add properties to the `ipsec-addon.yml` file as described below for [Linux VMs](#linux) and [Windows VMs](#windows).

<p class="note"><strong>Note</strong>: Enabling IPsec for Windows adds IPsec security to Windows VMs that users can create after installing the <a href="https://docs.pivotal.io/pivotalcf/windows/index.html">PCF Runtime for Windows</a> tile.</p>

### <a id="linux"></a> Add Linux VM Support to Your Manifest

Perform the following steps to add IPsec to Linux VMs in your deployment:

1. Add the following YAML under `addons:` to your `ipsec-addon.yml` file:
  <pre>
  <strong>releases</strong>:
  \- name: ipsec
      <strong>version</strong>: 1.X.X
  addons:
  \- name: ipsec-addon
      <strong>jobs</strong>:
      \- <strong>name</strong>: ipsec
        release: ipsec
      include:
        stemcell:
        - <strong>os</strong>: ubuntu-trusty
      properties:
        ipsec:
          <strong>optional</strong>: false
          <strong>ipsec\_subnets</strong>:
          \- 10.0.1.1/20
          <strong>no\_ipsec\_subnets</strong>:
          \- 10.0.1.10/32  # bosh director
          \- 10.0.1.4/32 # ops manager
          <strong>instance\_certificate</strong>: |
            -----BEGIN CERTIFICATE-----
            MIIEMDCCAhigAwIBAgIRAIvrBY2TttU/LeRhO+V1t0YwDQYJKoZIhvcNAQELBQAw
            ...
            -----END CERTIFICATE-----
          <strong>instance\_private\_key</strong>: |
            -----BEGIN EXAMPLE RSA PRIVATE KEY-----
            EXAMPLExRSAxPRIVATExKEYxDATAxEXAMPLExRSAxPRIVATExKEYxDATA
            ...
            -----END EXAMPLE RSA PRIVATE KEY-----
          <strong>ca\_certificates</strong>:
            \- |
              -----BEGIN CERTIFICATE-----
              MIIFCTCCAvGgAwIBAgIBATANBgkqhkiG9w0BAQsFADAUMRIwEAYDVQQDEwl0ZXN0
              ...
              -----END CERTIFICATE-----
            \- |
              -----BEGIN CERTIFICATE-----
              MIIFCTCCAvGgAwIBAgIBATAAYDVQQDEwl0ZXN0NBgkqhkiG9w0BAQsFADAUMRIwE
              ...
              -----END CERTIFICATE-----
          <strong>prestart\_timeout</strong>: 30
          <strong>esp\_proposals</strong>: aes128gcm16!
          <strong>ike\_proposals</strong>: aes128-sha256-modp2048!
          <strong>log\_level</strong>: 1
          <strong>ike\_version</strong>: ike
          <strong>optional\_warn\_interval</strong>: 1
          <strong>force\_udp\_encapsulation</strong>: false
  </pre>
1. Replace the values listed in the template as follows:
  * <code><strong>releases: - version</strong></code>: Specify the version number of your IPsec download from Pivotal Network.
  * <code><strong>optional</strong></code>: <a name="optional"></a> This value makes IPsec enforcement optional.
          To add IPsec, set this flag to `true`.
          After IPsec has been successfully installed, set this flag back to `false` and redeploy.
  * <code><strong>ipsec\_subnets</strong></code>: <a name="ipsec_subnets"></a> 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><strong>no\_ipsec\_subnets</strong></code>: <a name="no_ipsec_subnets"></a> 
  List the IP address of your BOSH Director and Ops Manager VM,
          along with any other IP addresses in your PCF deployment that you want to communicate with without encryption.
          Pivotal recommends that you list the subnets that are used for PCF managed services.
          Subnets for PCF managed services that do not support IPsec (such as an Pivotal Ops Manager) 
          must be listed under `no_ipsec_subnets`.
    <p class="note warning"><strong>WARNING</strong>: If you have an external load balancer such as F5, add it to the <code><strong>no\_ipsec\_subnets</strong></code> property.
     If you want to include it in the <code><strong>ipsec_subnet</strong></code>, you must configure it manually.</p>
    <p class="note warning"><strong>WARNING</strong>: In GCP, if you use the default router for DNS instead of the Google public DNS at <code>8.8.8.8</code>,
     you must add the IP address of the default router in your subnet to <code><strong>no\_ipsec\_subnets</strong></code>.
     For example, <code>10.0.0.1/32</code>.</p>
  * <code><strong>instance\_certificate</strong></code>: <a name="instance_certificate"></a> 
  Copy in the signed certificate that will be used by all your instance VMs.
          You must use one of the CAs in the <code>ca\_certificates</code> property to sign this certificate.
          For a development or test environment, you can use a self-signed certificate.
          For more information, see [Generate a Self-Signed Certificate](#self-signed).
  * <code><strong>instance\_private\_key</strong></code>: <a name="instance_private_key"></a>
          Copy in the private key that corresponds to the <code>instance\_certificate</code> above.
          This key must not use a pass phrase.
  * <code><strong>ca\_certificates</strong></code>: <a name="ca-certs"></a>
          Copy 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.
  <br><br>
  IPsec <strong>v1.8.12</strong> and later supports the CA certificate chain.
  Concatenate the contents of the root and the intermediate certificates
  as one of the list items in <strong>ca\_certificates</strong>,
  with the root CA at the top:
    <pre>
       <strong>ca\_certificates</strong>:
         \- |
           -----BEGIN CERTIFICATE-----
           ... <strong>\<ROOT\></strong>
           -----END CERTIFICATE-----
           -----BEGIN CERTIFICATE-----
           ... <strong>\<INTERMEDIATE 1 ISSUED BY THE ROOT CERT ABOVE\></strong>
           -----END CERTIFICATE-----
           -----BEGIN CERTIFICATE-----
           ... <strong>\<INTERMEDIATE 2 ISSUED BY THE INTERMEDIATE 1 ABOVE
           ... AND SIGNS THE INSTANCE CERT\></strong>
           -----END CERTIFICATE-----
         \- |
           -----BEGIN CERTIFICATE-----
           ... <strong>\<SECOND ROOT\></strong>
           -----END CERTIFICATE-----
    </pre>
  <p class="note"><strong>Note</strong>: The root and the intermediate certificates cannot have the same subjectName,
     also called the common name and set with <code>CN=</code>.
     The root <b>must</b> be the first certificate of the chain.</p>
  * <code><strong>prestart\_timeout</strong></code>: You can modify the 30-second default prestart timeout value. This value limits the number of seconds allowed for IPsec to start before failing the attempt.
  * <code><strong>log\_level</strong></code>: <a name="log\_level"></a> You can specify the IKE daemon numerical log level, ranging from `-1` to `4`.
  For more information, see [Logger Configuration](https://wiki.strongswan.org/projects/strongswan/wiki/LoggerConfiguration) in the strongSwan documentation.
  * <code><strong>optional\_warn\_interval</strong></code>: <a name="optional\_warn\_interval"></a> The interval in hours of warning when `optional` property is set to true. It prints the warning message `{Date} - IPsec is set to "Optional"` in the file `/var/vcap/sys/log/ipsec/ipsec.stdout.log` for Linux.
  * <code><strong>force\_udp\_encapsulation</strong></code>: 
  <a name="force\_udp\_encapsulation"></a> Available on Linux-only deployments. 
  If set to `true` it forces UDP encapsulation for ESP packets.
    <p class="note warning"><strong>WARNING</strong>: Setting this property to `true` in 
      mixed deployments causes the deployment to fail. 
      If you do not have a Linux-only deployment, you must set `force_udp_encapsulation` to `false`. </p>


### <a id="windows"></a> Add Windows VM Support to Your Manifest

To add IPsec to Windows VMs in your deployment, follow these steps:

1. Modify the `ipsec-addon.yml` created during the previous section to add the properties indicated <strong>in bold</strong> below under the `ipsec` key.
  <pre>
  \- name: ipsec-addon
      ...
      properties:
        ipsec:
          .
          .
          .
          <strong>ike_version</strong>: ikev1
          <strong>dpdaction</strong>: none
  </pre>

1. Add the following YAML under `addons:` to your `ipsec-addon.yml` file.
   Add it under the `ipsec-addon` section for Linux, if you included one [above](#linux).
  <pre>
  \- name: ipsec-windows-addon
      jobs:
      \- <strong>name</strong>: ipsec-win
        release: ipsec
      include:
        stemcell:
          \- <strong>os</strong>: windows2012R2
      properties:
        ipsec:
          <strong>optional</strong>: false
          <strong>ipsec\_subnets</strong>:
          \- 10.0.1.1/20
          <strong>no\_ipsec\_subnets</strong>:
          \- 10.0.1.10/32  # bosh director
          \- 10.0.1.4/32 # ops manager
          <strong>instance\_certificate</strong>: |
            -----BEGIN CERTIFICATE-----
            MIIEMDCCAhigAwIBAgIRAIvrBY2TttU/LeRhO+V1t0YwDQYJKoZIhvcNAQELBQAw
            ...
            -----END CERTIFICATE-----
          <strong>instance\_private\_key</strong>: |
            -----BEGIN EXAMPLE RSA PRIVATE KEY-----
            EXAMPLExRSAxPRIVATExKEYxDATAxEXAMPLExRSAxPRIVATExKEYxDATA
            ...
            -----END EXAMPLE RSA PRIVATE KEY-----
          <strong>ca\_certificates</strong>:
            \- |
              -----BEGIN CERTIFICATE-----
              MIIFCTCCAvGgAwIBAgIBATANBgkqhkiG9w0BAQsFADAUMRIwEAYDVQQDEwl0ZXN0
              ...
              -----END CERTIFICATE-----
            \- |
              -----BEGIN CERTIFICATE-----
              MIIFCTCCAvGgAwIBAgIBATAAYDVQQDEwl0ZXN0NBgkqhkiG9w0BAQsFADAUMRIwE
              ...
              -----END CERTIFICATE-----
          <strong>quick\_mode\_proposals</strong>:
            \- encryption: AESGCM128
              hash: AESGMAC128
          <strong>main\_mode\_proposals</strong>:
            \- encryption: AES128
              hash: SHA256
              keyexchange: DH14</pre>
1. Replace the values listed in the template as follows:
  * <code><strong>ipsec\_subnets</strong></code>: Copy and paste the value from [ipsec\_subnets](#ipsec_subnets) for Linux.
  * <code><strong>no\_ipsec\_subnets</strong></code>: Copy and paste the value from [no\_ipsec\_subnets](#no_ipsec_subnets) for Linux.
  * <code><strong>instance\_certificate</strong></code>: Copy and paste the value from [instance\_certificate](#instance_certificate) for Linux.
  * <code><strong>instance\_private\_key</strong></code>: Copy and paste the value from [instance\_private\_key](#instance_private_key) for Linux.
  * <code><strong>ca\_certificates</strong></code>: Copy and paste the value from [ca\_certificates](#ca-certs) for Linux.
  * <code><strong>optional</strong></code>: Copy and paste the value from [optional](#optional) for Linux.

###<a id="proposals"></a> Optional: Custom Linux/Windows Mixed Deployment Proposals

A default proposal set is already selected for the `ipsec-addon.yml`. 
If you want to use different proposals, modify the `ipsec-addon.yml` using the following table:

1. Select the encryption type from the first row.
2. Copy the properties from that row into `ipsec-addon.yml` accordingly. See the `ipsec-addon.yml` file example above.

<table>
  <tr>
    <th rowspan="2">Encryption Type</th>
    <th colspan="2">Linux (ipsec-addon)</th>
    <th colspan="2">Windows (ipsec-win-addon)</th>
  </tr>
  <tr>
    <th>ike_proposals</th>
    <th>esp_proposals</th>
    <th>main_mode_proposals</th>
    <th>quick_mode_proposals</th>
  </tr>
  <tr>
    <td>128 Bit Encryption</td>
    <td><pre>aes128-sha256-modp2048!</pre></td>
    <td><pre>aes128gcm16!</pre></td>
    <td>
    <pre>- encryption: AES128
  hash: SHA256
  keyexchange: DH14</pre>
    </td>
    <td>
      <pre>- encryption: AESGCM128
  hash: AESGMAC128</pre>
     </td>
  </tr>
  <tr>
    <td>256 Bit Encryption</td>
    <td><pre>aes256-sha256-modp2048!</pre></td>
    <td><pre>aes256gcm16!</pre></td>
    <td>
      <pre>- encryption: AES256
  hash: SHA256
  keyexchange: DH14</pre>
    </td>
    <td>
      <pre>- encryption: AESGCM256
  hash: AESGMAC256</pre>
     </td>
  </tr>
</table>
<br>

* <code><strong>ike\_proposals</strong></code>: You can modify the IKE (Main Mode) encryption and integrity algorithms, and the Diffie-Hellman group.
  The default, `aes128-sha256-modp2048!`, is 128 bit AES-CBC for encryption, SHA2\_256\_128 HMAC for integrity, and Group 14 for Diffie-Hellman. 
* <code><strong>esp\_proposals</strong></code>: You can modify the ESP (Quick Mode) encryption and integrity algorithms.
  The default, `aes128gcm16!`, is 128 bit AES-GCM with 128 bit ICV for both encryption and integrity.
* <code><strong>main\_mode\_proposals</strong></code>: This is an array of Main Mode algorithms for encryption, integrity, and key exchange.
  This value must match the list specified in **ike_proposals** for Linux.
  See the table for proposal sets for both Linux and Windows.
  The default entry that matches the Linux default is:
    <pre>
    \- encryption: AES128
         hash: SHA256
         keyexchange: DH14
    </pre>
* <code><strong>quick\_mode\_proposals</strong></code>: This is an array of Quick Mode algorithms for encryption and integrity.
  This value must match the list specified in **esp_proposals** for Linux.
  See the table for proposal sets for both Linux and Windows.
  The default entry that matches the Linux default is:
    <pre>
    \- encryption: AESGCM128
         hash: AESGMAC128
    </pre>



##<a id="download-deploy"></a> Step 3: Download and Deploy the IPsec Add-on

Perform the following steps to download the IPsec binary, add your IPsec manifest to your BOSH manifest, 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.

1. 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>

1. 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>

1. SSH into Ops Manager.
 <pre class="terminal">$ ssh -i PATH-TO-PRIVATE-KEY ubuntu@YOUR-OPS-MANAGER-VM-IP</pre>

1. On the Ops Manager VM, navigate to the software binary location in your working directory.
<pre class="terminal">
$ cd PATH-TO-BINARY</pre>

1. Log in to the BOSH Director.
  * **For Ops Manager v1.10 or earlier:**
  <ol  type="i">
    <li>
      On the Ops Manager VM, target the internal IP address of your BOSH Director. When prompted, enter your BOSH Director credentials. To retrieve your BOSH Director credentials, navigate to Ops Manager, click the **Credentials** tab, and click **Link to Credential** next to **Director Credentials**. For example:
      <pre class="terminal">
      $ bosh --ca-cert /var/tempest/workspaces/default/root\_ca\_certificate target YOUR-BOSH-DIRECTOR-INTERNAL-IP
      Target set to 'p-bosh'
      Your username: director
      Enter password: ******************
      Logged in as 'director'
      </pre>
    </li>
  </ol>
  * **For Ops Manager v1.11 or later:**
  <ol type="i">
    <li>
      On the Ops Manager VM, create an alias in the BOSH CLI for your Ops Manager Director IP address. For example:
      <pre class="terminal">$ bosh2 alias-env my-env -e 10.0.0.3</pre>
    </li>
    <li>
      Log in to the BOSH Director, specifying the newly created alias. 
      For example:
      <pre class="terminal">$ bosh2 -e my-env log-in</pre>
    </li>
  </ol>

1. Upload your release, specifying the path to the tarballed IPsec binary, by running one of the following commands:
  * **For Ops Manager v1.10 or earlier:**
<pre class="terminal">$ bosh upload release PATH-TO-BINARY/BINARY-NAME.tar</pre>
  * **For Ops Manager v1.11 or later:**
<pre class="terminal">$ bosh2 -e my-env upload-release PATH-TO-BINARY/BINARY-NAME.tar</pre>

1. List the releases by running one of the following commands, and confirm that the IPsec binary file appears:
  * **For Ops Manager v1.10 or earlier:**
    <pre class="terminal">$ bosh releases</pre>
  * **For Ops Manager v1.11 or later:**
    <pre class="terminal">$ bosh2 -e my-env releases</pre>

1. Download your current runtime config and save as `bosh-manifest.yml` by running one of the following commands:
  * **For Ops Manager v1.10 or earlier:**
<pre class="terminal">$ bosh runtime-config > bosh-manifest.yml</pre>
  * **For Ops Manager v1.11 or later:**
<pre class="terminal">$ bosh2 -e my-env runtime-config > bosh-manifest.yml</pre>

1. Append the contents of your IPsec manifest `ipsec-addon.yml` to `bosh-manifest.yml`.

1. Update your runtime configuration to include the IPsec add-on.
  * **For Ops Manager v1.10 or earlier:**
<pre class="terminal">$ bosh update runtime-config PATH/bosh-manifest.yml</pre>
  * **For Ops Manager v1.11 or later:**
<pre class="terminal">$ bosh2 -e my-env update-runtime-config --name=ipsec PATH/bosh-manifest.yml</pre>

1. Verify your runtime configuration changes match what you specified in the IPsec manifest file.
  * **For Ops Manager v1.10 or earlier:**
<pre class="terminal"> $ bosh runtime-config</pre>
  * **For Ops Manager v1.11 or later:**
<pre class="terminal"> $ bosh2 -e my-env runtime-config</pre>

    For example:

    <pre class="terminal">
    $ bosh2 -e my-env 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
        ...
      <span>-</span> name: ipsec-win  # if using Windows
        release: ipsec
        ...
    </pre>

1. If you have already deployed PAS (or Elastic Runtime) or are adding IPsec to an existing deployment:
  1. Set the `optional` flag to `true`.
  1. Navigate to your **Installation Dashboard** in Ops Manager.
  1. Click **Apply Changes**
  1. Wait for the installation to complete.
  1. Set the `optional` flag to `false`.
  1. Update the runtime config. 
      * **For Ops Manager v1.10 or earlier:**
      <pre class="terminal">$ bosh update runtime-config PATH/bosh-manifest.yml</pre>
      * **For Ops Manager v1.11 or later:**
      <pre class="terminal">$ bosh2 -e my-env update-runtime-config --name=ipsec PATH/bosh-manifest.yml</pre>

  1. Navigate to your **Installation Dashboard**.
  1. Click **Apply Changes**.

1. If the PAS (or Elastic Runtime) tile is not yet installed:
  1. Navigate to your **Installation Dashboard** in Ops Manager.
  1. Click **Apply Changes**
  1. Deploy PAS (or Elastic Runtime) by following the installation instructions for your IaaS.
     For more information, see [Installing Pivotal Cloud Foundry](http://docs.pivotal.io/pivotalcf/installing/index.html).

1. The `bosh-manifest.yml` and `ipsec-addon.yml` files contain sensitive information.  When the deployment process is completed, be sure to remove any unneeded copies of these files from the local workstation. Pivotal recommends that any archival copies of manifest files to be retained should be appropriately secured via encryption and/or logical access controls.

##<a id="verify"></a> Step 4: Verify Your IPsec Installation

After installing IPsec and deploying PAS (or Elastic Runtime), perform the following steps to verify your IPsec installation:

1. List the job VMs in your deployment by running one of the following commands:
  * **For Ops Manager v1.10 or earlier:**<br>
  `bosh vms`
  * **For Ops Manager v1.11 or later:**<br>
  `bosh2 -e BOSH-ENVIRONMENT vms`

1. Open an SSH connection into the VM, using the job name and index of any VM found above, by running one of the following commands:
  * **For Ops Manager v1.10 or earlier:**<br>
  `bosh ssh JOB-NAME/INDEX`
  * **For Ops Manager v1.11 or later:**
  `bosh2 -e BOSH-ENVIRONMENT -d DEPLOYMENT-NAME ssh JOB-NAME/INDEX`

    <p class="note"><strong>Note</strong>: The exact VM does not matter, because installing the IPsec add-on loads IPsec on all VMs deployed by Ops Manager.</p>

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>


1. If you installed IPsec for Windows, follow these steps:
  1. From any Windows VM, open **Windows Firewall with Advanced Security**. 
  1. Click **Connection Security Rules**. 
  1. Confirm that you see rules for each `ipsec` and `no-ipsec` subnet that you listed in your manifest. 

##<a id="self-signed"></a>Generate a Self-Signed Certificate with OpenSSL

<p class="note warning"><strong>WARNING</strong>: Use a self-signed certificate only for development or test environments. 
  Pivotal recommends against using self-signed certificates for production deployments. 
  The script below generates private keys in a <code>certs</code> subdirectory.</p>

Follow these steps to generate a self-signed certificate for your IPsec manifest:


1. [Download](./scripts/openssl-create-ipsec-certs.sh) the `openssl-create-ipsec-certs.sh` bash script.
1. Navigate to 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>
1. Because this certificate expires in 365 days, set a calendar reminder to rotate the certificate within the year.
   For instructions on changing certificates, see [Rotating IPsec Certificates](credentials.html).