PingAuthorize

Manual upgrades

Upgrading PingAuthorize Server manually

Perform the following steps to upgrade a PingAuthorize server.

Steps

  1. Download and unzip the new version of PingAuthorize Server in a location outside the existing server’s installation.

    For these steps, assume the existing server installation is in /opt/pingauthorize/PingAuthorize and the new server version is extracted into /home/stage/PingAuthorize.

  2. Provide a copy of the PingAuthorize license file for the version to which you are upgrading in the /home/stage/PingAuthorize directory, or give the location of the license file to the tool using the --licenseKeyFile option.

  3. Run the update tool provided with the new server package to update the existing PingAuthorize Server.

    The update tool might prompt for confirmation on server configuration changes if it detects customization.

    Example:

    /home/stage/{pingauthorize}/update --serverRoot /opt/pingauthorize/{pingauthorize}

Reverting an update

After you’ve updated PingAuthorize Server, you can revert to the previous version (one level back) using the revert-update tool.

About this task

The revert-update tool accesses a log of file actions taken by the updater to put the file system back to its previous state. If you have run multiple updates, you can run the revert-update tool multiple times to sequentially revert to each prior update. You can only revert back one level at a time with the revert-update tool. For example, if you had to run the update twice since first installing PingAuthorize Server, you can run the revert-update tool to revert to its previous state, then run the revert-update tool again to return to its original state.

When starting the server for the first time after running a revert, the server displays warnings about "offline configuration changes," but these are not critical and will not appear during subsequent start-ups.

Steps

  • Run revert-update in the server root directory to revert back to the most recent previous version of the server, as shown in the following example:

    /opt/pingauthorize/{pingauthorize}/revert-update

Upgrading the PingAuthorize Policy Editor manually

If you originally installed the PingAuthorize Policy Editor using .zip files, use this procedure to upgrade the Policy Editor when a new version is released.

Steps

  1. In your current Policy Editor, complete the steps in Backing up policies.

  2. Stop the Policy Editor.

    $ bin/stop-server

  3. Obtain the new version of the PingAuthorize Policy Editor and extract it to a location outside the existing Policy Editor’s installation.

  4. Prepare the existing policy database.

    The new server installation might require changes to the policy database structure.

    Choose from:

    • If you store your policies in the H2 policy database, copy the existing database. The server setup tool performs these upgrades and generates a new configuration.xml file.

      This example assumes the old installation is in /opt/pingauthorize/PingAuthorize-PAP-previous, and the new installation is in /opt/pingauthorize/PingAuthorize-PAP. Run the following commands to upgrade from each version:

      Step 8.1 and later
      $ cp /opt/pingauthorize/{pingauthorize}-PAP-previous/Symphonic.mv.db opt/pingauthorize/{pingauthorize}-PAP
      Step 8.0 earlier
      $ cp /opt/pingauthorize/{pingauthorize}-PAP-previous/admin-point-application/db/Symphonic.mv.db opt/pingauthorize/{pingauthorize}-PAP

    • If you store your policies in a PostgreSQL database, follow the instructions for Upgrading a PostgreSQL policy database.

  5. Run the setup tool.

    Updating PingAuthorize Server uses an update tool. However, PingAuthorize Policy Editor does not have this tool. Instead of updating the Policy Editor in-place, you must install the new Policy Editor.

    The setup tool uses the default credentials to upgrade the database. If the credentials no longer match the default values, provide the correct credentials to the setup tool using the appropriate command-line options:

    • If you are using the default H2 policy database implementation, provide the non-default values using the --dbAdminUsername, --dbAdminPassword, --dbAppUsername, and --dbAppPassword command-line options. Otherwise, setup fails when it cannot access the H2 policy database, or it might reset credentials to their default values. For more information, see Manage policy database credentials.

    • If you are using a PostgreSQL policy database implementation, provide the server runtime user value through the --dbAppUsername command-line option. For the server runtime password, provide this value to the PING_DB_APP_PASSWORD environment variable before server start.

    Follow the instructions in either of the following topics:

  6. Start the new Policy Editor.

    Follow the instructions in Post-setup steps (manual installation).

  7. In the new Policy Editor, complete the steps in Upgrading the Trust Framework and policies.