SharePlex 10.1.1 - Installation and Setup for Oracle on RDS

About this Guide

This manual provides instructions for installing and setting up SharePlex on an Amazon RDS Oracle database.

Other SharePlex documentation

For the complete SharePlex documentation set, go to https://support.quest.com/shareplex/technical-documents.

View this document in PDF format

You can download, view and save this document in Adobe PDF format. Click Download in the upper right-hand corner of this page. This action downloads the entire publication.

Overview and Requirements

The deployment of SharePlex for an Oracle database hosted on the Amazon RDS service is slightly different from deploying SharePlex for an on-premises Oracle database. In a typical on-premises database environment, a SharePlex administrator can install and set up SharePlex directly on the production database system. However, in an RDS environment, SharePlex cannot be installed on the underlying operating system, which is fully managed by Amazon.

To replicate to or from an Oracle database on RDS, you install SharePlex on a server that is external to the RDS deployment of the Oracle database, and then configure SharePlex to interact with the RDS database through a remote connection. Once SharePlex is deployed, it operates the same way as it does when capturing from, or posting to, an on premises source and target.

Requirements and support

Understand the following when using SharePlex in an RDS environment.

SharePlex AMI

In all but one of the supported configurations for replication to or from an RDS database, you need to obtain a SharePlex AMI (Amazon Virtual Machine Instance). This instance is an Amazon Linux virtual machine, hosted on Amazon EC2, with SharePlex pre-installed. An Oracle client is included in the image. You launch the SharePlex instance from your EC2 account and then perform a few tasks to set up licensing and connectivity to the database.

Configure a SharePlex AMI instance

These instructions help you to create your SharePlex instance.

Prerequisites

• Create an Amazon Web Services (AWS) account and (recommended by Amazon) an Identity and Access Management User, or obtain the AWS credentials of an existing account that will be used for SharePlex.
• Have your SharePlex license key available.
• Each SharePlex AMI requires an incoming SSH rule that opens port 22 for incoming connections by users who will issue SharePlex commands or perform other replication-related administrative tasks. The One-Click Launch method provides a predefined security group with an existing incoming SSH rule that you can link to one or more IP addresses, or you can select a different security group. The Manual Launch method enables you to create a custom security group, or you can select an existing group. To create a custom security group before you start the launch, see the Amazon AWS documentation.

• SSH access to your SharePlex instance is allowed only by public key authentication using a key pair. The public key of the key pair is embedded in your SharePlex instance, and a private key is stored by you (the SharePlex user) in a file on the computer from which you will connect to SharePlex. You specify the file in the connection string. The One-Click Launch method requires you to select an existing key pair. The Manual Launch method enables you to create a key pair or select an existing one. To create a key pair, see the Amazon AWS documentation.

Create the SharePlex AMI instance

To find SharePlex on Amazon AWS

1. Log on to Amazon Marketplace with your AWS account credentials.
2. In the Search box, type SharePlex.
3. Click the SharePlex for Database Replication link that is returned by the search. The SharePlex page is displayed, where you can compare costs based on various infrastructure options.
4. Click Continue to Subscribe at the top of the page.

5. You have the option of creating a SharePlex instance in either of the following ways:

   • One-click launch: Launches a default SharePlex instance, with limited customization options. The instance launches with a default name, which you can change after the launch process is completed.
   • Manual Launch: Provides additional customization options for your SharePlex instance, including the ability to specify a name and create a key pair or security group.

To create a SharePlex AMI instance with one click

1. Select One-Click.

2. Specify the following settings. See the Amazon RDS help if you need more information about these features.

   Version: Select the SharePlex version that you want to run.

   Region: Select the Amazon region that will host the SharePlex instance.

   EC2 Instance Type: Select the virtual machine attributes for the SharePlex instance.

   VPC Settings: Select or create a virtual private cloud network and subnet for your SharePlex instance.

   Security Group: Select an existing security group, or select Create new based on seller settings to customize the existing SSH rule to your own IP addresses. Note: Any Amazon-generated default security groups shown in the list do not provide enough security for production replication across external networks.

   Key Pair: Select a key pair, which will be used as authentication when you log on to the SharePlex instance. Note: To log into SharePlex with th selected key pair, you must be in possession of the .pem file that contains the private key of that key pair.

3. Click Launch with One Click. You are notified that your instance of the software is being deployed on EC2. You can view the status of this instance on the EC2 console and assign it a name if desired.

To create a SharePlex AMI instance manually

1. Select Manual Launch.
2. Click Launch.
3. Under Version, select the SharePlex version that you want to run.
4. Under Launch, find the Amazon region that will host the SharePlex instance, then click Launch with EC2 Console.
5. Select an instance type that matches your processing and storage needs, then click Next: Configure Instance Details.

6. Select among options that are related to the operation of the SharePlex instance.

