Troubleshooting

This section lists the general configuration steps and the common errors that occur during installation or upgrade.

Resolving the ORA-06520 Error

The following error indicate a missing symlink or an external library:

ORA-06520: PL/SQL: Error loading external library  
ORA-06512: at "<user_name>.PTY", line 1022  
ORA-06512: at "<user_name>.PTY", line 2633  
[ERROR] Failed to test UDFs installation  
[ERROR] sqlplus exit code: 1  
[ERROR] Installation failed. Rolling back changes...

Note: This error typically occurs in Oracle versions 21 and earlier.

To address runtime/configuration issues, perform the following steps:

Ensure libclntsh.so.<version> symlinks to libclntsh.so in the Oracle library directory.
Run ln -s libclntsh.so libclntsh.so.23.1.

Configuring the Environment Variables

The Oracle DB Protector can be installed by the sudoer user and Oracle admin user. This section discusses the installation using the sudoer user. Wherever possible, the Oracle commands for the Oracle admin user would be provided as well. To use the Oracle DB Protector, configure environment variables as per the Oracle version being used.

Resolving the ORA-20113 Error

In case of the ORA-20113: Failed to Load configuration error message, ensure to grant 755 permissions to the following directories:

/etc/protegrity/
<installaiton_directory>

Resolving the ORA-28575 Error

In the Oracle Database Protector on the AIX platform, if the external procedure fails with the ORA-28575: unable to open RPC connection to external procedure agent error message, then create a soft link for the extproc binary.

To create the soft link for the extproc binary:

Log in to the Oracle Database server.
To navigate to the directory that contains the binaries, run the following command:
```
cd $ORACLE_HOME/rdbms/lib
```
To create the soft link, run the following command:
```
make -f ins_rdbms.mk iextproc
```

Configuring the extproc.ora Environment Variable

The extproc.ora file is available in the $ORACLE_HOME directory.

To identify the location of the extproc.ora file, run the following command:
```
find . -name extproc.ora 2>/dev/null
```
To use the Protegrity UDFs, add the following environment variable in the extproc.ora file:
```
SET EXTPROC_DLLS=ANY
```

Recovering a Failed Upgrade

There can be scenarios where an automatic rollback of the Oracle Database Protector UDF solution may complete with errors. This results in the system being in a potentially inconsistent state. In such instances, the installer retains the backup directories of the previously working installation. The system can be manually restored to the previous working installation.

Important:
Execute the steps using the appropriate system user.
Ensure the availability of appropriate operating system level and Oracle database privileges.
Execute the steps in the specified order.
Commands assume a Linux/Unix environment.
Use extreme caution when running rsync commands with the --delete option.

When a rollback operation fails, the installer retains the following backup directories (example with timestamp):

<path_to_previous_installation_dir>/logforwarder_<timestamp>
<path_to_previous_installation_dir>/rpagent_<timestamp>
<path_to_previous_installation_dir>/databaseprotector_<timestamp>
/etc/protegrity_<timestamp>

When a component is installed, it is placed under a component-specific subdirectory under the user-provided installation directory:

Logforwarder → <installation_dir>/logforwarder
RPAgent → <installation_dir>/rpagent
Database Protector → <installation_dir>/databaseprotector

The backup directories contain the contents of these component directories and must be restored into their corresponding target directories.

/etc/protegrity

Verifying the Log Forwarder Status

To verify the status of the Log Forwarder, run the following command:
```
<installation_dir>/logforwarder/bin/logforwarderctrl status
```
Press ENTER. The script returns the status of the Log Forwarder.

To stop the Log Forwarder, run the following command:

<installation_dir>/logforwarder/bin/logforwarderctrl stop

