13 Cloning Management Agent

The Management Agent you install using other installation types is always a fresh installation without any customized configuration that you had done or interim one-off patches that you had applied to other running Management Agents.

If you want to install an additional Management Agent that is identical to the existing well-tested, pre-patched, and running Management Agent, then the best option is to clone the existing instance. Yes, we literally mean making identical copies!

The "Management Agent Cloning" is an installation option that allows you to make copies of your existing running Management Agents so that the same configuration changes are carried over to the newly cloned Management Agent instance - either on a single host or multiple hosts. This saves time and effort in patching a fresh installation all over again and bringing it to the current state.

You can clone a Management Agent in two ways, either from the Grid Control console or from the command line.

Note:

Cross platform cloning and cloning on shared clusters is not supported. For example, you cannot clone a Linux-specific Management Agent from a Linux host to a Solaris host.

This chapter describes the following:

Cloning Management Agent Using Grid Control Console
Cloning Management Agent Using Command Line
Cloning Management Agent on a Cluster

Note:

The Agent Clone application is available only in Enterprise Manager 10g Grid Control Release 5 (10.2.0.5).

This installation guide is mainly for the base release, that is, Enterprise Manager 10g Grid Control Release 2 (10.2.0.1) Use this guide to install the base release and then patch it with 10.2.0.5 Grid Control patch set to migrate to Enterprise Manager 10g Grid Control Release 5 (10.2.0.5). The 10.2.0.5 Grid Control patch is available on My Oracle Support (formerly Metalink).

Cloning Management Agent Using Grid Control Console

This section describes the following:

Prerequisites for Cloning Management Agent
Cloning Management Agent

Note:

If the cloning operation fails, review the log files described in Appendix C, "Agent Log Files".

Prerequisites for Cloning Management Agent

Before you start to clone a Management Agent, meet the following prerequisites:

Table 13-1 Prerequisites for Cloning a Management Agent

Requirement	Description	Yes/No
Hardware and Software Requirements	Ensure that you meet the hardware and softwrae requirements. For hardware requirements, see Hardware Requirements. For software requirements, see Software Requirements.
Operating System Requirements	Check if that operating systemon which you are going to install the Management Agent is ceritified. For information about certified operating systems, see Operating System, Browser, Target Certification.
Package Requirements	Install the packages that are required for your operating system. For information about packages, see Appendix G, "Check Platform-Specific Package Requirements for Agent Installation".
Load Balancer Requirements	If you are cloning the Management Agent in an environment that has multiple OMSes managed by a Server Load Balancer (SLB), then ensure that you enable communication between the Management Agent and the host running the SLB. For information about configuration to be done for SLB, see Configurations Required for Management Agent to Communicate with Oracle Management Service with Server Load Balancer.
Operating System Group Requirements	Ensure that you are part of the same operating system group that installed Oracle Application Server and/or Oracle Collaboration Suite.
User and Operating System Group Requirement	Ensure that the target host where you want to install the Management Agent has the appropriate users and operating system groups created. For information about creating operating system groups and users, see Operating System Groups and Users Requirements.
Path Validation Requirements	Validate the path to all command locations. For more information, see Validate All Command Locations.
Permission Requirements	Ensure that you have read, write, and execute permissions to `oraInventory` on all remote hosts. If you do not have these permissions on the default inventory (typically at `/etc/oraInst.loc`) on any remote host, you can specify the path to an alternative inventory location by using the `-i <location>` option in the Additional Parameters section. For information about oraInventory permissions, see Installing Enterprise Manager Grid Control As the First Oracle Software.
Default Port Requirements	Ensure that the SSH daemon is running on the default port (that is, 22) on all the target hosts. If the port is a non-default port, that is, any port other than 22, then update the SSH_PORT property in the `paths.properties` file to ensure successful cloning of the Management Agent. If the software for Oracle Management Agent 10g Release 4 (10.2.0.4) or higher is available, then update the following file: `<OMS_HOME>/sysman/agent_download/<VERSION>/<PLATFORM>/agentdeploy/Paths.properties` If the software of the Management Agent is not available: `<OMS_HOME>/sysman/prov/resources/Paths.properties`
Oracle Inventory Location Requirements	Ensure that the Oracle Inventory (`oraInventory`) is not in a shared location. When you use the `oraInst.loc` file, ensure that the inventory location specified there is not pointing to a shared location. If it is, change it to a non-shared location.
PubkeyAuthentication Parameter Requirements	Ensure that the `PubkeyAuthentication` parameter is enabled in the sshd_config file. To verify the value of this parameter, run the following command: `grep PubkeyAuthentication /etc/ssh/sshd_config` The result of this command must be Yes. If the result is No, then edit the `/etc/ssh/sshd_config` file and set the PubkeyAuthentication value to Yes.
Installing User Requirements	If the central inventory owner and the user installing the Management Agent are different, then ensure that they are part of the same group. Also ensure that the inventory owner and the group to which the owner belongs have read and write permissions on the inventory directory. For example, if the inventory owner is abc and user installing the Management Agent is xyz, then ensure that abc and xyz belong to the same group, and they have read and write access to the inventory.
SUDO Requirements	Ensure that you have SUDO privileges to run `root.sh` and `/bin/sh`. To verify whether you have SUDO privileges to run these files, access the `/etc/sudoers` file and check whether you have a similar entry as shown below. If you do not see a similar entry, then add one. `<user> <hostname>=PASSWD: /home/em/agent10205/agent10g/root.sh, /bin/sh`
Prerequisite Check Requirements	If you want the prerequisite checks to run before the actual cloning operation could begin, then you must ensure that the software for Oracle Management Agent 10g Release 4 (10.2.0.4) or higher is available in the following location. `<OMS_HOME>/sysman/agent_download/` If the software is not available in this location, you can still proceed with the cloning operation but the prerequisite checks may or may not be performed, depending on the location of the Source Agent Home, that is, the Management Agent to be cloned. If the Source Agent Home is on the host where the OMS is running, then none of the prerequisite checks are run. You can choose to proceed with the cloing operation, but if you still want to run the prerequisite checks, then ensure that the software for Oracle Management Agent 10g Release 4 (10.2.0.4) or higher is available in the location mentioned above. If the Source Agent Home is on any other host, then except for system prerequisite checks, all other prerequisite checks are run. Oracle recommends you to run the prerequisite checks so that the requirements that are not being met are identified, and unnecessary errors and installation failures are avoided beforehand.
Existing Management Agent Requirements	Ensure that you have at least one existing instance of a Management Agent that can be cloned.
Target Host Credentials Requirements	Ensure that the target hosts where you want to clone the Management Agent have the same credentials and file system structure.
Installation Base Directory Requirements	Your installation base directory must be empty and writable. Your installation base directory must NOT be a shared, mounted location.
Agent User Account Permissions and Rights (For Microsoft Windows)	(For Microsoft Windows) Ensure that the agent user account has permissions and rights to perform the following: Act as part of the operating system. Increase quotas. Replace process level token. Log in as a batch job. To verify whether the agent user has these rights, follow these steps: Launch the Local Security Settings. From the Start menu, click Settings and then select Control Panel. From the Control Panel window, select Administrative Tools, and from the Administrative Tools window, select Local Security Settings. In the Local Security Settings window, from the tree structure, expand Local Policies, and then expand User Rights Assignment.
Permissions for cmd.exe (For Microsoft Windows)	(For Microsoft indows) Grant the `Cmd.exe` program Read and Execute permissions for the user account that the batch job runs under. This is a restriction from Microsoft. For more information on this restriction and to understand how you can grant these permissions, access the following Microsoft Web site URL: `http://support.microsoft.com/kb/867466/en-us`

Cloning Management Agent

To clone a Management Agent using Grid Control console, do the following:

In Grid Control, click Deployments. Grid Control displays the Deployments page.
On the Deployments page, from the Agent Installation section, click Install Agent. Grid Control displays the Select Agent Deployment Type page.
On the Select Agent Deployment Type page, click Clone Agent. Grid Contol displays the Agent Clone: Installation Details page.

