Setting Up the Upgrade Agent

• 1: Upgrade Configurations
• 2: Rollback Behavior
• 3: Protegrity SDK Upgrade Permissions and Deployment
• 3.1: User Roles and Groups
• 3.2: Component Overview
• 3.3: Recommended File and Folder Permissions

pty_insight_analytics*troubleshooting_*

process.name: sdkupgrd

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.

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 - 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.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.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 - 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