Press ENTER. The command stops the Log Forwarder.
To check for any running instances of the Log Forwarder, run the following command:
```
ps -ef | grep logforwarder
```
Note: This command is useful in scenarios where installation is corrupt and the control command fails to return a valid status.
Press ENTER. The command lists all the running instances of the Log Forwarder along with the respective process ID.
To stop the specific instance of the Log Forwarder, run the following command:
```
kill -9 <logforwarder_process_id>
```
Press ENTER. The command will stop the specific instance of the Log Forwarder.

Verifying the RPAgent Status

To verify the status of the RPAgent, run the following command:
```
<installation_dir>/rpagent/bin/rpagentctrl status
```
Press ENTER. The script returns the status of the RPAgent.

To stop the RPAgent, run the following command:

<installation_dir>/rpagent/bin/rpagentctrl stop

Press ENTER. The command stops the RPAgent.
To check for any running instances of the RPAgent, run the following command:
```
ps -ef | grep rpagent
```
Note: This command is useful in scenarios where installation is corrupt and the control command fails to return a valid status.
Press ENTER. The command lists all the running instances of the RPAgent along with the respective process ID.
To stop the specific instance of the RPAgent, run the following command:
```
kill -9 <rpagent_process_id>
```
Press ENTER. The command will stop the specific instance of the RPAgent.

Restoring the Component Directories and User Configuration

Restore the contents of all the Protegrity components and configuration directories using the retained backups.

For each component:

Identify the installation directory.
Replace its contents with the corresponding backup directory using a suitable tool such as rsync, cp, or mv.

Note: The Logforwarder, RPAgent, and Database Protector components may be installed in the same directory or in separate directories, depending on the environment.

Important:
Ensure all services are stopped before performing this step.
Do not merge directories manually.
Always fully replace the target directory contents with the backup contents.

Restoring the Log Forwarder

To navigate to the backup directory, run the following command:
```
<path_to_previous_installation_dir>/logforwarder_<timestamp>
```
To navigate to the installation directory, run the following command:
```
<installation_dir>/logforwarder
```
To restore the Log Forwarder, run the following command:
```
rsync -a --delete <path_to_previous_installation_dir>/logforwarder_<timestamp>/ <installation_dir>/logforwarder/
```
Warning rsync --delete option permanently removes files from the target directory that are not present in the backup. Always verify that the target directory is the correct component directory before executing the command.

Restoring the RPAgent

To navigate to the backup directory, run the following command:
```
<path_to_previous_installation_dir>/rpagent_<timestamp>
```
To navigate to the installation directory, run the following command:
```
<installation_dir>/rpagent
```
To restore the RPAgent, run the following command:
```
rsync -a --delete <path_to_previous_installation_dir>/rpagent_<timestamp>/ <installation_dir>/rpagent/
```
Warning rsync --delete option permanently removes files from the target directory that are not present in the backup. Always verify that the target directory is the correct component directory before executing the command.

Restoring the Database Protector

To navigate to the backup directory, run the following command:

<path_to_previous_installation_dir>/databaseprotector_<timestamp>

To navigate to the installation directory, run the following command:
```
<installation_dir>/databaseprotector
```
To restore the Database Protector, run the following command:
```
rsync -a --delete <path_to_previous_installation_dir>/databaseprotector_<timestamp>/ <installation_dir>/databaseprotector/
```
Warning rsync --delete option permanently removes files from the target directory that are not present in the backup. Always verify that the target directory is the correct component directory before executing the command.

Restoring the User Configuration

To navigate to the backup directory, run the following command:
```
/etc/protegrity
```
To restore the user configuration, run the following command:
```
rsync -a --delete /etc/protegrity_<timestamp>/ /etc/protegrity/
```
Note: The /etc/protegrity/ directory location does not change across installations or upgrades. This step ensures that all previous configuration settings are fully restored.

Starting the Services

To start the Log Forwarder, run the following command:

<installation_dir>/logforwarder/bin/logforwarderctrl start

To start the RPAgent, run the following command:

<installation_dir>/rpagent/bin/rpagentctrl start

Restoring the Oracle Database Protector