7. Click Next: Add Storage.
8. Keep the default storage settings (these are adequate in most cases) or make any changes as necessary.
9. Click Next: Add Tags.

10. Click Add Tag then provide the following:

    • Key column: Enter your user name or some other value on which you can search and sort to find this SharePlex instance. Example: MyUserName
    • Value column: Enter the SharePlex instance name. Example: MySharePlexInstance

11. Click Next: Configure Security Group.

12. Select or create a security group that satisfies the SharePlex requirements. To create a rule, see the Prerequisites in these instructions.

13. Click Next: Review and Launch.
14. Review your instance specifications, and make any changes if needed.

15. Click Launch. The key pair dialog is displayed. Specify how you want to associate a key pair with the SharePlex instance:

    • If a key pair exists already, select Choose an existing key pair, then select the name.
    • To specify a new key pair, select Create a new key pair, type a name for the key pair file, then click Download Key Pair. The private key is downloaded to your computer in the form of a file with the extension of .pem (typically the Downloads folder on Windows).
16. Change the permissions on the.pem file to read-only. This is an Amazon requirement. Store the file in a safe place where you have access to it later
17. Click Launch Instance.
18. Click View Instance, then wait for the instance initialization to be completed.

19. Select the SharePlex instance by its assigned name tag, then wait until the Status Checks column shows a Checks Passed status.

Log in to the SharePlex instance

1. If you do not have an SSH client on your system, download and install one.
2. Run the SSH client.

3. Always log on to the SharePlex AMI instance as the ec2-user. This user is the SharePlex Administrator. Use the following command:

   ssh -i ~/.ssh/pem_file_name.pem ec2-user@IP_address/hostname

   where:

   • pem_file_name is the name of the .pem file that you downloaded, which contains the private key of the security key pair.
   • IP_address/hostname is either the IPv4 public IP address or, if present, the host name that is mapped to this IP address in your domain name server or /etc/hosts file.

Add a license key to the SharePlex instance

1. Log on to the SharePlex instance.

2. Run the SharePlex license key utility with the following command at the Linux command prompt:

   /home/ec2-user/shareplex/proddir/install/splex_add_key

3. Choose option 2:

   SharePlex License Utility
   1) Read license key from file
   2) Enter license key manually
   3) Add license key for alternate host
   q) Quit License Utility
   Enter option:

4. Type the license key exactly as you received it from Quest, including the SPLEXKEY= string if one prepends the key, any spaces, and any capitalization. Press Enter when finished typing the key.

5. Enter the SiteMessage text string provided by Quest with the license key.

6. Enter q to exit the utility.

Setup for on-premises source, RDS target

SharePlex supports the following SharePlex configurations when the source database is on-premises and the target is an RDS database.

• SharePlex installed on-premises
• SharePlex AMI instance on EC2 cloud

SharePlex installed on-premises

In this scenario, Capture, running on premises, connects to the source database through a bequeath connection and the Post process connects to the RDS database through TNS.

To set up this configuration, install SharePlex on-premises in one of these ways:

• You can use your production source server to run all of the SharePlex replication components. In this setup, both source and target replication processes (and their queues) are installed on one server, the production server.

  Note: In a high-volume transactional environment, the buildup of data in the post queues and the presence of multiple Post processes may generate unacceptable overhead for a production system. In that case, you should use an intermediary server.

• You can use an on-premises intermediary server to run the Import and Post components (and the post queues). This method removes most of the replication overhead from the source server. For more information, see Post to PaaS cloud from an intermediary server on page 1.

Note: To view SharePlex system requirements when installed on premises, see the SharePlex Release Notes.

Install SharePlex

Install SharePlex on the source (and on the intermediary server, if using one for the Post process).

1. Log in to the system as the user that will be named as the SharePlex Administrator during this installation. This user will own the installation files and binaries.

2. If sp_cop is running, shut it down.

   sp_ctrl> shutdown

3. Copy the installation file to a temporary directory where you have write permissions.

4. Grant executable permissions to the file.

   #chmod 555installation_file

5. Run the .tpm file. If installing SharePlex in a cluster, run the installer from the primary node (the one to which the shared disk is mounted)

   # ./installation_file

6. Verify that the information shown on the first screen corresponds to the Oracle version and platform you are upgrading.

