GroundWork Monitor supports the use of SSL for encrypting web browser connections to Apache, although this feature is not enabled by default. If you would like to enable this feature, you must first create or import an SSL Certificate for Apache to use, and then enable the SSL support in the appropriate Apache configuration file(s). The binaries and libraries necessary to enable SSL support are included in the GroundWork Monitor distribution. The steps below outline how to enable SSL for the Apache Web Server.
For more information, please refer to the Apache site at: http://httpd.apache.org/docs/2.2/ssl/
To enable SSL support in GroundWork Monitor:
- If you have an existing SSL certificate and key file for your web server that you wish to reuse, you must edit the /usr/local/groundwork/apache2/conf/extra/httpd-ssl.conf file to reference those files. The files must also have permissions that will allow them to be read by the Apache server on startup. A common situation in which you would use existing files would be if they were obtained from an external certificate authority.
- It is important that the person who generates the certificate correctly specifies the Common Name. It must match the hostname where the certificate will be used exactly. In particular, the choice of fully qualified name or unqualified (short) name has to be consistent with all the ways that SSL will be invoked, not only for Apache content but also JOSSO requests. A mismatch here will create odd rejections.
- A further area of concern is the factor of chained certificates. If the issuing authority provides such a chain certificate make sure that the details such as issuing authority match with the server certificate.
- If you wish to create new self-signed certificate and key files, log in to the system as the root user and use the commands below from a terminal session. This will ensure appropriate default file names and certificate settings, and correct permissions are used.
The back-quotes surrounding the date-command invocation (`date +%s`) are used to capture its output and substitute it into the command line.
- This command will create a certificate good for 3 years from the date of manufacture; -days 1095. You might wish to specify a longer period, such as 10 years; -days 3653, to move the expiration date even further into the future.
- The -set_serial option specifies a hopefully-unique serial number for this certificate, in contrast to the fixed default of 0. Using a different value for this option each time you create a certificate helps to avoid problems with some browsers. The integer timestamp produced by the date command shown above in this context provides sufficient uniqueness for ordinary use.
- Answer the questions asked by the last command shown above. When prompted for the Common Name, enter the hostname that will be used for all access to the Groundwork Monitor Web Interface.
- Possible Passphrase Issue
If you supplied a passphrase when you made the certificate request, then you will need to be on hand to enter that correctly every time the Apache web service is started. To avoid this necessity, you will need to remove the passphrase from the key. You can do so in the following way
When prompted you must enter the passphrase you used when creating the key. The unencrypted key will be generated. If you used a different name than "server.key" be sure you make the appropriate change.
- Install the cert to the openssl certificate store:
- Verify your certificate:
- Symbolically link the certificate and key to the default apache certificate location:
- Edit the file:
- Remove the # symbol in the lines below:
Replace my-server with the Common Name (hostname to be used in the browser address bar): When making this change you must make sure that you open access from the outside world to the GroundWork server over ports 443 AND port 80. The port 80 connection is not obvious. Any traffic that arrives at port 80 will be redirected in Apache to port 443. This includes the situation where you already have GDMA running under port 80 and need to continue that capability while you make a gradual conversion.
- Save the changes you've just made to:
- Remove the # symbol in the lines below:
- The certificate name is identified in the file conf/extra/httpd-ssl.conf. If you did not create it with the default name, if you are using a differently named certificate provided by an authority, or if you are using a chain of authority, you may have to make changes as follows. If you just created your own self signed cert with default names skip this next step;
- Change the ServerName directive to match the Common Name of the certificate being used.
- Change these lines to match the actual certificate file name in place of server.crt and server.key; and the chain certificate server-ca.crt.
Remember, these are conditional steps, not necessarily needed. Also keep in mind that the certificates must be in the proper format and that it may be necessary to validate these with the openssl tool and potentially separate component certificates in order to import them correctly
The next change is for the case where you have a single chain certificate:
If you do not have a single chain certificate, but instead have multiple certificates which are referenced, then make the change as follows instead of the file.
- Edit the following file and change the protocol from http: to https: for the properties gatewayLoginUrl and gatewayLogoutUrl:
- Edit the following file and change the protocol from http: to https: for the propertiesgatein.sso.josso.base.url and gatein.sso.portal.url:
- Import the certificate to the java keystore. Assuming you used the default certificate name server.crt in step 2, you should import this certificate with the following commands:
- Use the certificate Common Name as *myserver.mydomain.com*
- The keytool will ask for the java keystore password. By default this is *changeit*
- It will also ask if the cert should be trusted. You should answer *yes*
- If you are using a chain certificate, import it to the java keystore. With the following commands, change the certificate name to what you actually have where it shows chain.pem and a unique name instead of myserver_chain:
- Edit the following files replacing http with https on lines starting with GatewayLoginUrl and GatewayLogoutUrl. Save the files.
- This next step needs to be done for Business Service Monitoring to work correctly with https/ssl.
Only for versions prior to 7.0.2
This step applies to GroundWork Monitor Enterprise versions before and not including 7.0.2.
You will need to insert, right before the last close-brace (}) at the end of the file, 4 lines in the /usr/local/groundwork/config/rstools/config.php file. To decide what lines to add, first check to see whether you are running a single-JBoss instance or a dual-JBoss instance. If the following directory exist, then you are running single-JBoss; if it exist, then you are running dual-JBoss:
On a GroundWork server that is running a single-JBoss setup, add these lines:
On a GroundWork server that is running a dual-JBoss setup, add these lines instead:
- When setting up SSL on your GroundWork Monitor server you will need to apply these additional instructions.
Only for version 7.0.2
This step applies to GroundWork Monitor Enterprise version 7.0.2.
To decide what commands to run, first check to see whether you are running a single-JBoss instance or a dual-JBoss instance. If the following directory exist, then you are running single-JBoss; if it exist, then you are running dual-JBoss:
On a GroundWork server that is running a single-JBoss setup, run these commands:
On a GroundWork server that is running a dual-JBoss setup, run these commands instead:
- Stop and Start gwservices:
- You may now bring up the site in a browser using https, for example: