--- title: Upgrading the administrative node description: Upgrade the PingAccess administrative node using the PingAccess Upgrade Utility. You will use the -r switch to disable configuration replication on the target version. component: pingaccess version: 9.0 page_id: pingaccess:pingaccess_zero_downtime_upgrade:pa_upgrading_the_admin_node canonical_url: https://docs.pingidentity.com/pingaccess/9.0/pingaccess_zero_downtime_upgrade/pa_upgrading_the_admin_node.html revdate: March 27, 2024 section_ids: before-you-begin: Before you begin about-this-task: About this task steps: Steps example: Example: result: Result: example-2: Example: result-2: Result: choose-from: Choose from: next-steps: Next steps --- # Upgrading the administrative node Upgrade the PingAccess administrative node using the PingAccess Upgrade Utility. You will use the `-r` switch to disable configuration replication on the target version. ## Before you begin For more information on upgrading PingAccess, see [Upgrading PingAccess](../upgrading_pingaccess/pa_upgrading_pa_landing_topic.html). ![This flowchart shows a deployment as the administrative node is upgraded.](_images/zil1564006855826.png) In the previous flowchart: 1. A user with a WebSession Cookie sends a request to the load balancer. 2. The load balancer directs the request to one of three engine nodes, which are all using the source version of PingAccess 3. The administrative node is using the target version of PingAccess. Before beginning the upgrade process, make sure you have: * Ensured PingAccess is running * Downloaded the PingAccess [distribution](https://www.pingidentity.com/en/resources/downloads/pingaccess.html) `.zip` file or the incremental update bundle and extracted it. * The PingAccess license, if you are switching to a new license file * Administrator credentials * Basic Authentication enabled ## About this task Any warnings or errors encountered are recorded in `log/upgrade.log`, as well as on the screen while the utility is running. The upgrade uses an exit code of `0` to indicate a successful upgrade and an exit code of `1` to indicate failure. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | If you are upgrading from version 4.3 or earlier, and your installation uses custom plugins, they will need to be rebuilt against the new (5.0) Software Development Kit (SDK) *(tooltip: \
\

A set of tools that allows a developer to build a custom application that integrates with or connects to a platform or service.\

