How to enable SSL support

h1. Enabling HTTPS (TLS) support for Apache

GroundWork Monitor supports the use of HTTPS with SSL (technically with TLS) 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/|http://httpd.apache.org/docs/2.2/ssl/]

h6. Contents
{toc:minLevel=4|maxLevel=5|printable=false}

h4. 1.0 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.
{noformat}
source /usr/local/groundwork/scripts/setenv.sh
{noformat}
{noformat}
cd /usr/local/groundwork/common/openssl/certs
{noformat}
{noformat}
openssl genrsa -out server.key 2048
{noformat}
{noformat}
openssl req -new -x509 -key server.key -out server.pem -days 1095 -sha256 -set_serial `date +%s`
{noformat}
{note}The back-quotes surrounding the date-command invocation (`date \+%s`) are used to capture its output and substitute it into the command line.{note}
#* 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.
{noformat}
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 []:
{noformat}
# Install the cert to the openssl certificate store:
{noformat}
c_rehash
{noformat}
# Verify your certificate:
{noformat}
openssl verify /usr/local/groundwork/common/openssl/certs/*.pem
{noformat}
# Symbolically link the certificate and key to the default apache certificate location:
{noformat}
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
{noformat}
{note}in 7.1.0, you may need to remove existing default files /usr/local/groundwork/apache2/conf/server.crt and /usr/local/groundwork/apache2/conf/server.key before creating the above symlinks.{note}
# Edit the file {{*/usr/local/groundwork/apache2/conf/httpd.conf{*}}}
#* comment out the Listen 80:
{noformat}
#Listen 80
{noformat}
#* uncomment the following lines:
{noformat}
LoadModule rewrite_module modules/mod_rewrite.so
Include conf/extra/httpd-ssl.conf
{noformat}
# Next, you will need to update the ServerName directive and possibly the certificate names in the {{{*}conf/extra/httpd-ssl.conf{*}}} file.
#* Edit:
{noformat}
/usr/local/groundwork/apache2/conf/extra/httpd-ssl.conf
{noformat}
#* Change the *ServerName* directive to match the *Common Name* of the server where the certificate is being used. Don't append any port number (e.g. :443) to the ServerName.
#* The certificate filename is specified in this file as well, so 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 will have to make changes to reflect the certificate files you are using. If you just created your own self signed cert with the default names, then you won't need to change the names here. If you need to, 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{*}}}.
{noformat}
SSLCertificateFile "/usr/local/groundwork/apache2/conf/server.crt"
SSLCertificateKeyFile "/usr/local/groundwork/apache2/conf/server.key"
SSLCertificateChainFile "/usr/local/groundwork/apache2/conf/server-ca.crt"
{noformat}
{note}Remember, these are conditional changes, not necessarily needed. Also keep in mind that the certificates you use 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{note}
# Edit:
{noformat}
/usr/local/groundwork/config/cacti.properties
{noformat}
and change the lines:
{noformat}
cacti.1.host=localhost
cacti.1.protocol=http
cacti.1.port=80
{noformat}
to:
{noformat}
cacti.1.host=myserver.mydomain.com
cacti.1.protocol=https
cacti.1.port=443
{noformat}
{note}Replace {{{*}myserver.mydomain.com{*}}} with the certificate *Common Name/hostname* in the line above.{note}
If you have multiple cacti hosts configured, make the changes for all of them (cacti.2.host, cacti.3.host, etc.)
# Edit:
{noformat}
/usr/local/groundwork/config/status-viewer.properties
{noformat}
and change:
{noformat}
secure.access.enabled=true
{noformat}
# Edit:
{noformat}
/usr/local/groundwork/config/report-viewer.properties
{noformat}
and change:
{noformat}
secure.access.enabled=true
{noformat}
# Edit the following file and change the protocol from {{{*}http:*}} to {{{*}https:*}} for the properties {{{*}gatewayLoginUrl{*}}} and {{{*}gatewayLogoutUrl{*}}}:
{noformat}
/usr/local/groundwork/config/josso-agent-config.xml
{noformat}
Example:
{noformat}
<property name="gatewayLoginUrl">
<value>https://myserver.mydomain.com/josso/signon/login.do</value>
</property>

<property name="gatewayLogoutUrl">
<value>https://myserver.mydomain.com/josso/signon/logout.do</value>
</property>
{noformat}
# Edit the following file and change the protocol from {{{*}http:*}} to {{{*}https:*}} for the properties {{{*}gatein.sso.josso.base.url{*}}} and {{{*}gatein.sso.portal.url{*}}}:
{noformat}
/usr/local/groundwork/config/configuration.properties
{noformat}
Example:
{noformat}
gatein.sso.josso.base.url=https://${gatein.sso.josso.host}/josso/signon

