Upgrading the Application Protector Java

• 1: About Upgrade Agent
• 2: Installing the Upgrade Agent
• 3: Setting Up the Upgrade Agent
• 3.1: Upgrade Configurations
• 3.2: Rollback Behavior
• 3.3: Protegrity SDK Upgrade Permissions and Deployment
• 3.3.1: User Roles and Groups
• 3.3.2: Component Overview
• 3.3.3: Recommended File and Folder Permissions
• 4: AP Java Upgrade and Rollback Examples
• 4.1: Online and Offline Upgrade
• 4.2: Online and Offline Rollback

1 - About Upgrade Agent

The Upgrade Agent is a new component introduced in the AP Java 10.1.0 build package to enable upgrade capability. It is the core module that provides safe, automated, coordinated, and reversible upgrades for AP Java protectors.

The Upgrade Agent is responsible for upgrading the AP Java protector, regardless of whether it is online or offline. It also handles rollback operations for online and offline protectors. To ensure seamless upgrades in the future without needing to stop the protector application, it is essential to install the Upgrade Agent before running the protector application.

Features of AP Java Upgrade Agent

• Ensures that protection operations are never interrupted during an upgrade.
• Supports upgrades and rollbacks for protectors.
• Executes upgrade and rollback operations on a single node in a coordinated manner.
• Monitors and coordinates multiple protector processes.
• Automatically creates backups of existing components to enable safe and reliable restoration during rollback.

Note:
Only one protector type is supported per node. The upgrade agent can upgrade only one protector at a time and currently supports AP Java only.

Upgrading AP Java also upgrades the shared RP Agent (RPA) and Log Forwarder components. If additional protectors (for example, AP Python) are installed on the same node, they must be manually upgraded to a version compatible with the upgraded AP Java core, because RPA and Log Forwarder are shared across protectors.

For more information about core version compatibility, refer to the README.

After a successful upgrade, the Upgrade Agent automatically creates a backup of the previous protector version at /opt/protegrity/upgrader/backup/.
The backup includes:

• AP Java protector directory
• RP Agent directory
• Log Forwarder directory

This backup is required for rollback operations.

2 - Installing the Upgrade Agent

Agent‑based upgrade is supported only when AP Java version 10.1.0 or later is already installed.

The Agent coordinates AP Java upgrade, takes backup, validates signatures, and manages services during upgrade or rollback operation.

To perform seamless upgrades in the future without stopping the protector, ensure that the Upgrade Agent is installed before running the protector.

Installation Scenarios

Fresh Installation - Manual, Without Upgrade Agent

• Fresh installation must be performed manually.
• The Upgrade Agent is not used during fresh installation.
• Agent upgrader installation is silent which means there are no prompts or user interaction.

To perform the fresh installation of SDK Upgrader:

When you extract the ApplicationProtector_Linux-ALL-64_x86-64_JRE-1.8-64_<version>.tgz package, the UpgradeAgentSetup_Linux_x64_<version>.sh agent installer file is extracted along with other files.

For more information about extracting the build package, refer to Extracting the Setup Scripts and Package.

Run the AP Java installer using the following command.

./UpgradeAgentSetup_Linux_x64_<version>.sh

The SDK Upgrader Agent installation starts.

*****************************************************
Welcome to the SDK Upgrader Agent Setup Wizard
*****************************************************

This will install the SDK Upgrader Agent on your computer.
Unpacking...
Extracting files...

Protegrity SDK Upgrader Agent is installed in /opt/protegrity/upgrader.

Upgrading the Agent

Manual extraction of the product build .tgz is not required. If a newer Upgrade Agent is included, the agent self‑upgrades itself and prompts the user to re‑run the agent to continue the upgrade.

The installation of the new Upgrade Agent does not impact existing backups or log files. The update is limited to the following components:

• upgrader/bin/sdkupgrd binary
• upgrader/data/sdkupgrd.conf
• upgrader/data/metadata.ini

The installation directory is organized into clearly defined subdirectories.
For more information about the installation directory structure and the purpose of each subdirectory, refer to Installation Directory Structure Overview.

3 - Setting Up the Upgrade Agent

