forked from pivotal-cf/docs-pcf-install
-
Notifications
You must be signed in to change notification settings - Fork 1
/
self-signed-ssl.html.md.erb
168 lines (119 loc) · 6.53 KB
/
self-signed-ssl.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
---
title: Using SSL with a Self-Signed Certificate in Pivotal Ops Metrics
owner: Metrix
---
<strong><%= modified_date %></strong>
Secure Socket Layer (SSL) is a standard protocol for establishing an encrypted
link between a server and a client.
To communicate over SSL, a client needs to trust the SSL certificate of the
server.
There are two kinds of SSL certificates: signed and self-signed.
* **Signed**: A Certificate Authority (CA) signs the certificate.
A CA is a trusted third party that verifies your identity and certificate
request, then sends you a digitally signed certificate for your secure server.
Client computers automatically trust signed certificates.
* **Self-signed**: Your own server generates and signs the certificate.
Clients do not automatically trust self-signed certificates.
To communicate over SSL with a server providing a self-signed certificate, a
client must be explicitly configured to trust the certificate.
<%= partial '../customizing/known-issue-self-signed-certs' %>
Clients keep all trusted certificates in a kind of keystore called a truststore.
To configure a client to trust a self-signed certificate, import the
self-signed certificate to a truststore on the client.
Refer to the following procedures to use SSL with a self-signed certificate in Pivotal Ops Metrics.
## <a id='enable'></a>Step 1: Enable SSL ##
To enable SSL, follow the step below to configure a PKCS#1 certificate in your release manifest.
1. Use `openssl genrsa` with the `-out` flag to generate a new private key. For example, run the following command to generate a 2048-bit private key named `privkey.pem`:
<pre class="terminal">
$ openssl genrsa -out privkey.pem 2048
</pre>
1. Use `openssl req` to generate a new certificate signing request based on your private key.
<pre class="terminal">
$ openssl req -new -key privkey.pem -out server.csr
</pre>
1. Use the command below to create a self-signed certificate, `server.crt`, from the existing private key, `privkey.pem` and the existing certificate signing request, `server.csr`:
<pre class="terminal">
$ openssl x509 -req -days 365 -in server.csr -signkey privkey.pem -out server.crt
</pre>
1. Use `keytool -import` to create a client keystore. Note that the local JMX client uses this keystore, not the server.
<pre class="terminal">
$ keytool -import -alias ops-metrics-ssl -file ops-metrics.cer -keystore localhost.truststore
</pre>
1. Enter a password for the keystore when prompted. Record this password.
1. Enter `yes` when prompted to trust the certificate.
1. Use `bosh edit deployment` to open your release manifest for editing.
<pre class="terminal">
$ bosh edit deployment
</pre>
In your release manifest, copy your private key into the `ssl_private_key` field and your public certificate into the `ssl_cert` field.
```
properties:
maximus:
username: USERNAME
password: PASSWORD
public_hostname: HOSTNAME
use_ssl: true # This defaults to true
ssl_cert: ! '-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----'
ssl_private_key: ! '-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY----- '
```
1. Verify your settings using the local JMX client of your choice.
The example below uses `jconsole`.
Replace `KEYSTORE_PASSWORD` with the keystore password that you recorded in a previous step:
<pre class="terminal">
$ jconsole -J-Djavax.net.ssl.trustStore=/lib/home/jcert/localhost.truststore -J-Djavax.net.ssl.trustStorePassword=KEYSTORE_PASSWORD
</pre>
1. In the **Remote Process** field, enter the IP address of the Maximus
server, port number `44444`.
<br><br>
1. To complete the **Username** and **Password** fields, refer to the
**Credentials** tab of the Metrics tile in Pivotal Ops Manager.
By default, these credentials are `admin` and `admin`.
<%= image_tag("images/ssl/jconsole.png") %>
## <a id='generate'></a>Step 2: Generate a Self-Signed Certificate ##
Follow the steps below to generate a self-signed certificate on your server:
1. In Pivotal Ops Manager, click the **Pivotal Ops Metrics** tile.
1. Check **Enable SSL**.
1. Click **Generate Self-Signed RSA Certificate** and check the **Trust Self-Signed Certificates** box.
<%= image_tag("images/ssl/generate-ssl.png") %>
1. Enter your system and application domains in wildcard format.
Optionally, also add any custom domains in wildcard format.
Click **Generate.**
<%= image_tag("images/ssl/generate.png") %>
1. Select and copy the certificate.
<%= image_tag("images/ssl/copy.png") %>
1. Paste the certificate into a text file and save as `ops-metrics.cer`.
## <a id='import'></a>Step 3: Import the Self-signed Certificate to a Truststore ##
Follow the steps below to import the self-signed certificate to your client:
1. Copy `ops-metrics.cer` from your server to your client.
1. Navigate to the client directory where you copied the saved certificate.
1. Use `keytool -import` to import the certificate with an alias of `ops-metrics-ssl` to the truststore `localhost.truststore`:
<pre class="terminal">
$ keytool -import -alias ops-metrics-ssl -file ops-metrics.cer -keystore localhost.truststore
</pre>
* If `localhost.truststore` already exists, a password prompt appears.
Enter the keystore password that you recorded in a previous step.
* If `localhost.truststore` does not exist, you must create a password.
1. Verify the details of the imported certificate.
## <a id='start'></a>Step 4: Start a Monitoring Tool with the Truststore ##
Once you import the self-signed certificate to the `localhost.truststore`
truststore on the client, you must instruct your monitoring tool to use the
truststore.
On a command line, start your monitoring tool with the location and password of the truststore as follows:
1. Pass the location of `localhost.truststore` to the monitoring tool using
the `javax.net.ssl.trustStore` property.
1. Pass the truststore password using the `javax.net.ssl.trustStorePassword`
property.
Example starting jConsole:
<pre class="terminal">
$ jconsole -J-Djavax.net.ssl.trustStore=/lib/home/jcert/localhost.truststore -J-Djavax.net.ssl.trustStorePassword=KEYSTORE_PASSWORD
</pre>
1. Enter a fully-qualified hostname. This hostname must exist in a subdomain covered by your certificate.
<p class='note'><strong>**Note**</strong>: You must enter a fully-qualified
hostname, not an IP address.
</p>
Your monitoring tool should now communicate with your server through the
SSL connection.