\
)*. You will then run the upgrade utility manually with the new `-i` command-line option to specify a directory containing the custom plugin jars and only the custom plugin jars. To migrate your custom plugins, see the [PingAccess Addon SDK for Java Migration Guide](../agents_and_integrations/pa_add_on_sdk_for_java_migration_guide.html). | During the upgrade, it is important to not make any changes to the running PingAccess environment. ## Steps 1. If you are using the upgrade utility, change to the new version's `/upgrade/bin` directory on the command line. For example: ``` cd /pingaccess-6.1.0/upgrade/bin ``` 2. If you are using the incremental update bundle, disable configuration replication for the replica administrative node. 1. In a browser, go to https\://*\*:*\*/pa-admin-api/v3/api-docs/. ### Example: https\://localhost:9000/pa-admin-api/v3/api-docs/ 2. Expand the **/adminConfig/replicaAdmins** endpoint. 3. Click the **GET /adminConfig/replicaAdmins** operation. 4. Click **Try it out!** and note the `id` for the replica admin. 5. Click the **GET /adminConfig/replicaAdmins/{id}** operation. 6. Enter the `id` of the replica admin you want to update and click **Try it out!** 7. Copy the **Response Body**. 8. Click the **PUT /adminConfig/replicaAdmins/{id}** operation and enter the `id` of the replica admin you want to update. 9. Paste the **Response Body** you copied and change `"configReplicationEnabled"` to `false`. 10. Click **Try it out!** ### Result: If the operation is successful, you will receive a **Response Code** of **200**. 3. If you are using the incremental update bundle, disable configuration replication for each engine node. 1. In a browser, go to https\://*\*:*\*/pa-admin-api/v3/api-docs/. ### Example: https\://localhost:9000/pa-admin-api/v3/api-docs/ 2. Expand the **/engines** endpoint. 3. Click the **GET /engines** operation. 4. Click **Try it out!** and note the engine `id` for each engine. 5. Click the **GET /engines/{id}** operation. 6. Enter the `id` of the engine you want to update and click **Try it out!** 7. Copy the **Response Body**. 8. Click the **PUT /engines/{id}** operation and enter the `id` of the engine you want to update. 9. Paste the **Response Body** you copied and change `"configReplicationEnabled"` to `false`. 10. Click **Try it out!** ### Result: If the operation is successful, you will receive a **Response Code** of **200**. 4. Upgrade the system: ### Choose from: * If you are using the upgrade utility on a Windows system, use this command: `upgrade.bat -r ] ] ] ] [-s \| --silent] `. For example: ``` upgrade.bat -r ../pingaccess-5.3.0 ``` * If you are using the upgrade utility on a Linux system, use this command: `./upgrade.sh -r ] ] ] ] [-s \| --silent] `. For example: ``` ./upgrade.sh -r ../pingaccess-5.3.0 ``` * If you are using the incremental update package, open the readme file and make the file changes specified in the readme. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The `-r` switch will disable configuration replication on the administrative node. You will re-enable configuration replication for each node as part of the upgrade process. | **Parameter definitions** The command-line parameters are the same regardless of the platform, and are defined as follows: | Parameter | Value description | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | -r \| --disable-config-replication | Disables configuration replication on the administrative node. | | -p <*admin\_port*> | Optional port to be used by the temporary PingAccess instance run during the upgrade. The default is 9001. | | -i <*directory*> | An optional directory containing additional library JAR files (for example, plugins, JDBC drivers) to be copied into the target installation.Beginning in version 6.0, JAR files are stored in the `/deploy` folder.During an upgrade from versions earlier than 6.0, third-party JAR files are migrated from the `lib` folder to the `deploy` folder if no directory is specified.During an upgrade from version 6.0 or later, the contents of the `deploy` folder are migrated to the new `/deploy` folder if no directory is specified. | | <*sourcePingAccessRootDir*> | The PA\_HOME for the source PingAccess version. | | -l <*newPingAccessLicense*> | An optional path to the PingAccess license file to use for the target version. If not specified, the existing license is reused. | | -j <*jvm\_memory\_options\_file*> | An optional path to a file with Java Virtual Machine (JVM) *(tooltip: \
\

A virtual machine that allows a computer to run Java programs and programs that are compiled to Java bytecode.\

\
)* memory options to use for the new PingAccess instance during the upgrade. | | -s \| --silent | Run the upgrade with no user input required. To use this option, specify the source version's credentials using environment variables. | **Environment Variables** You can specify the username and password for the source version using these environment variables: | Environment variable | Description | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PA_SOURCE_API_USERNAME` | The username for the source version's Admin application programming interface (API) *(tooltip: \
\

A specification of interactions available for building software to access an application or service.\

\
)*. This should be set to Administrator. | | `PA_SOURCE_API_PASSWORD` | The basic authorization password for the Administrator in the source version's Admin API. | **JVM Memory options** These options can be included in the JVM memory options file. Memory amounts use `m` or `g` to specify the unit. | Memory option | Description | | ------------------------- | ------------------------------------------------------------- | | `-Xms` | Minimum heap size. | | `-Xmx` | Maximum heap size. | | `-XX:NewSize=` | Minimum size for the Young Gen space. | | `-XX:MaxNewSize=` | Maximum size for the Young Gen space. | | `-XX:+UseParallelGC` | Specifies that the parallel garbage collector should be used. | For example: ``` #Sample JVM Memory options file -Xms512m -Xmx1g -XX:NewSize=256m -XX:MaxNewSize=512m -XX:+UseParallelGC ``` You can copy the existing `PA_HOME/conf/jvm-memory.options` file to create a JVM memory options file for the upgrade. 5. Stop the existing PingAccess admin instance. 6. Start the new PingAccess admin instance. ## Next steps | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If PingAccess is running as a service, and you upgraded using the upgrade utility:- In Linux, update **PA\_HOME** in `/etc/systemd/system/pingaccess.service` to point to the new installation. - In Windows, remove the existing PingAccess service (`\sbin\Windows\uninstall-service.bat`) and add the new service (`\sbin\Windows\install-service.bat`). | After you have upgraded the administrative node, you can [upgrade the replica admin node](pa_upgrading_the_replica_admin_node.html).