This section explains how users should interact with the Upgrade Agent for performing upgrades and rollback operations for AP Java protectors.

AP Java Upgrade allows you to upgrade the AP Java SDK, RP Agent, and Log Forwarder without stopping your applications.

Note: For both online and offline upgrade, you should not pass the path of the extracted local .tgz build file. The Upgrade agent must extract the .tgz file to generate the signatures/ directory.

Before performing an online or offline upgrade or rollback, review the following important considerations and limitations.

Scalability and Performance Considerations

With a policy size of approximately 5MB, upgrade and rollback operations are validated safely for up to 70 concurrent processes on the tested machine configuration.

Supported Deployment

• Ensure that only one RPA and one Log Forwarder are installed on the system.
• Upgrading multiple RPAs on the same host is not supported.
• Upgrading or rolling back only one version of AP Java at a time is allowed on the same host.

Log Forwarder Upgrade Behavior and Requirements

• The Upgrade Agent does not perform fresh installations of the Log Forwarder. The Log Forwarder must already be installed for the agent to upgrade it.
• To skip the Log Forwarder upgrade when it is not required or not installed, set the isFluentBit parameter to no in the sdkupgrd.conf file.
• If isFluentBit is set to yes in sdkupgrd.conf, you must also configure the Log Forwarder endpoint in the sdkupgrd.conf file.
• When Log Forwarder mode is set to error, upgrading renames the Log Forwarder directory from logforwarder to logforwarder_<new_version>.

Port Requirements for Error Mode

• If mode=error is enabled in config.ini, ensure that ports 15780 and 15781 are open.
• The Upgrade Agent uses port 15781 to run the new Log Forwarder during upgrade.
• Although port 15780 is released after an upgrade, it is required again if an online rollback is initiated.

Backup and Rollback Limitations

• Backup is maintained only for the most recent upgrade.
• Rollback is supported only for that most recent upgrade.

Online vs Offline Upgrade and Rollback Rules

• During upgrade or rollback, multiple AP Java installations on a node must be in a consistent state. All processes must be either running or stopped. Mixed process states are not supported.
• Offline upgrade and offline rollback requires all AP Java processes to be stopped, while online upgrade and online rollback requires at least one AP Java process to be running.

DevOps Flow Limitations

• When using the DevOps flow, only offline upgrade and rollback are supported.
• Online upgrade is not supported with the DevOps flow.
• To enable the DevOps flow, set the devops parameter to yes in the sdkupgrd.conf file.

Upgrade and Hot Reload Logging

A hot upgrade or reload refers to replacing AP Java JAR and PLM files while the AP Java process is running, without restarting the service.

• Protector hot-reload logs are created by the protector and stored under /opt/protegrity/upgrader/logs/<protector_version>/. Protector upgrade logs are not sent to Protegrity Insights.
• Upgrade Agent logs are created under /opt/protegrity/upgrader/logs/Agent/. When Fluent Bit is enabled, Upgrade Agent logs are removed after being successfully pushed to Protegrity Insights.

Viewing Upgrade Agent Audit Logs

Upgrade and rollback audit logs generated by the Upgrade Agent are available in Protegrity Insights.

To locate Upgrade Agent logs:

Index:

pty_insight_analytics*troubleshooting_*

Filter:

process.name: sdkupgrd

Use this filter to view audit and troubleshooting logs related specifically to Upgrade Agent execution, including upgrade and rollback activities.

Note: Upgrade is not supported if Log Forwarder contains custom configurations for forwarding audit logs to an external SIEM.

3.1 - Upgrade Configurations

View the Agent Help

Generic Agent Help

Before running any upgrade or rollback operation, run the agent help using the following command.

/opt/protegrity/upgrader/bin/sdkupgrd -h

OR

/opt/protegrity/upgrader/bin/sdkupgrd --help  
/opt/protegrity/upgrader/bin/sdkupgrd -help

This command displays all supported parameters and usage instructions.

The following help parameters are listed.

SDK Upgrader Agent Version: 1.0.0+5.g0493