On the Agent Clone: Installation Details page, do the following:

In the Source Agent section, provide details about the location where the running Management Agent or the archived ZIP file of the running Management Agent is available.

Table 13-2 Element Description - Source Agent Section - Cloning Management Agent

UI Element on the Screen Details Required

UI Element on the Screen	Details Required
Source Agent Home	Specify the location where the Management Agent to be cloned is available. The location can be one of the following: Full path to the Oracle home directory of the Management Agent that you want to clone. Ensure that the path extends up to the `agent10g` directory. For example, `/home/john/Oraclehomes/agent10g/`. Full path to the location where the archived format (ZIP file) is available, that is, if you have already archived the Oracle home directory of the Management Agent. For example, `/home/software/agent.zip`. Ensure that the ZIP file contains the contents of the Oracle home directory. To ensure this, when you create the ZIP file, create it from the parent directory of the agent10g directory. For example, to ZIP the contents from `/scratch/oraclehome/agent/agent10g`, navigate to `/scratch/oraclehome/agent` directory first, and then run `zip -r agent10g agent.zip`. Full path to the shared, NFS mounted location where the Management Agent to be cloned or the archived ZIP file is available. For example, `/home/nfsshared/agent.zip`.
Source Agent Home on OMS	Select this if the location you specified for Source Agent Home (above) is available on the host where OMS is running. Note: If you want to extract the contents of an Oracle home directory to an OMS host, then the Oracle home directory of a Microsoft Windows-based Management Agent must not be extracted on a UNIX-based host (and vice versa).

Source Agent Home

Specify the location where the Management Agent to be cloned is available.

The location can be one of the following:

Full path to the Oracle home directory of the Management Agent that you want to clone. Ensure that the path extends up to the agent10g directory. For example, /home/john/Oraclehomes/agent10g/.
Full path to the location where the archived format (ZIP file) is available, that is, if you have already archived the Oracle home directory of the Management Agent. For example, /home/software/agent.zip.

Ensure that the ZIP file contains the contents of the Oracle home directory. To ensure this, when you create the ZIP file, create it from the parent directory of the agent10g directory. For example, to ZIP the contents from /scratch/oraclehome/agent/agent10g, navigate to /scratch/oraclehome/agent directory first, and then run zip -r agent10g agent.zip.
Full path to the shared, NFS mounted location where the Management Agent to be cloned or the archived ZIP file is available. For example, /home/nfsshared/agent.zip.

Source Agent Home on OMS

Select this if the location you specified for Source Agent Home (above) is available on the host where OMS is running.

Note: If you want to extract the contents of an Oracle home directory to an OMS host, then the Oracle home directory of a Microsoft Windows-based Management Agent must not be extracted on a UNIX-based host (and vice versa).

In the Hosts section, provide details about the target hosts where you want to clone the Management Agent.

Table 13-3 Element Description - Host Section - Cloning Management Agent

UI Element on the Screen Details Required

UI Element on the Screen	Details Required
Platform	Select the platform of the host on which you want to clone. Ensure that the platform you select here matches with the platform of the Source Agent Home.
Provide Host List	Specify the hosts where you want to clone the Management Agent. You can specify either the name of the host or its IP address. Separate them by a comma or white space. For example, `host1.example.com,host2.example.com`. You can specify either physical hosts or virtual hosts, but not a combination of the two. If you are specifying virtual hosts, then select All are Virtual Hosts. If you have a file that contains a list of all required host names, then click Get Host Names From File and select the file. Ensure that the file format is similar to `/etc/hosts` file.
Cluster Name	Specify a name that can be used to form a cluster of the all the target hosts you specified.

Platform

Select the platform of the host on which you want to clone.

Ensure that the platform you select here matches with the platform of the Source Agent Home.

Provide Host List

Specify the hosts where you want to clone the Management Agent. You can specify either the name of the host or its IP address. Separate them by a comma or white space. For example, host1.example.com,host2.example.com.

