Update of an existing installation

This page describes how to upgrade security.manager NEXT to a newer version. The upgrade affects all components of security.manager NEXT:

Before the upgrade

Note the upgrade notes in the Release Notes of the current version as well as all versions that lie between the current version and the version you have installed so far.

Preparation

Before upgrading the security.manager NEXT components, unzip the installation file security.manager-NEXT-1.2.0.zip into an arbitrary folder. This will create the folder security.manager-NEXT-1.2.0 that will be referred to as [SECMAN-DIR] in these docs.

Upgrade the Manager UI

To identify the running version of the Manager UI before or after an upgrade, open https://<tomcat-host>/secman-next/info.txt in a browser.

Follow these steps to update the Manager UI:

  1. Determine the data directory (parameter data.directory.location) configured in [TOMCAT]\webapps\secman-next\WEB-INF\classes\custom-application.properties. The directory contains custom configuration of the current installed version of security.manager NEXT. The value is needed for restoring it later.

  2. Stop the Apache Tomcat server where the Manager UI is installed.

  3. Remove the old Manager UI context from [TOMCAT]\webapps (move it to a backup folder before deleting it completely).

  4. Extract the file [SECMAN-DIR]\secman-next.war to [TOMCAT]\webapps.

  5. Edit the file [TOMCAT]\webapps\secman-next\WEB-INF\classes\custom-application.properties and change the property data.directory.location to the previously determined value.

  6. Restart the Apache Tomcat server.

  7. Check the Manager UI version as described above.

Upgrade the CLI

The application secmanctl is shipped as an executable file for Windows and Linux operating systems (x86-64 architecture). It is also available as a package in the public npm registry. Depending on which type of installation was used before, there are basically two possibilities to upgrade an existing installation:

  • If the shipped executables were installed, you should update them with those shipped by the new release.

  • If the application was installed from the public npm registry, you should update them by using npm.

Upgrading installed executables

The secmanctl files are located in the following directory:

  • [SECMAN-DIR]/cli/linux_x64 for Linux.

  • [SECMAN-DIR]\cli\windows_x64 for Windows.

Follow these steps to upgrade the manually installed files:

  1. Determine the current installation path.

    • On Linux by executing the command which secmanctl.

    • On Windows by executing the command where secmanctl.

  2. Delete all previously installed files from the installation path.

  3. Copy all new files from the directory mentioned above to the installation path.

  4. Check the new version of the CLI by executing the command secmanctl --version. The version should be 1.2.0.

Upgrading the npm package

Follow these steps to upgrade the npm package:

  1. Perform the update by executing the command npm update -g @conterra/secmanctl.

  2. Check the new version of the CLI by executing the command secmanctl --version. The version should be 1.2.0.

Upgrade the SOI

Important notes about the upgrade

  • In contrast to the following instructions, upgrading the SOI version 1.0.0 to a newer version requires you to delete and reinstall the SOI. If you currently have version 1.0.0 installed, please follow the instructions in section Upgrade SOI version 1.0.0.

  • Please make sure you have upgraded the CLI before upgrading the SOI.

  • We recommend you to backup existing policies via the CLI before upgrading the SOI.

  • The SOI update will stop all services where the SOI is active. Please manually start these services after the SOI update.

  • Existing policies will get lost if you delete the SOI via the ArcGIS Server Manager. Please make sure not to delete the SOI extensions, but to upgrade them. If you have accidentally deleted an extension, you can restore previously backed up policies via the CLI.

Execute the upgrade

Please follow these steps to upgrade the SOI:

  1. Upgrade the SOI via the ArcGIS Server Manager:

    1. Sign in to ArcGIS Server Manager and navigate to the Site section. Open the Extensions area.

    2. Perform an upgrade of the two installed SOE files via Edit extension action.

      • Upgrade the ct-security-soi-arcmap.soe extension with the file of the same name from [SECMAN-DIR].

      • Upgrade the ct-security-soi-arcgispro.soe extension with the file of the same name from [SECMAN-DIR].

      • Verify that the version of the upgraded extensions shown in the column Display Name contains the version 1.2.0.

  2. Verify that previously existing policies are still set. You have the following options to do this:

    1. Verify the policies via the Manager UI.

    2. Or verify the policies via the CLI. The sync command (including the --dry option) should not show any differences between active and backed up policies:

      $ secmanctl sync -f ./backup_policies -d https://gis.example.com:6443/arcgis -t MghzyNeWubQtT.. --dry

Congratulations! You successfully finished the upgrade process. Now, get familiar with the new features of security.manager NEXT.

Upgrade SOI version 1.0.0

With the release of security.manager NEXT 1.1.0, the shipped SOE files were renamed:

  • ct-security-soi-1.0.0-arcmap.soe was renamed to ct-security-soi-arcmap.soe

  • ct-security-soi-1.0.0-arcgispro.soe was renamed to ct-security-soi-arcgispro.soe

It is required to delete the old SOI via the ArcGIS Server Manager before uploading the new version of the SOI.

When deleting the old SOI, existing policies will get lost! During the upgrade process, the policies will be backed up and restored via the CLI command sync. Do not use any existing policy working directory for the backup.

Please make sure you have upgraded the CLI before upgrading the SOI.

Follow these steps to upgrade the SOI:

  1. Backup all existing policies:

    1. Create a local backup directory, for example backup_policies. Create a subdirectory backup_policies/services.

    2. Execute the CLI sync command in combination with the --reverse option:

      $ secmanctl sync --reverse -f ./backup_policies -d https://gis.example.com:6443/arcgis -t MghzyNeWubQtT..

    3. Make sure, no error occured and check the backup folder for completeness.

  2. Upgrade the SOI via the ArcGIS Server Manager:

    1. Sign in to ArcGIS Server Manager and navigate to the Site section. Open the Extensions area.

    2. Delete the two installed SOE files (this will delete all policies!):

      • ct-security-soi-1.0.0-arcmap.soe

      • ct-security-soi-1.0.0-arcgispro.soe

    3. Click Add Extension to upload both SOE files from [SECMAN-DIR].

  3. Execute the sync command (now without the --reverse option) to restore the policies from backup_policies:

    $ secmanctl sync -f ./backup_policies -d https://gis.example.com:6443/arcgis -t MghzyNeWubQtT..

    Check the output for errors. If all policies have been applied, you can safely delete the backup folder.

Congratulations! You successfully finished the upgrade process. Now, get familiar with the new features of security.manager NEXT.