Usage:
 ./sdkupgrd upgrade [--conf <path>] [--esa-user <user>] [--esa-password <pass>]
 ./sdkupgrd rollback
 ./sdkupgrd version | -v | --version
 ./sdkupgrd -h | --help | -help

Commands:
 upgrade                Upgrade agent and protectors to a new version
 rollback               Rollback agent and protectors to a previous version
 version                Display agent version information

Configuration:
 All parameters are read from data/sdkupgrd.conf
 Use --conf <path> to specify a custom conf file path

ESA Credentials (security):
 ESA username and password are NOT stored in the conf file.
 Provide via --esa-user / --esa-password arguments,
 or they will be prompted interactively (password is hidden).

For detailed help on a specific command:
 ./sdkupgrd upgrade -h
 ./sdkupgrd rollback -h

Agent Upgrade Help

Run the agent upgrade help using the following command.

/opt/protegrity/upgrader/bin/sdkupgrd upgrade -h

The following help parameters are listed.

SDK Upgrader Agent Version: 1.0.0+5.g0493

Usage:
 ./sdkupgrd upgrade [--conf <path>] [--esa-user <user>] [--esa-password <pass>]

Description:
 Upgrades the agent, RPAgent, LogForwarder, and protectors to a new version.
 Supports both online (ESA-connected) and offline upgrade modes.

Configuration keys (read from data/sdkupgrd.conf or --conf <path>):

  Key                     Description                                      Default
  ----------------------  -----------------------------------------------  --------------------------------
  location-of-build       URL or local path to the build file (REQUIRED)   -
  offline                 Enable offline upgrade mode (yes/no)              no
  rpagent-path            Path to RPAgent installation                     /opt/protegrity/rpagent
  logforwarder-path       Path to LogForwarder installation                /opt/protegrity/logforwarder
  endpoints               LogForwarder endpoints (comma-separated)         -
  protector-paths         Protector paths (comma-separated)                /opt/protegrity/sdk/java
  devops                  Enable DevOps mode / skip RPAgent (yes/no)       no
  isFluentBit             Enable LogForwarder upgrade (yes/no)              yes
  insecure                RPAgent insecure mode (yes/no)                   no
  esa-host                ESA server hostname or IP address                -
  esa-port                ESA server port                                 25400
  new-logforwarder-path   New logforwarder path (error mode)               /opt/protegrity/logforwarder_{version}
  stdout                  Print logs to console (yes/no)                   no
  debug                   Enable debug logging (yes/no)                    no

ESA Credentials (NOT stored in conf file for security):

  ESA username and password must be provided via CLI arguments or interactive prompt.
  They are never read from the conf file to prevent credential exposure.
  Password input is always masked/hidden for security.

  --esa-user <username>   ESA username (prompted interactively if not provided)
  --esa-password <pass>   ESA password (prompted with hidden input if not provided)

  Note: In DevOps mode (devops=yes), ESA credentials are not required.

Options:
 --conf <path>          Path to sdkupgrd.conf file (default: data/sdkupgrd.conf)
 --esa-user <username>  ESA username
 --esa-password <pass>  ESA password (hidden in logs, masked with *)
 -v, --version          Show agent version
 -h, --help             Show this help message

Examples:
 ./sdkupgrd upgrade                                              # interactive mode
 ./sdkupgrd upgrade --esa-user admin --esa-password secret       # credentials via args
 ./sdkupgrd upgrade --conf /path/to/sdkupgrd.conf                # custom conf file
 ./sdkupgrd upgrade --esa-user admin                             # password prompted

Agent Rollback Help

Run the agent rollback help using the following command.

/opt/protegrity/upgrader/bin/sdkupgrd rollback -h

The following help parameters are listed.

SDK Upgrader Agent Version: 1.0.0+5.g0493

Usage:
 ./sdkupgrd rollback

Description:
 Rolls back the agent, RPAgent, LogForwarder, and protectors to a previous version.
 Restores from the most recent backup created during an upgrade.

Options:
 -v, --version          Show agent version
 -h, --help             Show this help message

Examples:
 ./sdkupgrd rollback                                    # rollback with defaults
 ./sdkupgrd rollback --offline                          # rollback in offline mode