You can specify either physical hosts or virtual hosts, but not a combination of the two. If you are specifying virtual hosts, then select All are Virtual Hosts.

If you have a file that contains a list of all required host names, then click Get Host Names From File and select the file. Ensure that the file format is similar to /etc/hosts file.

Cluster Name

Specify a name that can be used to form a cluster of the all the target hosts you specified.

In the OS Credentials section, specify the user name and password to access the target hosts where you want to clone the Management Agent. If you are cloning on multiple hosts, then ensure that the credentials are the same for all the hosts.

Select Run root.sh if you want Grid Control to run this script. Grid Control uses SUDO to run this script and prompts you to specify the "invoking user's password" when it runs the script. Ensure that you have SUDO privileges to run /bin/sh, otherwise, the installation may fail.

If /etc/sudoers is configured in such a way that sudo never prompts for a password, then a directory with the host password as the title gets created in the invoking users home directory. To avoid this, ensure that you configure /etc/sudoers file such that running a command using sudo always prompt for a password.

If you do not select Run root.sh here, then you must manually run the script once the installation is complete. To understand how the manually run this script, see Running root.sh Script Manually.
In the Destination section, specify the full path to the directory on the target hosts where you want to clone the Management Agent. For example, /home/mark/OracleHomes.

Ensure that you have write permission on this installation base directory. The Oracle home directory for the Management Agent will be created as a subdirectory in this base directory. For example, if you specify /home/mark/OracleHomes as the installation base directory here, then Grid Control will clone the Management Agent to /home/mark/OracleHomes/agent10g.
In the Port section, specify a port on which the Management Agent can communicate with the OMS.

The same port will be used for all the hosts specified across all platforms. If no port is specified here, the application uses the first free port that is available within the range of 1830 to 1849.
In the Additional Parameters section, specify any additional parameters that you want to pass during the cloning process.

For information about the additional parameters that are supported for Agent Cloning, see Appendix H, "Additional Parameters for Agent Deploy Application".

Note that if you are specifying more than one parameter, then separate them with a white space. For example, -invPtrLoc /home/oraInst.loc -scratchPath /tmp s_OMSHost=<LoadBalancerHost> s_OMSPort=<LoadBalancerPort>.

If you are cloning a Management Agent that was installed along with OMS, then include the following additional parameter:

b_chainedInstall=false, oracle.sysman.top.agent:s_installType=AGENT
In the Management Server Security section, specify the registration password if you want to secure the communication between Management Agent and OMS.
In the Additional Scripts section, specify the additional scripts you want to run before and/or after cloning and configuration steps.

The scripts you specify here must be available on all the target hosts. If you want to run the scripts as SUDO, then select Run as Superuser.

Click Continue. Grid Control displays the My Oracle Support Details page.
On the My Oracle Support Details page, do the following:
- If the host where the Management Agent is being installed has a direct connection to the Internet, then specify an email address and My Oracle Support (formerly Metalink) password.
  
  An email address is required so that security updates and install updates can be sent. You can specify any email address, but Oracle recommends you to specify the My Oracle Support (formerly Metalink) user name. For example, john.mathew@xyz.com.
- If the host where the Management Agent is being installed has an indirect connection to the Internet through a proxy server, then specify an email address and My Oracle Support password, and then in the Connection Details section, specify the proxy server details.
  
  Note:
  You can change the proxy server settings any time after the installation or patching process ends. To do so, run the configCCR command from the /ccr/bin/ directory within the Oracle home directory of the Management Agent.
- If the host where the Management Agent is being installed does not have a direct or indirect connection to the Internet, then specify the email address and leave the other fields blank.
  
  In this case, after you complete the installation process, manually collect the configuration information and upload it to My Oracle Support (formerly Metalink). To understand how the configuration information can be manually collected and uploaded, see the steps outlined in Manually Collecting and Uploading Configuration Information to My Oracle Support (formerly Metalink).
Click Continue.

Note:

If the Management Agent does not start up automatically when you restart the host, then do the following:

Open the agentstup file from the Oracle home of the Management Agent:

$ORACLE_HOME/install/unix/scripts/agentstup
Edit the file to replace executingUser=$USER with executingUser=`id -un`. Then, save and exit the file.
Run the root.sh script from the Oracle home of the Management Agent:

$<ORACLE_HOME>/root.sh
Restart the Management Agent by running the following command from the Oracle home of the Management Agent:

$<ORACLE_HOME>/bin/emctl start agent

This is a one-time action to be taken. Step (1) to Step (3) will ensure that the Management Agent starts up automatically every time you restart the host in the future.

Note:

If the installation fails, review the log files described in Appendix C, "Agent Log Files".

Running root.sh Script Manually

The root.sh script is run after the installation process ends successfully. The script takes care of the postinstallation configurations to be done for Management Agent. If you install a Management Agent using the Agent Clone Wizard, then you are allowed to select an option to run root.sh script automatically.

However, if you have not selected there, then you must run the script manually after the installation completes.

To run the root.sh script manually:

Log in as a root user on the host. Alternatively, use the sudo command to change to a root user.
Run the root.sh script from the Oracle home directory of the Management Agent:

<oracle_home>/root.sh

For example, if you are using sudo to change to a root user, then you will run the following command:

/usr/local/bin/sudo /scratch/OracleHomes/agent10g/root.sh

Cloning Management Agent Using Command Line

This section describes how you can clone a Management Agent using command line interface. In particular, this section covers the following:

Cloning Management Agent Installed with OMS or As Additional Agent
Logs to Review if Cloning Fails

Cloning Management Agent Installed with OMS or As Additional Agent

To clone a Management Agent that was installed with OMS or as an additional, standalone agent, do the following:

Install a Management Agent on a host using any of the deployment methods described in Chapter 10, " Deploying Management Agent".
Zip the Management Agent Oracle home that you want to clone (for example, agent.zip).
Perform a file transfer (FTP) of this zipped Oracle home onto the destination host (for example, ftp agent.zip).
In the destination host, unzip the Management Agent Oracle home.
Go to $ORACLE_HOME/oui/bin/ directory and run the following command:
- If you are cloning a Management Agent that was installed along with OMS, then run the following command:
```
./runInstaller -clone -forceClone ORACLE_HOME=<full path of Oracle home> ORACLE_HOME_NAME=<Oracle home name> -noconfig -silent b_chainedInstall=false oracle.sysman.top.agent:s_installType=AGENT
```
- If you are cloning a Management Agent that was installed as a fresh standalone Management Agent, then run the following command:
```
./runInstaller  -clone -forceClone ORACLE_HOME=<full path of Oracle home> ORACLE_HOME_NAME=<Oracle home name> -noconfig -silent
```
Note:
By default, the cloned Management Agent does not inherit the customized parameters in the emd.properties file of the source Management Agent. In other words, the modifications to emd.properties parameters of the source Management Agent are reset to default values for the cloned, target Management Agent.
If you want to retain the changes done to the emd.properties file, then redo the changes in the emd.properties.template file, as this is the file that is instantiated while cloning a Management Agent. Both these files are located in $ORACLE_HOME/sysman/config/, where $ORACLE_HOME is the Oracle home directory of the source Management Agent.
Execute the following script to run the Agent Configuration Assistant (agentca):
```
$ORACLE_HOME/bin/agentca -f
```
Note:
The cloned Management Agent is not in the secure mode by default. You must manually secure the Management Agent by running <Oracle_Home>/bin/emctl secure agent. However, note that even after securing the Management Agent, some data might still be transferred over the network without being encrypted.
(For UNIX only) After running the configuration assistant, run the following scripts as a root user on the host.
- If this is the first Oracle product you just installed on the host, then run the oraInstroot.sh script from the Central Inventory:
```
$ORACLE_HOME/oraInventory/oraInstRoot.sh
```
  For example, if you are using sudo to change to a root user, then you will run the following command:
  
  /usr/local/bin/sudo $ORACLE_HOME/oraInventory/oraInstRoot.sh
