Using GDMA with HTTPS

Version 3 by Bren Eckles
on Jan 13, 2014 13:34.

compared with
Current by Bren Eckles
on Nov 30, 2016 11:14.

Key
This line was removed.
This word was removed. This word was added.
This line was added.

Changes (14)

View Page History
h5. 1.1 Dealing with certificates

Before you begin to address GDMA client setup for HTTPS, you must take the first steps toward configuring Apache and Java within GroundWork Monitor to support HTTPS. Instructions for doing so can be found in [How to enable SSL support] page in the Bookshelf. For purposes of supporting GDMA over HTTPS, the key parts are the creation of the server private key file ({{/usr/local/groundwork/apache2/conf/server.key}}), an initial server certificate ({{/usr/local/groundwork/apache2/conf/server.crt}}), and (optionally) an initial empty revocation list, though of course you will need to complete the rest of the server setup as well.

A server certificate can be either generated locally and self-signed, or obtained from a Certificate Authority. The additional steps for dealing with a Certificate Authority, making a certificate request, and dealing with the file you get back from them, are beyond the scope of this document.
For GDMA purposes, you will need a certificate for your GroundWork Monitor server, as generated via the instructions noted above, and (if desired) a Certificate Revocation List (CRL) file. The CRL file is allowed and used if present, but is not required by the GDMA client software.  You may put one in play even if you know of no certificates that should be revoked. The GDMA software uses the CRL, if present, so that customers who might actually want to revoke certain certificates have the built-in capability to do so.

Managing SSL certificates with OpenSSL, as we will do below, is a broad topic. Here, we will only scratch the surface. If you want more details, dive into the OpenSSL documentation, such as these pages, as [OpenSSL documentation|http://www.openssl.org/docs/] as well as other sources on the Internet:.
* [http://www.openssl.org/docs/]
* [http://www.openssl.org/docs/apps/openssl.html]
* [http://www.openssl.org/docs/apps/genrsa.html]
* [http://www.openssl.org/docs/apps/req.html]
* [http://www.openssl.org/docs/apps/ca.html]
* [http://www.openssl.org/docs/apps/crl.html]

Specifics of the server-side configuration for supporting GDMA are given below, in the [#GroundWork Monitor server setup for HTTPS] section.
Specifics of the server-side configuration for supporting GDMA are given in the [GroundWork Monitor server setup for HTTPS|#SetupHTTPS] section below.

{note:title=Forewarned should be forearmed}
* Certificate management is made a lot easier if you establish certain conventions from the beginning, such as numbering your certificate and revocation-list files so you can tell which is which when new ones appear in your infrastructure. The commands we show in this document adopt a simple standard for such numbering. You can adopt whatever policies and conventions you want for your own site, but you should definitely think about such issues in advance of deploying SSL in your infrastructure.
{note}
{anchor:Direct}

h5. 1.2 Direct use of the GroundWork server name as the Target Server

Previous instructions on setting up GDMA clients sometimes recommended use of the virtual {{gdma-autohost}} name for the GroundWork Monitor server in the {{Target_Server}} parameter on the GDMA client, this being the default Target Server hostname provided by the GDMA installer.  Use of the virtual hostname, which would need to be resolved by your DNS to point to the GroundWork server, allows a level of indirection in how that name is interpreted. (See interpreted, (for further details see the GDMA Quick Start document in the section [Auto Configuration Setup|GDMA Quick Start#Auto Configuration Setup] section for further details.) Setup]).

With the use of SSL certificates, that convention is no longer possible because the hostname in the {{Target_Server}} parameter must exactly match the hostname used in the SSL certificate, and the hostname in the SSL certificate must match the hostname of the GroundWork server in order for the certificate to be seen as valid for accessing that server. (Use of the {{gdma-autohost}} name as the value of the {{GDMA_Auto_Host}} parameter can continue as before, because this use of the name is not tied to the use of SSL certificates. It relates to content passed over the connection to the server, not the establishment of the connection.)

Because matching the name is so critical, setting of the {{Target_Server}} value to the appropriate server name is called out later in this document, for both existing GDMA clients and for new GDMA clients. "Matching" means an exact match: either fully qualified or unqualified, exactly as contained within the certificate. If you're not sure of the name, you can see the exact hostname contained within a certificate named {{server_01.pem}} with the following command where the displayed {{CN}} field will contain the hostname;:
{code:none}
cd /usr/local/groundwork/gdma/certs
/usr/local/groundwork/common/bin/openssl x509 -noout -text -in server_01.pem \
| fgrep Subject:
h4. 2.0 Transitioning your Infrastructure to HTTPS

Customers who have many GDMA clients will naturally want to know how to transition all of them from HTTP to HTTPS, and whether a big-bang approach is required. The transition plan depends on your current setup. See [How For details see the Bookshelf document [How to enable SSL support] for details.

* *HTTP (GDMA 2.3.1 or earlier) to HTTPS (GDMA 2.3.2 or later)* --- Here are the steps:

Supporting GDMA communication over HTTPS requires both server-side and client-side configuration.
{Anchor:SetupHTTPS}

h5. 4.1 GroundWork Monitor server setup for HTTPS
cp -p server.crt server_01.pem
{code}
# Finish setting up Apache and Java on the GroundWork Monitor server to use HTTPS, as documented in the [How to enable SSL support] Bookshelf page. That will include bouncing both {{apache}} and {{gwservices}}, as listed at the end of that procedure.

h5. 4.2 Upgrading existing clients from HTTP to HTTPS
Target_Server = "https://gwserver.mydomain.com"
{code}
# In that {{Target_Server}} value, be sure that you use exactly the same server name, unqualified or qualified, as you used when you created the certificate for that server. (See [#Direct server, for details see [Direct use of the GroundWork server name as the Target Server] for details.) Server|#Direct] section on this page).
# Restart GDMA on the client.

Once your server runs with HTTPS, installing new GDMA clients to use HTTPS is easy.

# When the installer asks for the Target Server hostname, specify the name of the GroundWork Monitor server exactly as it is included in your SSL certificate. (See [#Direct certificate, for details see [Direct use of the GroundWork server name as the Target Server] for details.) Server|#Direct] section on this page).
# When the installer asks for the protocol to use for communication with the GroundWork server, select HTTPS.
# When the installer asks whether you wish to start the GDMA service after the installation, select No. (This question is not asked during a Windows GDMA install.)