7. You are prompted for the following:

   Note: These are basic installation instructions. For complete pre-installation and installation instructions for on-premises deployment, see the SharePlex Installation and Setup Guide for an Oracle Source.

   Prompt	Input
   Installation type	Select <New Installation>.
   Product directory location (path)	Enter the path to the SharePlex installation directory. If the specified directory does not exist, the installer creates it. If the directory exists, it must be empty.
   Variable data directory location	Specify an empty directory. The installer creates the specified directory if it does not exist. Important! Do not install this directory into the SharePlex product directory.
   SharePlex Admin group	Enter the DBA-privileged group to which the SharePlex Administrator user belongs, which will own the SharePlex binaries. If the default group of the SharePlex Administrator is oinstall, select any option, and make certain this user is listed under oinstall in the etc/group file.
   TCP/IP port for SharePlex	Enter the port number to use for SharePlex TCP/IP communications. The default is 2100.
   License key (do you have?)	Press Enter to accept the default of Y (yes). If you do not have a license, enter N (no).
   License key	Enter the license key you received from Quest.
   Customer name	Enter the SiteMessage text string provided by Quest with the license key.

Create the tnsnames.ora file

1. On the source or the intermediary system (if using one) create a tnsnames.ora file with connection information for the target RDS database.

   Important! The TNS alias cannot contain any dashes (-).

   The following is an example:

   target =
     (DESCRIPTION =
       (ADDRESS = (PROTOCOL = TCP)(HOST = yourtarget.amazonaws.com) (PORT = 1521))
       (CONNECT_DATA =
         (SERVICE_NAME=orcl)
       )
     )

Run Oracle Setup

1. On the source, run ora_setup for the source database. See the directions for running Oracle Setup in Database Setup for Oracle.

   • Reply YES to "Will SharePlex install be using a BEQUEATH connection?"
   • Reply NO to "Are you setting up SharePlex for an RDS database?"
   • Reply YES to "Will the current setup for sid: SID be used as a source (including cases as source for failover or primary-primary setups)?"

2. On the source or intermediary (if using one) run ora_setup again, this time for the target database.

   • Reply NO to "Will SharePlex install be using a BEQUEATH connection?"
   • Reply YES to "Are you setting up SharePlex for an RDS database?" When you answer YES, it automatically configures Post to use a TNS connection and prompts for the RDS primary user, which has the required privileges to install SharePlex replication objects in the RDS database.
   • Reply NO to "Will the current setup for sid: SID be used as a source (including cases as source for failover or primary-primary setups)?"

Set up routing in the configuration file

When you create your configuration file, use the name of the local host (where SharePlex is installed) in the routing map so that Post runs locally. The following is an example:

SharePlex as an AMI instance on EC2 cloud

In this scenario, SharePlex runs as an Amazon Machine Image instance on the EC2 service. Capture connects to the source database through TNS and the Post process connects to the RDS database through TNS.

Obtain a SharePlex AMI image

To launch a SharePlex AMI instance, see Configure a SharePlex AMI instance.

Log on to the SharePlex AMI instance

Always log on to the SharePlex AMI instance as the ec2-user. This user is the SharePlex Administrator. Use the following command:

ssh -i ~/.ssh/pem_file_name.pem ec2-user@IP_address/hostname

where:

• pem_file_name is the name of the .pem file that you downloaded, which contains the private key of the security key pair.
• IP_address/hostname is either the IPv4 public IP address or, if present, the host name that is mapped to this IP address in your domain name server or /etc/hosts file.

Create a tnsnames.ora file

On the SharePlex AMI instance, create a tnsnames.ora file with entries for the source and target databases.

The following are examples:

source =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = yoursource.amazonaws.com) (PORT = 1521))
    (CONNECT_DATA =
      (SERVICE_NAME=orcl)
    )
  )
target  =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = yourtarget.amazonaws.com) (PORT = 1521))
    (CONNECT_DATA =
      (SERVICE_NAME=orcl)
    )
  )

Run ora_setup

1. On the SharePlex AMI instance, run ora_setup for the source database. See the directions for running Oracle Setup in Database Setup for Oracle.

   • Reply NO to "Will SharePlex install be using a BEQUEATH connection?"
   • Reply NO to "Are you setting up SharePlex for an RDS database?"
   • Reply YES to "Will the current setup for sid: SID be used as a source (including cases as source for failover or primary-primary setups)?"

2. On the SharePlex AMI instance, run ora_setup again for the target database.

   • Reply NO to "Will SharePlex install be using a BEQUEATH connection?"
   • Reply YES to "Are you setting up SharePlex for an RDS database?"
   • Reply NO to "Will the current setup for sid: SID be used as a source (including cases as source for failover or primary-primary setups)?"

Configure remote capture

1. On the SharePlex AMI instance, start sp_cop.
2. Start sp_ctrl.
3. Set the SP_OCT_OLOG_USE_OCI parameter to 1, which enables Capture to read the redo records through OCI, rather than directly from the redo files.

Note: Enabling the SP_OCT_OLOG_RDS_MINER parameter is deprecated and no longer supported for Oracle 19c.

Set up routing in the configuration file

When you create the SharePlex configuration file, use the name of the EC2 host of the SharePlex AMI instance in the routing map so that Post runs on that host. The following is an example: