Upgrading Portal Dedicated to 6.10

warning

If upgrading from Portal Dedicated 4.x see the “Migrating events from earlier versions“ section.

warning

When using Oracle it will be required to run the configuration script with repair option -r.

warning

If SAML is configured for SSO please ensure you have a non-SAML account to login with before proceeding as SAML can only be fully re-configured from within the service.

info

Download and extract the new Portal Dedicated artefact before proceeding.

Copying existing configuration

The new version reuses 3 configuration files from the old version. It is recommended to make backups on the new configuration files before copying over the old versions.

info

All these commands are run from the root folder of the new Portal Dedicated installation.

application.properties

Most of the Portal Dedicated configuration is centralized in the application.properties file

1. Make a backup of the application.properties provided in the new release:

   cp application.properties application.properties.bak

2. Copy application.properties from the previous release:

cp ../waratek-mc-<version-build>/application.properties .

controller.keystore.p12

Copying this file from the previous release is only required if it was changed

1. Make a backup of the controller.keystore.p12 provided in the new release:

cp controller.keystore.p12 controller.keystore.p12.bak

2. Copy controller.keystore.p12 from the previous release:

cp ../waratek-mc-<version-build>/controller.keystore.p12 .

logging.xml

Copying this file from the previous release is only required if it was changed

1. Make a backup of the logging.xml provided in the new release:

cp logging.xml logging.xml.bak

2. Copy logging.xml from the previous release:

cp ../waratek-mc-<version-build>/logging.xml .

Updating the ReadonlyREST Configuration is not required if updating from version 5.5.x

Updating ReadonlyREST Configuration

warning

These are the following changes required for the Java Agent v22.2.4+ to ensure that the Elasticsearch connectivity startup check is performed. Without the following steps, the Java Agent (v22.2.4+) won’t be able to connect to Portal Dedicated.

The readonlyrest configuration should be updated to allow Agents perform status checks on the Elasticsearch cluster.

1. Find the readonlyrest.yml file. Note that the file distributed with the MC is a sample file. The actual configuration lives in the config directory of the Elasticsearch installation.

2. Update the file. It is easiest to apply the changes manually in a text editor to avoid formatting issues:

   1. Add HEAD to methods property values
   2. Add "cluster:monitor/main" to actions property values

For reference, the before snippet:

methods: [PUT, POST]
actions: ["indices:data/write/bulk", "indices:data/write/index"]

And after:

methods: [PUT, POST, HEAD]
actions: ["indices:data/write/bulk", "indices:data/write/index", "cluster:monitor/main"]

Running upgrade script

The configuration script used during installation is also used for upgrading the Portal Dedicated and is located in the scripts directory.

When upgrading the script:

• Updates the systemd service script with the new Portal Dedicated location
• Updates the path to the certificate keystore
• Provisions the database using Flyway

info

The script must be run as root in order to complete these tasks

warning

The upgrade script relies on the application.properties file containing the correct database credentials so the steps above must be completed before continuing.

The script takes a single option when running an upgrade:

sudo ./scripts/configureManagementConsole.sh -a

producing output similar to:

User 'management-console' already exists
Creating management-console service scripts
Configuring logging directory at /var/log/management-console
Configuring Management Console database: jdbc:postgresql://localhost:5432/management_console
Running Flyway migration scripts
WARNING: DB: there is already a transaction in progress (SQL State: 25001 - Error Code: 0)
WARNING: DB: there is already a transaction in progress (SQL State: 25001 - Error Code: 0)
Management Console successfully installed.
Please follow the Installation Guide for additional configuration options for /opt/waratek/waratek-mc-5.5.0/application.properties
To start the Management Console run: sudo systemctl start management-console

Upgrading with Oracle Database

If you are using Oracle for your Portal Database, then you need to repair the database during the upgrade process, by including an extra parameter -r or --database-repair in the configuration script.

More information about configuration script options can be found in the Basic Automated Configuration page**.**

Migrating SAML Settings

Portal Dedicated 6.9 contains changes to how SAML integration is configured.

1. The application.properties now requires 2 optional properties, only required if SAML authentication requests/response should be signed or if assertions are encrypted. These properties were previously:

spring.security.saml2.relyingparty.registration.ping.signing.credentials[0].private-key-location=file:/opt/waratek/mc-private.key
spring.security.saml2.relyingparty.registration.ping.signing.credentials[0].certificate-location=file:/opt/waratek/mc.crt
spring.security.saml2.relyingparty.registration.ping.decryption.credentials[0].private-key-location=file:/opt/waratek/mc-private.key
spring.security.saml2.relyingparty.registration.ping.decryption.credentials[0].certificate-location=file:/opt/waratek/mc.crt

and are now migrated into 2 properties:

waratek.security.authentication.saml.relyingparty.certificate=file:/opt/waratek/mc.crt
waratek.security.authentication.saml.relyingparty.private-key=file:/opt/waratek/mc-private.key

2. The property specifying the IdP metadata in application.properties is no longer required and should be removed:

spring.security.saml2.relyingparty.registration.ping.assertingparty.metadata-uri=file:/opt/waratek/metadata.xml

To complete the SAML integration, the Portal Dedicated must then be started/restarted.

Once the Portal Dedicated has been started, follow the instructions in Installation Guide > Integrations > Integration with SAML. When you get to the step of uploading the IdP file, use the IdP file which was previously specified in application.properties.

Done

The Portal Dedicated service has now been successfully updated.