How to enable SSL support

Enabling HTTPS (SSL) support for Apache

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/

Configuration Steps

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.
```
source /usr/local/groundwork/scripts/setenv.sh
```
```
cd /usr/local/groundwork/common/openssl/certs
```
```
openssl genrsa -out server.key 2048
```
```
openssl req -new -x509 -key server.key -out server.pem -days 1095 -sha256 -set_serial `date +%s`
```
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.
```
You are about to be asked to enter information that will be incorporated into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank. For some fields there will be a default value.
If you enter '.', the field will be left blank.
Country Name (2 letter code) [GB]:
State or Province Name (full name) [Berkshire]:
Locality Name (eg, city) [Newbury]:
Organization Name (eg, company) [My Company Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (eg, your name or your server's hostname) []:
Email Address []:
```
- 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
```
mv server.key server-crypt.key
openssl rsa -in server-crypt.key -out server.key
```
  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:
```
c_rehash
```

Verify your certificate:

openssl verify /usr/local/groundwork/common/openssl/certs/*.pem

Symbolically link the certificate and key to the default apache certificate location:

ln -s /usr/local/groundwork/common/openssl/certs/server.pem /usr/local/groundwork/apache2/conf/server.crt
ln -s /usr/local/groundwork/common/openssl/certs/server.key /usr/local/groundwork/apache2/conf/server.key

Edit the file:

/usr/local/groundwork/apache2/conf/httpd.conf

Remove the # symbol in the lines below:

Replace my-server with the Common Name (hostname to be used in the browser address bar):

#LoadModule rewrite_module modules/mod_rewrite.so
#Include conf/extra/httpd-ssl.conf
#RewriteEngine On
#RewriteCond %{SERVER_PORT} !^443$
#RewriteRule ^/(.*)$ [https://my-server/$1] [NE]

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:

/usr/local/groundwork/apache2/conf/httpd.conf

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;

Edit:

/usr/local/groundwork/apache2/conf/extra/httpd-ssl.conf

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

SSLCertificateFile "/usr/local/groundwork/apache2/conf/server.crt"
SSLCertificateKeyFile "/usr/local/groundwork/apache2/conf/server.key"

The next change is for the case where you have a single chain certificate:

SSLCertificateChainFile "/usr/local/groundwork/apache2/conf/server-ca.crt"

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.

SSLCACertificatePath "/usr/local/groundwork/common/openssl/certs/"

Edit:

/usr/local/groundwork/config/status-viewer.properties

and change:

secure.access.enabled=true

Edit:

/usr/local/groundwork/config/report-viewer.properties

and change:

secure.access.enabled=true

Edit the following file and change the protocol from http: to https: for the properties gatewayLoginUrl and gatewayLogoutUrl:
```
/usr/local/groundwork/config/josso-agent-config.xml
```
Edit the following file and change the protocol from http: to https: for the propertiesgatein.sso.josso.base.url and gatein.sso.portal.url:
```
/usr/local/groundwork/config/configuration.properties
```
Example:
```
gatein.sso.portal.url=https://myserver.mydomain.com
```
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:
```
source /usr/local/groundwork/scripts/setenv.sh
```
```
keytool -import -file /usr/local/groundwork/apache2/conf/server.crt -alias myserver.mydomain.com -keystore /usr/local/groundwork/java/jre/lib/security/cacerts
```
- 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:
```
source /usr/local/groundwork/scripts/setenv.sh
```
```
keytool -import -file /usr/local/groundwork/apache2/conf/chain.pem -alias myserver_chain -keystore /usr/local/groundwork/java/jre/lib/security/cacerts
```

Edit the following files replacing http with https on lines starting with GatewayLoginUrl and GatewayLogoutUrl. Save the files.

/usr/local/groundwork/apache2/conf/groundwork/apache2-noma.conf

/usr/local/groundwork/apache2/conf/groundwork/foundation-ui.conf

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 does not exist, then you are running single-JBoss; if it does exist, then you are running dual-JBoss:
```
/usr/local/groundwork/core/services/service-foundation/
```
On a GroundWork server that is running a single-JBoss setup, add these lines:
```
// Foundation URL
const FOUNDATION_URL = "http://localhost:8080/foundation-webapp/services/";
// Foundation REST API URL
const FOUNDATION_REST_URL = "http://localhost:8080/foundation-webapp/api";
```
On a GroundWork server that is running a dual-JBoss setup, add these lines instead:
```
// Foundation URL
const FOUNDATION_URL = "http://localhost:8180/foundation-webapp/services/";
// Foundation REST API URL
const FOUNDATION_REST_URL = "http://localhost:8180/foundation-webapp/api";
```

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 does not exist, then you are running single-JBoss; if it does exist, then you are running dual-JBoss:

/usr/local/groundwork/core/services/service-foundation/

On a GroundWork server that is running a single-JBoss setup, run these commands:

cd /usr/local/groundwork/perl/lib/site_perl/5.8.9/GW
sed -i.backup RAPID.pm \
    -e 's:if ( defined $options ):if (defined($protocol) and $protocol =~ m{^http$}i and\
            defined($hostname) and $hostname eq "localhost") {\
            $restport = 8080;\
            $basepath = "/foundation-webapp/api";\
        }\
        if ( defined $options ):' \
    -e 's/$options->{restport};/$options->{restport} if defined $options->{restport};/'

On a GroundWork server that is running a dual-JBoss setup, run these commands instead:

cd /usr/local/groundwork/perl/lib/site_perl/5.8.9/GW
sed -i.backup RAPID.pm \
    -e 's:if ( defined $options ):if (defined($protocol) and $protocol =~ m{^http$}i and\
            defined($hostname) and $hostname eq "localhost") {\
            $restport = 8180;\
            $basepath = "/foundation-webapp/api";\
        }\
        if ( defined $options ):' \
    -e 's/$options->{restport};/$options->{restport} if defined $options->{restport};/'

Stop and Start gwservices:

/usr/local/groundwork/ctlscript.sh stop gwservices

/usr/local/groundwork/ctlscript.sh stop apache

/usr/local/groundwork/ctlscript.sh start gwservices

/usr/local/groundwork/ctlscript.sh start apache

You may now bring up the site in a browser using https, for example:
```
https://myserver.mydomain.com
```

How to enable SSL support

Enabling HTTPS (SSL) support for Apache

Configuration Steps

Labels