gatein.sso.portal.url=https://myserver.mydomain.com
{noformat}
# 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, or modify the keytool command to import the certificate you plan to use:
{noformat}
source /usr/local/groundwork/scripts/setenv.sh
{noformat}
{noformat}
keytool -import -file /usr/local/groundwork/apache2/conf/server.crt -alias myserver.mydomain.com -keystore /usr/local/groundwork/java/jre/lib/security/cacerts
{noformat}
{note}Replace {{{*}myserver.mydomain.com{*}}} with the certificate *Common Name* in the command above.{note}
#* 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{*}}}:
{noformat}
source /usr/local/groundwork/scripts/setenv.sh
{noformat}
{noformat}
keytool -import -file /usr/local/groundwork/apache2/conf/chain.pem -alias myserver_chain -keystore /usr/local/groundwork/java/jre/lib/security/cacerts
{noformat}
# Edit the following files replacing {{{*}http{*}}} with {{{*}https{*}}} on lines starting with {{{*}GatewayLoginUrl{*}}} and {{{*}GatewayLogoutUrl{*}}}. Save the files.
{noformat}
/usr/local/groundwork/apache2/conf/groundwork/apache2-noma.conf
{noformat}
{noformat}
/usr/local/groundwork/apache2/conf/groundwork/foundation-ui.conf
{noformat}
# Edit the JOSSO HTTP server connector to configure a secure proxy from Apache.
#* For GroundWork Monitor version 7.1.1 (or prior versions):
\\
\\
{noformat}
/usr/local/groundwork/foundation/container/josso-1.8.4/conf/server.xml
{noformat}
Change
{noformat}
<Connector connectionTimeout="20000" port="8888" protocol="HTTP/1.1" redirectPort="8443"/>
{noformat}

# Edit both the standalone and dual JBoss HTTP server connector to configure the secure proxy from apache here:
{noformat}
/usr/local/groundwork/foundation/container/jpp/standalone/configuration/standalone.xml
{noformat}
and, (if dual will be installed),
{noformat}
/usr/local/groundwork/foundation/container/jpp/dual-jboss-installer/standalone.xml
{noformat}
and, (if dual is already installed),
{noformat}
/usr/local/groundwork/foundation/container/jpp2/standalone/configuration/standalone.xml
{noformat}
Change
{noformat}
<connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>
{noformat}
to
{noformat}
<connector name="http" protocol="HTTP/1.1" scheme="https" socket-binding="http" proxy-name="myserver.mydomain.com" proxy-port="443" secure="true"/>
{noformat}
{note}Replace {{{*}myserver.mydomain.com{*}}} with the certificate *Common Name/hostname* in the line above.{note}
# Stop and Start gwservices:
{noformat}
/usr/local/groundwork/ctlscript.sh stop gwservices
{noformat}
{noformat}
/usr/local/groundwork/ctlscript.sh stop apache
{noformat}
{noformat}
/usr/local/groundwork/ctlscript.sh start gwservices
{noformat}
{noformat}
/usr/local/groundwork/ctlscript.sh start apache
{noformat}
# You may now bring up the site in a browser using *https*, for example:{noformat}
https://myserver.mydomain.com
{noformat}

h4. 2.0 GDMA Notes

h5. 2.1 GDMA Plugins

When using HTTPS and downloading GDMA plugins, the <Server Name> must exactly match what is in the server's SSL certificate (typically, a fully-qualified name). For more information regarding downloading new GDMA plugins see the Bookshelf document [GDMA Advanced|https://kb.groundworkopensource.com/display/DOC71/GDMA+Advanced#GDMAAdvanced-2.3TellGDMAtoDownloadthePlugins].&nbsp;{color:#333333}See also&nbsp;{color}[Using GDMA with HTTPS]{color:#333333}.{color}

h5. 2.2 GDMA Version

If you use an old version of GDMA and need to transition to the current version you may need to keep port 80 open with a redirect to port 443. This should be seen as a temporary measure and disabled when you no longer have older agents in operation.
# To make this change edit the file:
{noformat}/usr/local/groundwork/apache2/conf/httpd.conf{noformat}
# Verify the following is uncommented (commented out in a step above):
{noformat}Listen 80{noformat}
# Uncomment the lines below:
{noformat}
RewriteEngine On
RewriteCond %{SERVER_PORT} !^443$
RewriteRule ^/(.*)$ https://my-server/$1 [NE]
{noformat}
{note}Replace {{{*}my-server{*}}} with the *Common Name* (hostname to be used in the browser address bar).{note}
{warning}When making this change any traffic that arrives at port 80 will be redirected in Apache to port 443.{warning}
# Save the changes you've just made to:
{noformat}
/usr/local/groundwork/apache2/conf/httpd.conf
{noformat}