Enable HTTPS

Enabling SSL

Enabling SSL on Jetty requires the enablement of the jetty ssl and https modules. Prior to enabling these modules, stop the jetty service if it is running.

Running PercussionCMS on Port 80 / 443

You can update the <InstallDir>/jetty/base/etc/installation.properties file to have the CMS use the default HTTP/HTTPS ports 80 and 443 instead of the default 9992 / 8443. On Linux systems this requires that the PercussionCMS service be installed to run as the root user in order for it to use the privileged ports (any ports below <1024). The properties that control the ports used are:

jetty.ssl.port=443

jetty.http.port=80

Turning on SSL Support

Note that the commands below assume a Terminal session with sudo access on Linux and a Command Prompt running as Administrator on Windows. They also assume that when you installed the Percussion service that you used the default service name of PercussionCMS. If you have used a different service name, please replace PercussionCMS in the examples below with your custom name.

Linux:

sudo service PercussionCMS stop

Windows:

net stop PercussionCMS

Enabling the SSL and HTTPS modules:

NOTE: The below commands will NOT start the jetty service. The StartJetty script has a number of options that can be used to manage the jetty server.

Linux:

cd {Percussion}/jetty/
./StartJetty.sh --add-to-start=ssl,https
Windows:
cd {Percussion}\jetty\
StartJetty.bat --add-to-start=ssl,https
 

These commands will return similar output to that below:

# ./StartJetty.sh --add-to-start=ssl,https

Found Jetty service PercussionCMS in /etc/default/PercussionCMS pointing to jetty base /{Percussion}/jetty/base

This instance is currently installed as service PercussionCMS

/var/run/rxjetty/PercussionCMS

INFO  : https   initialized in ${jetty.base}/start.d/https.ini

INFO  : ssl   initialized in ${jetty.base}/start.d/ssl.ini

COPY  : ${jetty.home}/modules/ssl/keystore to ${jetty.base}/etc/keystore

INFO  : Base directory was modified

Existing Java Keystore and Password After Upgrade

The upgrade will relocate your configured Java keystore to the following location:

Linux

<InstallDir>/jetty/base/etc/<keystoreFileName>

Windows

<InstallDir>/jetty/base/etc/<keystoreFileName>

Jetty SSL is configured by updating the <InstallDir>/jetty/base/etc/installation.properties file.

The following properties in <installDir>/jetty/base/etc/installation.properties are the minimum needed for a working https configuration:

jetty.ssl.port=8443

jetty.sslContext.keyStorePath=etc/Your.keystore

jetty.sslContext.trustStorePath=etc/Your.keystore

jetty.sslContext.keyStorePassword=yourpassword

jetty.sslContext.keyManagerPassword=yourpassword

jetty.sslContext.trustStorePassword=yourpassword

perc.ssl.protocols=TLSv1.2

Example Java Keystore

When the https and ssl modules were enabled, the system creates an example Java keystore in the <InstallDir>/jetty/base/etc/keystore location if the file does not exist. This file can be ignored if you are specifying your own keystore. The example keystore is configured with a self signed certificate and will show security errors from the browser when trying to access the site, but can be a good way to verify that ssl is enabled.

Creating a new Keystore With an Existing Valid Certificate

If you are configuring SSL/HTTPS with Percussion for the first time, the steps below provide an example of

Example 1: OpenSSL (PEM) Public & Private Key

cd <InstallDir>/jetty/base/etc

openssl pkcs12 -export -chain -in /path/to/cert/my.crt -inkey /path/to/key/my.key.pem -out keystore.p12 -name training.percussion.com -CAfile /path/to/bundle/bundle.crt

This command will generate a PKS12 standards based keystore, which can now be imported to a J2SE keystore.

keytool -importkeystore -srckeystore keystore.p12 -srcstoretype PKCS12 -destkeystore keystore.jks

You may receive the following warning, this can be ignored.

Warning:

The JKS keystore uses a proprietary format. It is recommended to migrate to PKCS12 which is an industry standard format using "keytool -importkeystore -srckeystore keystore.jks -destkeystore keystore.jks -deststoretype pkcs12".

Example 2: PFX (X.509) File

This example shows the process for importing a pfx formatted certificate.

keytool -importkeystore -srckeystore mycert.pfx -srcstoretype PKCS12 -destkeystore keystore.jks

One the keystore is generated and your certificate imported.

Once the installation.properties are configured, the Jetty service may be restarted and Percussion should now be accessible via HTTPS on the configured jetty.ssl.port.

Redirecting HTTP requests to HTTPS

Update <InstallDir>/rxconfig/Server/server.properties to include an entry for:

requireHTTPS=true

The Percussion service must be restarted for the change to take effect.

Disabling HTTPS after it is enabled

To disable HTTPS on Percussion you must first shut down the Percussion server.

After the server is shutdown, delete these files:

{InstallDir}/jetty/base/start.d/ssl.ini
{InstallDir}/jetty/base/start.d/https.ini

Edit the <InstallDir>/jetty/base/etc/installation.properties file and comment out (#), or delete the following properties:

jetty.ssl.port=8443

jetty.sslContext.keyStorePath=etc/Your.keystore

jetty.sslContext.trustStorePath=etc/Your.keystore

jetty.sslContext.keyStorePassword=yourpassword

jetty.sslContext.keyManagerPassword=yourpassword

jetty.sslContext.trustStorePassword=yourpassword

perc.ssl.protocols=TLSv1.2

Edit the <installDir>/rxconfig/Server/server.properties file

requireHTTPS=false

The Percussion service must be restarted for the change to take effect.