Note: The sdkupgrd rollback -h (or --help) output provides the lists command line options. However, the parameters, such as --offline, --stdout, and --debug are not supported on the command line. These parameters must be configured in the sdkupgrd.conf file instead.

GPG Signature Verification

The Upgrade Agent performs GPG signature verification before upgrade to ensure the integrity and authenticity of the build file. Ensure that the .gpg file is obtained from the ESA and placed in the /opt/protegrity/upgrader/bin/ directory for the signature verification.

Note: Without the .gpg file, the Upgrade Agent cannot verify or upgrade the protector.

To get the GPG encryption key from the ESA, which is in the /opt/verification_keys/ directory, run the following command on the protector machine.

sshpass -p <ESA root password> scp -r root@<ESA ip>:/opt/verification_keys/10.0.gpg /opt/protegrity/upgrader/bin

For more information about verification of signed protector build, refer to Verification of Signed Protector Build.

Build File Path

When initiating an upgrade, ensure that the compressed .tgz build file is available, or provide the build URL.

location-of-build = <path_to_build.tgz>

Caution: Do not set the path of the extracted .tgz build file manually. The Upgrade Agent expects the raw .tgz file and handles extraction internally.

Upgrade Modes Supported

The Upgrade Agent supports upgrades in two modes:

• Online upgrade: When AP Java application is running.
• Offline upgrade: When AP Java application is not running.

Offline upgrade mode should be used when:

• The application is manually stopped.
• DevOps deployment only supports offline upgrade.
  For more information about DevOps deployment, refer to DevOps Approach for Application Protector Java.

Upgrade Process

Protector Upgrade

For an upgrade, update the sdkupgrd.conf configuration file located in the data/ directory.

For more information about the configuration file, refer to SDK Upgrader Agent Configuration File.

ESA Credential Requirements

• ESA credentials, username and password are required when performing upgrade operations.

3.2 - Rollback Behavior

The Upgrade Agent restores all backed-up components to their previous state. Rollback supports both online and offline mode.

• If the backup folder is missing or deleted, rollback cannot proceed.
• Always verify that the backup directory exists before performing any rollback. The agent performs automatic rollback in case of upgrade failure.
• Rollback is supported only for the most recent upgrade, as a backup is created only for the last upgrade performed.

3.3 - Protegrity SDK Upgrade Permissions and Deployment

Overview

Protegrity deployments include the following components:

• Upgrade Agent
• Application Protector (AP) Java SDK
• Resilient Package (RP) Agent
• Log Forwarder

It requires a structured permission model to ensure that only authorized users can access protected resources. The permissions define the ability to execute, read, or modify protected resources. This section provides recommended user and group configurations, file and folder permissions, and step‑by‑step deployment guidance for a common use case.

3.3.1 - User Roles and Groups

Groups

User Configuration Examples

User and Group Setup Commands

This section provide commands to create users and groups on Linux.

sudo groupadd ptyadmin
sudo useradd -m -g ptyadmin ptyadmin
sudo useradd -m -g ptyadmin ptyuser1

Here, ptyuser1 uses ptyadmin as the primary group. PID files are created with the following ownership:

ptyuser1:ptyadmin

The Upgrade Agent can read the files with this permission automatically.

3.3.2 - Component Overview

All Protegrity components are owned and primarily run by the ptyadmin user. The following table lists the components and their ownership.

^* - All components are owned by ptyadmin.

The 10.0.gpg file is used by the Upgrade Agent for signature verification. However, it is not a part of the product build. Complete the following steps.

1. Copy it manually from the ESA machine.
2. Place it in upgrader/bin/.
3. Set permissions to 640.

3.3.3 - Recommended File and Folder Permissions

This section explains the required users and groups, core components, and recommended file permissions for running Protegrity Upgrade Agent and the AP Java SDK securely on Linux systems.

Note: The user running the Upgrade Agent must own the extracted old SDK build used for the upgrade. If a local path is configured in sdkupgrd.conf, the user must also own the downloaded new build.

The following tables describe which users can access specific directories under the Upgrade Agent installation and explain why these permissions are required.

