Create an Oracle Data Safe On-Premises Connector

Prerequisites for Creating an Oracle Data Safe On-Premises Connector

Prior to creating an Oracle Data Safe on-premises connector, be sure to complete the following prerequisite tasks:

Obtain permission for creating an Oracle Data Safe on-premises connector. See the section called Target Registration Resources in OCI Resources for Oracle Data Safe.
Ensure that the host(s) on which you plan to install the Oracle Data Safe on-premises connector meets the hardware and software requirements.

Hardware Requirements

Oracle recommends that you install the on-premises connector on a host machine other than your Oracle database host machine. You can, however, install it on the database host machine if needed. In a production environment, Oracle recommends that you install the same on-premises connector on two Linux hosts for high availability. If one of your hosts goes down due to system failure or maintenance, Oracle Data Safe connections automatically fail over to the on-premises connector running on the other host, and the on-going Oracle Data Safe operations are not affected.

Be sure that the host machine on which you are going to install the on-premises connector meets the following hardware requirements:

Minimum CPU: 2
Minimum RAM: 16GB
Minimum local disk storage:
- 5GB, where the on-premises connection software plus log space takes 100 MB
- /tmp space: 100 MB
Network interface bandwidth: 1Gbps
Network connectivity:
- Outbound connectivity to Oracle Data Safe (accesspoint.datasafe.<region>.oci.oraclecloud.com:443). Replace <region> with your region; for example, accesspoint.datasafe.us-ashburn-1.oci.oraclecloud.com.
- Local connectivity to target database listener hosts/ports

Software Requirements

Be sure that the host machine on which you are going to install the on-premises connector meets the following software requirements:

Operating system:
- Oracle Linux 7 or higher (Linux x86-64) or
- Red Hat Enterprise Linux (RHEL) 8
Python 3.5 or higher - If you have multiple versions of Python installed, make sure that you set the default to Python 3.5 or higher, or explicitly provide the Python path when running the commands.
Java version 7 or higher with a valid Java Home (JAVA_HOME)

Note:

For instructions on how to uninstall, update, stop, and show the status, please refer to the README file that comes with the install bundle.

Create an Oracle Data Safe On-Premises Connector

Sign in to the Oracle Cloud Infrastructure Console and select the appropriate region in your tenancy.
From the navigation menu, select Oracle Database, and then Data Safe - Database Security.
On the left under Data Safe, click Target Databases.
On the left under Connectivity Options, click On-Premises Connectors.
On the right, click Create On-Premises Connector.
The Create On-Premises Connector panel is displayed.
From the drop-down list, select the compartment in which you want to store the on-premises connector.
Enter a name for the on-premises connector.
(Optional) Enter a description for the on-premises connector.
(Optional) To configure tagging, click Show Tagging Options, and then configure a tag.
Click Create On-Premises Connector.
The on-premises connector is created and listed in the table. The initial life-cycle state of the on-premises connector is set to INACTIVE.

Download the Install Bundle for the Oracle Data Safe On-Premises Connector

You can download the install bundle for the on-premises connector from the Connector Detail page in the Oracle Data Safe service.

Access the Overview page for Oracle Data Safe.
On the left under Data Safe, click Target Databases.
Under Connectivity Options on the left, click On-Premises Connectors.
Click the on-premises connector that you created.
Click Download Install Bundle.
The Download Install Bundle dialog box is displayed.
Enter a password for the install bundle, confirm it, and then click Download.
Keep this password on hand as you need it later when you install the on-premises connector on a host on your network.

The install bundle is downloaded to your browser's default download location.
Copy the install bundle ZIP file to a host machine on your network.
Unzip the file and confirm that you have the following files:
- README - Readme file with installation instructions
- connector.conf - Connection Manager configuration file
- downloads/orapki.zip - ZIP file containing an orapki script and required JAR files
- downloads/cman.zip - ZIP file containing Connection Manager binaries
- downloads/cmanora.template - Connection Manager configuration template
- util/datasafe_privileges.sql - Oracle Data Safe privileges SQL script. You can also download this script from the Oracle Data Safe service in Oracle Cloud Infrastructure.
- wallet/ewallet.p12 - P12 wallet
- setup.py - Python setup script to install the on-premises connector

Install an Oracle Data Safe On-Premises Connector

The Connection Manager, as part of your on-premises connector installation, establishes a TLS tunnel to a cloud Connection Manager. You can control outgoing traffic from your host machine to the IP address of the cloud Connection Manager, which listens on port 443. The address of a cloud Connection Manager is accesspoint.datasafe.REGIONNAME.oci.oraclecloud.com. For example, for the Ashburn region, the address isaccesspoint.datasafe.us-ashburn-1.oci.oraclecloud.com. You can obtain the IP address of the cloud Connection Manager by doing a DNS lookup.

The following items are also installed. For more information about these items, see the Database Administrator's Guide.

Listener control utility (lsnrctl)
Connection testing utility (tnsping)

Open a command prompt on a host machine where you want to install the on-premises connector.
As a user different from the root user, enter the following command to install the on-premises connector.
Do not run the installer as the root user.

Provide a port number for the on-premises connector. The https-proxy argument is optional. You can skip the https-proxy argument if the deploying host has public internet access. The on-premises connector does not support a proxy username and password.
The HTTP proxy may not be enough depending on your organization's network configuration and security policies. For example, some networks require a username and password for the HTTP proxy. In such cases contact your network administrator to open outbound connections to hosts in the accesspoint.oraclecloud.com domain using port 443 without going through an HTTP proxy.

The create-osservice argument is optional as well. By setting this to Yes you will designate the on-premises connector as an operating system service. This designation will ensure that the on-premises connector gets automatically restarted whenever the OS of the host machine is rebooted. If this argument is not included or set to no, the on-premises connector will have to be manually restarted whenever the OS of the host machine is rebooted.

The install script automatically starts the on-premises connector.
```
$ python setup.py install --connector-port=<port> [--https-proxy=<proxy:port> --create-osservice=<Yes or No>]
```
Examples:
```
$ python setup.py install --connector-port=1560
$ python setup.py install --connector-port=1560 --https-proxy=https://www-proxy.domain.com:80 --create-osservice=Yes 
```
At the prompt, enter the password that you created when you downloaded the install bundle.
The on-premises connector is installed in the current directory and automatically started. The status for the on-premises connector in the Oracle Data Safe service in Oracle Cloud Infrastructure is now set to ACTIVE.
(Optional) To diagnose installation issues or execute additional commands (such as uninstall, update, start, stop, and status), please refer to the README file that comes with the install bundle.

High Availability of an On-Premises Connector

If you wish to increase the resilience of your on-premises connector and make it highly available, install another instance of the connector using the same install bundle you downloaded for the first installation on a different host or VM. Up to three instances of the same on-premises connector can be started or installed. Each connector will check in with Oracle Data Safe, and if one connector instance fails or is unreachable, Data Safe will automatically try one of the remaining connectors. You may have up to three copies of the connector running simultaneously.

Related Topics

Install an Oracle Data Safe On-Premises Connector

Check the Status of an On-Premises Connector

To check the status of an on-premises connector, enter the following command:

python setup.py status

Restart an On-Premises Connector

To restart an on-premises connector, run the following command:

python setup.py restart

Creating OS User Service for Existing On-Premises Connectors

By designating the on-premises connector as an operating system(OS) service, you can prevent the on-premises connector from requiring a manual restart after an OS reboot of the on-premises connector's host machine.

To designate an existing on-premises connector as an OS service, run the following command on the on-premises connector:

setup.py osservice --command=create

This command will ensure that the on-premises connector is restarted whenever the OS of the host machine is rebooted.

Update an Oracle Data Safe On-Premises Connector

You can update an Oracle Data Safe On-Premises Connector by downloading a new copy of the install bundle and then running the setup script to perform the update.

The download procedure for creating and updating on-premises connectors is the same and the bundle includes the same set of files. However, in the update procedure you must unzip the bundle files into the same directory where the connector is already installed, overwriting the existing files. Also, to perform an update pass the update argument to the setup.py script instead of the install argument.

Note:

During the update, the on-premises connector is not able to connect to target databases that may be using it. Connection is reestablished when the update is complete.

Download the install bundle to your local computer from the Connector Detail page in the Oracle Data Safe service.
See Download the Install Bundle for the Oracle Data Safe On-Premises Connector for the download instructions.
Upload the bundle to the host where you want to update the connector.
Unzip the bundle into the directory where the on-premises connector is installed. This overwrites the current files.
As a user other than root, run setup.py with the update argument.
```
$ python setup.py update
```
Enter the bundle password when prompted for it.
```
Enter bundle password:
```

You should see the following messages:

Data Safe on-premises connector update in progress...
Updating wallet...
Data Safe on-premises connector successfully updated

This completes the update of the on-premises connector.

If you encounter errors during the update, see Troubleshooting Install or Update Issues.

Uninstall an Oracle Data Safe On-Premises Connector

You can use the setup.py script to uninstall an Oracle Data Safe on-premises connector.

Log on to the host where the on-premises connector is installed.
Navigate to the directory where the on-premises connector is installed. Find the setup.py script.
As a user other than root, run setup.py with the uninstall argument.
```
$ python setup.py uninstall
```
At the prompt, confirm that you want to uninstall the connector:
```
This will remove the Data Safe on-premises connector, please confirm (Yes/No): yes

Data Safe on-premises connector successfully uninstalled
```

Find the Log Files for an On-Premises Connector

An on-premises connector's setup and manage logs can be found at:

<script_directory>/log/

An on-premises connector's runtime log can be found at:

<script_directory>/oracle_cman_home/log/diag/netcman/<hostName>/cust_cman/trace/cust_cman.log

Troubleshooting Install or Update Issues

Error message: Failed to create the tunnels to Data Safe connection manager - for more details check <log file name>
After installation or update, the Oracle Data Safe on-premises connector attempts to connect (or re-connect) to the Oracle Data Safe Connection Manager. This message may not indicate an actual error. It can appear if tunnel creation is slow. To confirm that the connector is working, run the show tunnels command. If one or more tunnels (connections) exist, then the on-premises connector can communicate with the Connection Manager and you can ignore this message.
```
$ ./oracle_cman_home/bin/cmctl show tunnels -c cust_cman
```
```
CMCTL for Linux: Version 20.0.0.0.0 - Production on 09-OCT-2021
    10:45:34 
Copyright (c) 1996, 2020, Oracle. All rights reserved. 
Current instance cust_cman is already started
Connecting to (address_list=(address=(protocol=TCPS)(host=localhost)(port=1520))) 
Number of connections: 12. 
The command completed successfully.
```
If an error occurs during an update (for example if show tunnels shows that no tunnels exist), try rerunning the update command. Run uninstall and then rerun install only if update fails again. This is because after running uninstall you may need to reimport the database certificates if TCPS configuration was part of the original installation.