What's New in 5.4 for System Administrators

Release Overview

There are several platform changes that affect System Administrators responsible for maintaining on premise Percussion CMS implementations.

For Percussion Cloud / SaaS customers these changes are largely transparent as Percussion handles the upgrade and system administration for you.

CMS - Application Server Changes

Previous versions of Percussion included an embedded JBOSS application server. This application server is removed as part of the upgrade process to 5.4 and is replaced with the Jetty application server.

As part of the upgrade process, a backup of the 5.3 <InstallDir>/AppServer directory can be found in the following file:

<InstallDir>/AppServer_backup_<upgrade date>.zip

This directory could be copied and extracted to a temporary directory to retrieve any custom files that may have been deployed under the AppServer directory prior to upgrade.

SSL / TLS Changes

See configuring SSL/TLS for CM1. For instructions on configuring Percussion for https after upgrade.

Starting and Stopping the Server Changes

The methods for starting and stopping the Percussion instance on Linux and Windows have changed. Existing system services should be removed and new services should be installed after upgrade.

Manually starting the server as a stand alone process can be done by running <InstallDir>/jetty/StartJetty.sh on Linux or <InstallDir>\jetty\StartJetty.bat on Windows. Entering CTRL-C in the terminal window will shutdown the CM1 process. Starting the server this way is useful for testing / troubleshooting but is not practical for production use as the process will end when the user logs out. The recommended method for starting / stopping is to use the operating systems service manager.

See Updating the CM1 Service for more information.

Log File Location Changes

The location for CM1 log files has changed in this release. The new CM1 log location:

<InstallDir>/jetty/base/logs

Key Log Files:

server.log - This is the main system log file.
velocity.log - This log file contains output from the Velocity template engine and can be useful when debugging custom Widgets.
<day>.jetty.log - This log captures console output that is not passed through the normal logging engine.

Configuring Logging

Logging can be configured by editing the settings in the jetty/base/log4j2/log4j2.xml file. The logging system has been upgraded to Apache Log4j2 and any standard Log4j2 options are available. More information on configuring logging under CM1 5.4 can be found here.

Installation Logs

The installer writes logs to the following location:

<InstallDir>/rxconfig/Installer/install.log for CM1.

<InstallDir>/rxconfig/Installer/dts-install.log for DTS.

Application Server Layout

The application server layout uses a configuration overlay strategy.

jetty/base

The base directory contains user editable configuration files. Generally install / upgrade will not overwrite files within this directory with the exception of the webapps folder.

jetty/base/etc

The etc directory contains property files that can be used to configure the server, including datasources, SSL configuration, and port configuration. On upgrade the properties are populated with the configuration found in the old JBOSS AppServer/server/rx/deploy/jboss-web.deployer/server/xml configuration file.

jetty/base/start.d

Contains overiddes for files in the jetty/defaults/start.d folder. For example, to add your own environment specific settings like -XmX memory configuration, copying jvm.ini from defaults/start.d/jvm.ini to base/start.d/jvm.ini and making your changes there will override any default settings and the change will not be overwritten on upgrade / patch updates.

jetty/base/resources

Contains the log4j2.xml logging configuration file.

jetty/base/lib/jdbc

Contains the jdbc drivers that are available to use in Percussion database configurations. You may place any JDBC drivers not included by the system in this location and they will be available for use in datasources at runtime.

jetty/base/data

This directory contains the ActiveMQ temporary disk store used by the publishing engine.

jetty/base/logs

This directory contains the application server logs.

jetty/base/perc-cache

This directory contains cache files used by the application at runtime.

jetty/defaults

This directory contains Percussion default settings. These configuration files can be extended / overridden by creating equivalent copies of the files in the base folder. This folder will always be overwritten on upgrade / patch updates. We recommend that end users do not modify the contents of this directory.

jetty/upstream

This directory will always be overwritten on upgrade / patch updates with the latest Jetty application server version. We recommend that end users do not modify the contents of this directory.

DTS Application Server Changes

The DTS application server has been updated to include Apache Tomcat 9.31. This includes a number of security updates and improvements to Tomcat.

Tomcat Server Configuration

The configuration of the DTS is similar to previous versions but there are some new changes to take into account.

Tomcat 9 Changes

Tomcat 9 changes the configuration of the server.xml, introducing new configuration options and deprecating others. As a result, this file is overwritten on upgrade. A backup of this file is created in the Deployment/Server/conf/server.xml.5.3 location.

The server.xml has been updated to externalize many common properties of the server.xml. These properties can now be found in the following locations:

Production DTS: Deployment/Server/conf/perc/perc-catalina.properties

Staging DTS: Staging/Deployment/Server/conf/perc/perc-catalina.properties

The property file will not be overwritten on upgrade / patch updates.

Logging Changes

The Logging system has been updated to Log4j2. In general DTS service logs have been quieted in this release, with a default configuration to show only errors.

Configuration locations:

DTS Micro Services:

Production DTS: Deployment/Server/conf/perc/<service>-log4j2.xml
Staging DTS: Staging/Deployment/Server/conf/perc/<service>-log4j2.xml

Tomcat / General:

Production DTS: Deployment/Server/log4j2/conf/log4j2-tomcat.xml
Staging DTS: Staging/Deployment/Server/log4j2/conf/log4j2-tomcat.xml

SSL / TLS Changes

See configuring SSL/TLS for DTS. For instructions on configuring the DTS server for https after upgrade.

Service Installer Changes

The following scripts can be used to uninstall and reinstall the DTS Service on Linux and Windows specifically. Existing services should be uninstalled, and then reinstalled after upgrade.

Production DTS: Deployment/Server/DTSProductionService.bat
Staging DTS: Staging/Deployment/Server/DTSStagingService.bat

Joined Installation Path Behavior Change

For installations that have CM1 and DTS installed in the same directory, the system will no longer auto start the DTS when the CM1 service starts. The DTS service should be installed separately and is responsible for starting the DTS.

Native Microsoft SQL Server JDBC Driver

Support was added for the native Microsoft SQL Server JDBC driver for both the CM1 Application Server and the DTS Application Server. This is intended as a replacement for the open source JTDS driver for Microsoft SQL Server as it is actively maintained and updated for recent Microsoft SQL Server versions. We recommend the Microsoft native driver over the JTDS driver going forward.

Java Runtime

The system is certified on OpenJDK/JRE 1.8, and ships with the Amazon Corretto distribution of the Open JRE Runtime by default. Previous versions included the Oracle JRE 1.7.

Trusting Certificates at Startup

A common issue when keeping the JRE up to date is that trusted certificates, like private LDAP certificate authorities for use with secure LDAP, were lost after updating the JRE. A new feature has been introduced where the system will scan the rxconfig/secure_certificates folder and startup, and will import all certificates present in this directory into the trust store at server startup. This also allows simplifies the updating trusted certificates; to update a trusted cert, simply update the certificate file in the secure_certificates folder and restart the percussion service.

JMX Support

Many of the components included with Percussion support Java Management Extensions and can be configured to allow for Management and Monitoring via tools the leverage the JMX standard. The Java default configuration for JMX is not secure by default. After upgrading, all JMX services will be disabled by default. Through updating the configuration JMX can be enabled by customers that want to leverage it.

See Enabling JMX Support for more information.