Due to the failed rollback, the Oracle Database Protector types and UDFs may be in an invalid or inconsistent state. If database functionality is not correct, re-create the database objects.

To navigate to the directory containing the scripts, run the following command:
```
cd <installation_dir>/databaseprotector/oracle/sqlscripts
```
To drop the existing objects, run the following command, with an Oracle database user that owns the existing types and UDFs, or has sufficient privileges to drop them:
```
sqlplus <user_name>/<password> @dropobjects.sql
```
Important:
- During upgrades, different database users may have been used to create the UDFs.
- If rollback failed part-way, ownership of existing database objects may be unclear.
- Use the database user that owns the existing objects or has sufficient privileges.
- Errors such as “object does not exist” may occur and can be safely ignored depending on the database state.
To re-create the objects, run the following command, with a database user with the required permissions to create Oracle Database Protector types and UDFs:
```
sqlplus <user_name>/<password>@dcreateobjects.sql
```

Note: If issues persist after manual recovery, contact Protegrity Support and provide the installer log and details of the recovery steps performed.

Recovering a Partially Failed Installation

The Oracle Database Protector installation and upgrade processes involves creating and dropping a large number of Oracle database types and UDFs. In some scenarios, the SQL scripts may partially fail, resulting in an inconsistent database state.

The common scenarios include:

Fresh installation scenario where creation of some types or UDF fails.
Upgrade process where some new objects are created before a failure occurs.
Rollback process where the dropobjects.sql script encounters objects that were never created or were already dropped.

In such scenarios, the rollback process may log warnings similar to:

[WARN] IMPORTANT: One or more errors occurred while dropping new or restoring existing types and UDFs during rollback.
[WARN] This may indicate that some SQL script partially failed before and/or during the rollback.
[WARN] For example, you may see errors such as 'already exists' or 'not found'.
[WARN] Please review the current state of the database objects to ensure they match the expected configuration.
[WARN] Manual intervention may be required to fully restore the previous state.

These warnings are informational and do not automatically require action. However, a manual intervention is only required if the following instances are true:

The installer or rollback logs report SQL-related warnings or errors and
The current state of Oracle Database Protector types and UDFs is incorrect or inconsistent.

These errors occur because:

SQL scripts may fail partially because of permission issues, transient database errors, or environmental errors.
During rollback, the dropobjects.sql script attempts to drop all known objects.
Objects that were never created or were already removed, will generate errors such as:
- object does not exist
- already exists

Such errors are expected in partial-failure scenarios and do not necessarily indicate a fatal problem.

Execute the following steps ONLY when verification indicates that database objects are missing, invalid, or corrupted.

Re-create Database Objects (Only If Required)

To navigate to the directory where the scripts are located, run the following command:
```
cd <installation_dir>/databaseprotector/oracle/sqlscripts
```
Press ENTER. The command navigates to the directory containing the scripts.
To drop the UDFs, run the following command as a database user that owns the existing types and UDFs or has sufficient privileges:
```
sqlplus <user_name>/<password>@dropobjects.sql
```
Where:
- <user_name> is the database user that owns the existing types and UDFs.
- The user must have all required permissions listed in the product documentation.
Note: Errors such as object does not exist are expected in partial-failure scenarios and can be safely ignored.
To create the new UDFs, run the following command as a database user having all the required permissions to create Oracle Database Protector types and UDFs:
```
sqlplus <user_name>/<password> @createobjects.sql
```
Where:
- <user_name> is the database user that owns the existing types and UDFs.
- The user must have all required permissions listed in the product documentation.
Press ENTER. The script recreates the Oracle Database Protector types and UDFs. The database objects are restored to a clean and consistent state. The installation or rollback process is fully recovered from the SQL partial-failure scenario.
Note: If errors persist after re-creating the objects, review the SQL output and contact Protegrity Support with the installer and rollback logs.

Feedback

Was this page helpful?

Last modified : January 05, 2026