How to enable SSL support

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/

Contents

1.0 To Enable SSL support in GroundWork Monitor

  1. 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.
  2. 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.
  3. 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.
  4. 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 []:
  5. Install the cert to the openssl certificate store: 
    c_rehash
  6. Verify your certificate: 
    openssl verify /usr/local/groundwork/common/openssl/certs/*.pem
  7. 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
    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.
  8. Edit the file /usr/local/groundwork/apache2/conf/httpd.conf
    • comment out the Listen 80: 
      #Listen 80
    • uncomment the following lines: 
      LoadModule rewrite_module modules/mod_rewrite.so
Include conf/extra/httpd-ssl.conf
  9. Next, you will need to update the ServerName directive and possibly the certificate names in the conf/extra/httpd-ssl.conf file.
    • Edit: 
      /usr/local/groundwork/apache2/conf/extra/httpd-ssl.conf
    • 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. 
      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"
      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
  10. Edit: 
    /usr/local/groundwork/config/cacti.properties

    and change the lines:

    cacti.1.host=localhost
cacti.1.protocol=http
cacti.1.port=80

    to:

    cacti.1.host=myserver.mydomain.com
cacti.1.protocol=https
cacti.1.port=443
    Replace myserver.mydomain.com with the certificate Common Name/hostname in the line above.

    If you have multiple cacti hosts configured, make the changes for all of them (cacti.2.host, cacti.3.host, etc.)

  11. Edit: 
    /usr/local/groundwork/config/status-viewer.properties

    and change:

    secure.access.enabled=true
  12. Edit: 
    /usr/local/groundwork/config/report-viewer.properties

    and change:

    secure.access.enabled=true
  13. 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

    Example:

    <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>
  14. 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: 
    /usr/local/groundwork/config/configuration.properties

    Example:

    gatein.sso.josso.base.url=https://${gatein.sso.josso.host}/josso/signon
gatein.sso.portal.url=https://myserver.mydomain.com
  15. 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: 
    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
    Replace myserver.mydomain.com with the certificate Common Name in the command above.
    • 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
  16. 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
  17. 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
  18. Edit the JOSSO HTTP server connector to configure a secure proxy from Apache.
    • For GroundWork Monitor version 7.1.1 (or prior versions): 

      /usr/local/groundwork/foundation/container/josso-1.8.4/conf/server.xml

      Change

      <Connector connectionTimeout="20000" port="8888" protocol="HTTP/1.1" redirectPort="8443"/>

      to

      <Connector address="127.0.0.1" connectionTimeout="20000" port="8888" protocol="HTTP/1.1" scheme="https" proxy-name="myserver.mydomain.com" proxy-port="443" secure="true"/>
      Replace myserver.mydomain.com with the certificate Common Name/hostname in the line above.
  19. Edit both the standalone and dual JBoss HTTP server connector to configure the secure proxy from apache here: 
    /usr/local/groundwork/foundation/container/jpp/standalone/configuration/standalone.xml

    and, (if dual will be installed),

    /usr/local/groundwork/foundation/container/jpp/dual-jboss-installer/standalone.xml

    and, (if dual is already installed),

    /usr/local/groundwork/foundation/container/jpp2/standalone/configuration/standalone.xml

    Change

    <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>

    to

    <connector name="http" protocol="HTTP/1.1" scheme="https" socket-binding="http" proxy-name="myserver.mydomain.com" proxy-port="443" secure="true"/>
    Replace myserver.mydomain.com with the certificate Common Name/hostname in the line above.
  20. 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
  21. You may now bring up the site in a browser using https, for example: 
    https://myserver.mydomain.com

2.0 GDMA Notes

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. See also Using GDMA with HTTPS.

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.

  1. To make this change edit the file: 
    /usr/local/groundwork/apache2/conf/httpd.conf
  2. Verify the following is uncommented (commented out in a step above): 
    Listen 80
  3. Uncomment the lines below: 
    RewriteEngine On
RewriteCond %{SERVER_PORT} !^443$
RewriteRule ^/(.*)$ https://my-server/$1 [NE]
    Replace my-server with the Common Name (hostname to be used in the browser address bar).
    When making this change any traffic that arrives at port 80 will be redirected in Apache to port 443.
  4. Save the changes you've just made to: 
    /usr/local/groundwork/apache2/conf/httpd.conf
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.