This topic outlines the prerequisites for linking an EBS R12.1 instance to the Delphix Engine.


Ensure your EBS R12.1 instance is supported

See Source EBS R12.1 Instance Requirements to ensure you can link your EBS R12.1 instance to the Delphix Engine.

Ensure your EBS 12.1 environments comply with Oracle's documentation

Your environments must comply with Oracle's requirements for installing EBS. These requirements are outlined on Oracle E-Business Suite Release 12 Installation Guidelines (Doc ID 405565.1) found at http://docs.oracle.com.

Prepare the dbTier for linking

Delphix Engine's Unix Environment Requirements

The dbTier must meet the source requirements outlined in Requirements for Unix Environments. These requirements are generic to all source Unix environments added to the Delphix Engine.

Delphix Engine's Oracle Database Requirements

The dbTier must meet the source requirements outlined in Oracle Support and Requirements. These requirements are generic to all Unix environments containing an Oracle database to be linked.

oracle OS user account

The Delphix Engine must have access to the OS account which "owns" the Oracle RDBMS installation on the EBS dbTier (a.k.a. "oracle")...

  • This user should be a member of both the EBS dba and oinstall groups
  • If the source database uses Oracle ASM, then this OS user account should be a member of either the asmadmin or the asmdba OS groups
  • The user should have read permissions on all dbTechStack and all database files that will be cloned.

dbTechStack Executable Permissions

Often, the following Oracle executable files are owned by "root" and accessible only by "root", which would cause a problem for Delphix when attempting to copy these files to the Delphix engine for later provisioning...

  • $ORACLE_HOME/bin/nmb
  • $ORACLE_HOME/bin/nmhs
  • $ORACLE_HOME/bin/nmo

These executables are used by the Oracle Enterprise Manager agent to run jobs as another OS user, thus requiring "root" ownership and the SETUID bit.  To resolve the problem presented by these files being readable only by "root", either these files should be made readable by the "oinstall" OS group, or the Delphix engine must be instructed to exclude capturing these files.

To make these files readable by the "oinstall" OS group, someone with "root" permissions must run something similar to the following...

# chmod g+r $ORACLE_HOME/bin/nm*

Or to exclude these files from being captured by Delphix, use the Paths To Exclude fields to specify paths relative to the root path of the EBS dbTechStack dataset.  Typically, the ORACLE_HOME subdirectory is a subset of the root EBS dbTechStack dataset (i.e. "12.1.0.2.0") so the these executables will be something like "12.1.0.2.0/bin/nmb", etc.

Cleanup Before Provisioning Option

If you plan to utilize the Cleanup Before Provision option available during dbTechStack provisioning, the Delphix Engine requires the RDBMS ORACLE_HOME to be patched with Oracle Universal Installer (OUI) version 10.2 or above. You can read more about this provisioning option in Provisioning a Virtual EBS R12.1 Instance.

Note that provisioning is still possible without this option enabled, but you will need to manage the target dbTier's Oracle Inventory manually to ensure that conflicting entries do not cause provisions to fail.

Special Considerations for Upgraded 11gR2 Database

If the database for the EBS R12.1 instance has been upgraded to 11gR2 from previous versions, please follow the workaround procedures in Oracle Support document Doc ID 1333997.1 to update PERL5LIB variable in database context file if applicable. Failure to follow these workaround procedures may result in errors during the dbTier linking and provisioning process.

Prepare the appsTier for Linking

There are two ways to access the Oracle EBS appsTier for linking a Delphix dSource:

  1. the simple approach of logging in directly to the OS account which owns the Oracle EBS appsTier (a.k.a. "applmgr")
  2. the secure approach of logging in using a non-privileged OS account and running "applmgr" privileged commands using elevation

Using the simple approach

This method involves linking to the EBS appsTier host using the existing OS account typically named "applmgr" which owns the Oracle EBS appsTier.  No additional modification is necessary for this account, other than choosing to use SSH passworded authentication or SSH public-key authentication from the Delphix virtualization engine.

Using the secure approach

This method involves linking to the EBS appsTier host using a new non-privileged OS account, typically named "delphix_os".  This account by itself does not have any special privileges, but it expects to use a privilege elevation mechanisms (default is "sudo") to run privileged commands as the OS account which owns the Oracle EBS appsTier, typically named "applmgr".

Delphix Engine's Unix Environment Requirements

The appsTier must meet the source requirements outlined in Requirements for Unix Environments. These requirements are generic to all source Unix environments added to the Delphix Engine.

delphix_os OS user account

In order to separate authentication and perform privileged operations with a non-privileged OS account, first create an OS user account (i.e. "delphix_os") on the EBS appsTier node to be used as a source.
This user is easily created by the createDelphixOSUser.sh script.

  • The primary OS group of the Delphix Engine software owner account's (i.e. delphix_os) should be the same as the EBS AppsTier software owner account (i.e. applmgr).
  • Primary group = OSDBA Group (typically dba), secondary group = Oracle Install Group (typically oinstall). There are lots of cases where the OS group named dba fills this role, so be sure to check the group membership of the EBS AppsTier software owner account.
  • Please note, the non-privileged OS account must have the same group as assigned to EBS AppsTier privileged account (like applmgr).

Host Requirements:

To accomplish necessary tasks on the EBS appsTier source hosts, the Delphix OS user account (henceforth referred to as "delphix_os") requires privilege elevation specifications.

Here is an example specification for the "sudo" privilege elevation utility, using the "visudo" to edit the "sudoers" configuration file.  This specification makes the following assumptions:

  • OS = Linux
  • OS account owning Oracle EBS appsTier is named "applmgr"
  • root EBS appsTier dataset path provisioned by Delphix is "/u01/oracle/APPS"