• ptyadmin - Admin user who owns and manages the Upgrade Agent, RPAgent, and Log Forwarder.
• ptyuser1 - AP Java application user.

Upgrader Agent

The Upgrade Agent is always installed under /opt/protegrity/upgrader/.

AP Java SDK

RPAgent

Log Forwarder

4 - AP Java Upgrade and Rollback Examples

4.1 - Online and Offline Upgrade

This section outlines the online and offline upgrade of the Protegrity Application Protector (AP) Java.

In online mode, the upgrade runs without interrupting ongoing Java protector processes. The Protegrity Upgrade Agent manages state transitions, metadata updates, and version synchronization during the upgrade.

In offline mode, there are no protector processes that are in a running state.

Specifying Custom Configuration File Location

To perform an online upgrade, the offline parameter in the sdkupgrd.conf file must be set to no.
To perform an offline upgrade, the offline parameter in the sdkupgrd.conf file must be set to yes.

Before running the sdkupgrd binary, ensure to update the sdkupgrd.conf file with the required configuration values. By default, the configuration file is located at /opt/protegrity/upgrader/data/sdkupgrd.conf.

For more information about the configuration values, refer to SDK Upgrader Agent Configuration File.

To perform the upgrade:

1. Run the following command to start the upgrade.

   /opt/protegrity/upgrader/bin/sdkupgrd upgrade
   

   The prompt to add the ESA username and password appears.

   Note: If the configuration file is moved to a different location, specify the custom path using the --conf option.

   /opt/protegrity/upgrader/bin/sdkupgrd upgrade --conf /opt/sdkupgrd.conf
   

2. Run the upgrade in silent mode using the following command. Provide the ESA credentials with the command.

   /opt/protegrity/upgrader/bin/sdkupgrd upgrade --esa-user <esa_username> --esa-password <esa_user_password>
   

   Important: Do not set the path of the extracted .tgz build file manually. The Upgrade Agent expects the raw .tgz file and handles extraction internally.

   Do not extract the build manually. The Upgrade Agent validates the /signatures/ directory inside the .tgz bundle. If the /signatures/ directory is properly extracted, only then does the upgrade proceed.

For online and offline upgrade, these steps ensure that a smooth, zero‑downtime upgrade of AP Java protectors.

To confirm a successful online and offline upgrade -

• Review the Upgrade Agent logs in Insight for a success message indicating that the operation completed.
• Check the audit logs to verify that protection operations are being performed using the new AP Java version.
• Use Insight to review protector and audit logs.
• Confirm that logs reflect the new protector version after upgrade.

The application continues to serve protect and unprotect requests without interruption during the upgrade. In‑flight requests complete on the existing SDK version, while new requests are handled by the upgraded version after the reload. No requests are dropped, blocked, or fail during upgrade.

4.2 - Online and Offline Rollback

This section describes the complete procedure to perform an online and offline rollback operation for the Protegrity Application Protector Java components. It is assumed that the protector is already in the upgraded state.

Specifying Custom Configuration File Location

To perform an online rollback, the offline parameter in the sdkupgrd.conf file must be set to no.
To perform an offline rollback, the offline parameter in the sdkupgrd.conf file must be set to yes.

For rollback, the Upgrade Agent reads stdout, offline, and debug parameters from the sdkupgrd.conf file.

To perform online and offline rollback operation:

Run the following command to start the rollback.

/opt/protegrity/upgrader/bin/sdkupgrd rollback

Note: If the configuration file is moved to a different location, specify the custom path using the --conf option.

/opt/protegrity/upgrader/bin/sdkupgrd rollback --conf /opt/sdkupgrd.conf

For online and offline rollback, these steps ensure a smooth, zero‑downtime rollback of AP Java protectors. It safely restores the system to the previously backed-up protector version, ensuring continuity if an upgrade fails or needs to be aborted.

To confirm a successful rollback -

• Ensure that the protector version has reverted.
• Review the Upgrade Agent logs in Insight for a success message indicating that the operation completed.
• Verify that the running AP Java processes report the expected older version after rollback.
• Use Insight to review protector and audit logs.
• Confirm that logs reflect the rolled‑back version after rollback.