- Run the root.sh script from the Oracle home directory of the Management Agent:
```
$ORACLE_HOME/root.sh
```
  For example, if you are using sudo to change to a root user, then you will run the following command:
  
  /usr/local/bin/sudo /scratch/OracleHomes/agent10g/root.sh

Note:

If the Management Agent does not start up automatically when you restart the host, then do the following:

Open the agentstup file from the Oracle home of the Management Agent:

$ORACLE_HOME/install/unix/scripts/agentstup
Edit the file to replace executingUser=$USER with executingUser=`id -un`. Then, save and exit the file.
Run the root.sh script from the Oracle home of the Management Agent:

$<ORACLE_HOME>/root.sh
Restart the Management Agent by running the following command from the Oracle home of the Management Agent:

$<ORACLE_HOME>/bin/emctl start agent

This is a one-time action to be taken. Step (1) to Step (3) will ensure that the Management Agent starts up automatically every time you restart the host in the future.

Logs to Review if Cloning Fails

If the cloning operation fails, then review the following log files. The information in these logs might help you describe the failure while raising service requests with Oracle Support.

<ORACLE_HOME_INVENTORY>/logs/cloneActions<latest timestamp>.log
<ORACLE_HOME_INVENTORY>/logs/oraInstall<latest timestamp>.err
<ORACLE_HOME_INVENTORY>/logs/oraInstall<latest timestamp>.out

For example:

/home/oracle/oraInventory/logs/cloneActions2008-02-14_06-29-37AM.log

Cloning Management Agent on a Cluster

To clone a Management Agent on a cluster, do the following:

Install a Management Agent on a host using any of the deployment methods described in Chapter 10, " Deploying Management Agent".
Zip the Management Agent Oracle home that you want to clone (for example, agent.zip).
Perform a file transfer (FTP) of this zipped Oracle home to all the target nodes of the cluster (for example, ftp agent.zip).
On each target node of the cluster, unzip the Management Agent Oracle home. Oracle recommends you to maintain the same destination location on all nodes of the cluster.
On each target node of the cluster, go to $ORACLE_HOME/oui/bin/ directory and run the following command:
```
./runInstaller  -clone -forceClone ORACLE_HOME=<full path of Oracle home> ORACLE_HOME_NAME=<Oracle home name> -noconfig -silent
```
Note:
By default, the cloned Management Agent does not inherit the customized parameters in the emd.properties file of the source Management Agent. In other words, the modifications to emd.properties parameters of the source Management Agent are reset to default values for the cloned, target Management Agent.
If you want to retain the changes done to the emd.properties file, then redo the changes in the emd.properties.template file, as this is the file that is instantiated while cloning a Management Agent. Both these files are located in $ORACLE_HOME/sysman/config/, where $ORACLE_HOME is the Oracle home directory of the source Management Agent.
On each target node of the cluster, run the following script to run the Agent Configuration Assistant (agentca):
```
$ORACLE_HOME/bin/agentca -f -c "node1, node2, node3...."
```
Note:
The cloned Management Agent is not in the secure mode by default. You must manually secure the Management Agent by running <Oracle_Home>/bin/emctl secure agent. However, note that even after securing the Management Agent, some data might still be transferred over the network without being encrypted.
(For UNIX only) After running the configuration assistant, run the following scripts as a root user on the host.
- If this is the first Oracle product you just installed on the host, then run the oraInstroot.sh script from the Central Inventory:
```
$ORACLE_HOME/oraInventory/oraInstRoot.sh
```
  For example, if you are using sudo to change to a root user, then you will run the following command:
  
  /usr/local/bin/sudo $ORACLE_HOME/oraInventory/oraInstRoot.sh
- Run the root.sh script from the Oracle home directory of the Management Agent:
```
$ORACLE_HOME/root.sh
```
  For example, if you are using sudo to change to a root user, then you will run the following command:
  
  /usr/local/bin/sudo /scratch/OracleHomes/agent10g/root.sh