Defaults:delphix_os !requiretty

delphix_os ALL =  NOPASSWD: /bin/su - applvis -c ps *, /bin/su - applvis -c /bin/mount, /bin/su - applvis -c /bin/umount, /bin/su - applvis -c mkdir /u01/oracle/VIS/*, /bin/su - applvis -c *mkdir -p *, /bin/su - applvis -c rmdir /u01/oracle/VIS/*, /bin/su - applvis -c export *, /bin/su - applvis -c cd *, /bin/su - applvis -c echo *, /bin/su - applvis -c perl */adpreclone.pl *, /bin/su - applvis -c */*.env; sqlplus apps/* <<< exit;, /bin/su - applvis -c */rsync*, /bin/su - applvis -c */EBS_kill/kill_script.sh*, /bin/su - applvis -c test*sudo chown root*oinstall */kill_script.sh* sudo mv */kill_script.sh */EBS_kill/* sudo chmod 750 */EBS_kill/kill_script.sh * sudo chown -R root*oinstall */EBS_kill/*, /bin/su - applvis -c test*, /bin/su - applvis -c rm */CREATE_KILL_SCRIPT_FILE*, /bin/mount, /bin/umount, /bin/ps


Requirement for Privilege Elevation Script: DLPX_DB_EXEC

In order to elevate privileges from a non-privileged OS account (like delphix_os) to a privileged OS account (like applmgr) we need to push a privilege elevation script (dlpx_db_exec) up into the Delphix virtualization engine to become part of the Delphix common plugin.

Why we need DLPX_DB_EXEC

Some customers do not allow us to execute sudo for security reasons and to work around this we now use our own privilege elevation script (dlpx_db_exec) so that we can enable Delphix to execute commands that require superuser privileges on customer source and target machines.

The privilege elevation script DLPX_DB_EXEC can be created or pushed to Delphix Engine using Web API calls, CURL or dxtoolkit.

For steps on creating a Privilege elevation Profile please refer to CLI Cookbook: How to Create or Edit a Privilege Elevation Profiles and Profile Scripts

Content of DLPX_DB_EXEC Privilege Elevation Profile:


#!/bin/sh
#
# Copyright (c) 2018 by Delphix. All rights reserved.
#
# This script allows customization of command execution with an alternate user
# account.
# Arg $1 contains "-u<optional user account>" for the desired user under
# which database commands will be executed.
# By default this argument is ignored and the script is executed as the default
# account.
#
if [[ $1 != -u* ]]; then
   echo "Incorrect command line parameters, -u<optional user account> is required as the first parameter"
   exit 1
fi
user_id=`echo $1 | sed -e "s/^-u//"`
shift 1
if [[ $user_id != "delphix_os" ]]; then
    command=$(printf "%s " "$@")
    sudo su - $user_id -c "$command"
else
    $@
fi

Below is an example of how we can push privilege elevation script “dlpx_db_exec” on a customer Delphix Engine:

  • Create a session to Delphix Engine as delphix os User:

$ curl -s -X POST -k --data @- http://delphix-server/resources/json/delphix/session \
   -c ~/cookies.txt -H "Content-Type: application/json" <<EOF
{
   "type": "APISession",
   "version": {
       "type": "APIVersion",
       "major": 1,
       "minor": 4,
       "micro": 3
   }
}
EOF
{
   "status":"OK",
   "result": {
       "type":"APISession",
       "version": {
           "type": "APIVersion",
           "major": 1,
           "minor": 4,
           "micro": 3
       },
       "locale": "en_US",
       "client": null
   },
   "job": null
}


Note:
The API Version needs to be identified as per the Delphix Engine installed at the customer site.

  • Login to Delphix Engine as delphix OS User:

curl -i -c cookies.txt -b cookies.txt -X POST -H "Content-Type:application/json" <Delphix-Engine>/resources/json/delphix/login -d '{"password":"delphix","type":"LoginRequest","target":"DOMAIN","username":"delphix_admin"}'
  • Push DLPX_DB_EXEC contents to Delphix Engine:

curl -i -b cookies.txt -X POST -H "Content-Type:application/json" <Delphix-Engine>/resources/json/delphix/host/privilegeElevation/profileScript/HOST_PRIVILEGE_ELEVATION_PROFILE_SCRIPT-7 -d '{"type": "HostPrivilegeElevationProfileScript","contents": "#\n# Copyright (c) 2018 by Delphix. All rights reserved.\n#\n\n#\n# This script allows customization of command execution with an alternate user\n# account.\nif [[ $1 != -u* ]]; then\n    echo \"Incorrect command line parameters, -u<optional user account> is required as the first parameter\"\n exit 1\nfi\nuser_id=`echo $1 | sed -e \"s\/^-u\/\/\"`\n\nshift 1\nif [[ $user_id != \"delphix_os\" ]]; then\ncommand=$(printf \"%s \" \"$@\")\nsudo su - $user_id -c \"$command\"\nelse\n$@\nfi\n"}'

Clean Up Before Provisioning Option

If you plan to utilize the Cleanup Before Provision option available during appsTier provisioning, the Delphix Engine requires the Web Oracle Home to be patched with Oracle Universal Installer (OUI) version 10.2 or above. You can read more about this provisioning option in Provisioning a Virtual EBS R12.1 Instance.

Note that provisioning is still possible without this option enabled, but you will need to manage the target appTier's Oracle Inventory manually to ensure that conflicting entries do not cause provisions to fail.

Related Links