C Using the Downloadable Management Agent

This appendix describes how to add additional Host targets to the Oracle Enterprise Manager Grid Control by downloading and installing the Oracle Management Agent using the agentDownload script.

To add a Host target, you must install the Management Agent on the host computer you want to manage. When the Management Agent on that host begins communicating with the Oracle Management Service, the Agent target and the Host target will appear in the list of targets.

See Also:

For more information about the directories and files installed by the Enterprise Manager installation, see Oracle Enterprise Manager Advanced Configuration.

Methods for Installing the Management Agent

After you install the Management Service, your next step is to install the Management Agent on each host computer that you want to manage. Enterprise Manager provides a number of installation methods:

On each host computer, run the Oracle Universal Installer from the Enterprise Manager CD-ROM and select the Additional Management Agent installation type. Instructions for using this Management Agent installation method are included in Chapter 2. You can also share the software on the network, then download and run Oracle Universal Installer in silent mode on each local host using the response file (agent_download.rsp) and initialization parameters file (oraparam_agent.ini) provided with the Management Service installation:
```
AS_HOME/sysman/agent_download/
```
See Also:
Refer to the Oracle Universal Installer Concepts Guide for details on using response files and initialization parameter files with the Universal Installer.
Use the agentDownload script to install Management Agents. This method is preferred for environments with multiple hosts or if the targets are not set up with the required packages for an interactive installation.

This appendix describes how to use the agentDownload script to install and deploy Management Agents across managed hosts within your enterprise.

About the agentDownload Script

The downloadable Agent software contains a sample script called agentDownload. This script provides a means for installing Management Agents that can be customized for specific environments using a silent, scripted installation. The agentDownload script is fully functional and self-documenting so it can be customized easily for specific environments.

The agentDownload script uses "pull" technology. In other words, even though the script does not have to exist on a local file system, it must always be executed from the target host computer. You must be logged into the target host to run the script. Files are not "pushed" from a central location to a list of target hosts. Instead, files are "pulled" to the local $ORACLE_HOME from the staged product installation location.

This means that the agentDownload needs to be launched from each target host where you want the Management Agent installed. Because the installation is scripted, it is possible to use a wrapper script, UNIX cron job, rdist, or a combination of operating system features to fully automate this process for mass deployments.

Benefits of the agentDownload Script

The download script deploys the standard Management Agent installation, with some additional benefits:

Can be modified for specific user environments.
Non-interactive, silent, installations.
Output is text-only (non-graphical).
Management Agents installed using the script are identical to Management Agents installed with the Oracle Universal Installer graphical installation.
Simplifies deploying Management Agents in secure Web environments that are configured to provide HTTP access.

Obtaining the agentDownload Software

The downloadable Agent software is available on the platform-specific CD from which the Oracle Management Service was installed, and from the following Oracle Technology Network Web site:

http://otn.oracle.com/software/products/oem/index.html

To initiate a silent Oracle Universal Installer session using HTTP to install Management Agents, download and execute the agentDownload script described in this appendix to perform the installation. (Note that proxy servers are not supported.)

Using the agentDownload Script

To deploy multiple Management Agents using the agentDownload script, you must do the following:

Install the Oracle Management Service.

You install the Management Service using the Oracle Universal Installer and the instructions in Chapter 2. The Management Service is installed and deployed into its own Oracle Application Server home directory.

See Also:
For more information about the directory structure of a typical Management Service installation, see Oracle Enterprise Manager Advanced Configuration.
The download stage for the Mangement Service platform is installed with the Management Service. For example, for Solaris operating systems, the download stage can be found in:
```
AS_HOME/sysman/agent_download/solaris
```
The agentDownload script, the response file, and readme file can be found in:
```
AS_HOME/sysman/agent_download/
```
Download the agentDownload script to the target host from the Management Service URL.

The Management Service installation creates a Web sever alias called agent_download that maps to a physical directory in the Oracle Application Server home directory where the Management Service is installed and deployed. For example, if you installed the Management Service on a host named mgmthost27.acme.com, you could access the following URL from a browser:
```
http://mgmthost27.acme.com:4889/agent_download/
```
Note:
Port 4889 is the default port for Grid Control, so should be available after you install the Management Service.

Using this Web server alias, you can download the script to the target host computer using the following URL. Save the script locally as agentDownload (no extensions).
```
http://mgmthost27.acme.com:4889/agent_download/agentDownload.OS
```
Where OS represents the operating system platform. For example, for Solaris operating systems, the script is named agentDownload.solaris.

Any method of retrieving the file is acceptable: cp, rcp, scp, FTP, etc. The script can also be retrieved by launching a browser on the target machine and saving the link to a local file.
Execute the agentDownload script on the target host.

Before launching the script, ensure that:
- The execute bit is set and the script file has the proper file protection settings (use chmod to ensure the file has the correct privileges).
- The $ORACLE_HOME environment variable is set in the user environment. This will be the location of the Management Agent home on the target host; if the directory does not exist it will be created during the installation. If it exists, it must be empty.
- The jar executable file is in the PATH environment variable.
- The wget (or other file transfer mechanism) has been defined in the script. The script default is to call /usr/local/bin/wget.
- The $AGENT_INSTALL_PASSWORD environment variable is set in the environment if the Management Agent will be uploading to a secure Management Service.
  
  See Also:
  For more information about enabling Security for Enterprise Manager components, see Oracle Enterprise Manager Advanced Configuration.
- The script user has the necessary file access permissions for the Management Agent home directory
After the Management Agent installation is complete, change directory to the Agent home directory and run the root.sh script as the root user.

For example:
```
$PROMPT>su root
Password: root_password
#./root.sh
#exit
$PROMPT>
```
The root.sh script must be run as root; otherwise, it will exit and the Enterprise Manager job system will not be available. The job system is required for some Enterprise Manager features, such as hardware and software configuration tasks and configuring managed database targets.

Script Details

The agentDownload script performs the following actions:

Creates home directories for the Management Agent and Oracle Universal Installer if they don't exist, based on the $ORACLE_HOME environment variable:
Downloads the agent_download.rsp response file from the Management Service Web server.

The Management Service installs the response file with the name and port number of the Management Service. As a result, the Management Agent you install will be configured to use the Management Service from which the response file was downloaded.
Downloads a jarred Oracle Universal Installer for the target operating system from the Management Service Web server.
Unjars the Oracle Universal Installer and points the Oracle Universal Installer to the product definition file (products.xml) hosted by the Management Service Web server.

Launches the Oracle Universal Installer in silent mode from the local machine; the Universal Installer pulls files from the Web server to the target machine via HTTP.

Note:

This script uses the -ignoresysPrereqs flag to bypass pre-requisite check messages during installation; pre-requisite checks are still performed and saved to the installer logs. While this makes the Management Agent easier to deploy, check the logs to make sure the target machines on which you are installing Management Agents are properly configured for successful installation.

The resulting installation and configuration, including the automatic discovery of managed targets on the Management Agent host, is identical to that provided by the Management Agent install on the Enterprise Manager CD set.
The agentDownload script creates a log file in $ORACLE HOME.
The script will not install into an existing directory if it contains any files other than agentDownload session logs. Do not modify the script to install into an existing ORACLE HOME!
At the end of a successful install, the Agent will be started and should begin successfully uploading to the OMS, presuming automatic discovery and automatic start were not disabled at the command line.

To run the script use the following command:

./agentDownload41 [-dhiostx]

Descriptions of the script options follow:

Option	Description
-d	Do not automatically discover targets during installation.
-h	Usage: Displays and describes the options that can be used with this script.
-i	Inventory pointer location file: Can be used to point the installer to a non-default inventory.
-o	ORACLE_HOME: Can be picked up from the inventory or specified on the command line.
-s	Installer stage directory: Points to an installer previously downloaded by the script. If defined, the local installer will be launched and the jarred installer will not be downloaded.
-t	Do not automatically start the Agent at the end of installation.
-x	Debug output: Turns on shell debugging.

Customization

You can edit the contents of the agentDownload script so it uses a specific tool for transferring files from the Management Service Web server. The contents of the file contain instructions for doing so, as shown in the following example:

WGET="/usr/local/bin/wget --dot-style=mega --verbose --tries=5"

InstallerDownloadCmd=$WGET
# Define the command to be used to download the jarred installer from
# the web server hosting the OMS.
# Other download possibilities: ftp; cp/scp; use local browser to save the
# link to a file on the target machine. 
# This example uses wget, a GNU tool for http and ftp file transfers. 
# If the products.xml referenced by the Oracle Installer is a URL, then the
# Installer will download its files via http. This greatly facilitates
# performing installs in a secure environment that may include firewalls 
# and servers with limited access (no ftp server, NFS mounts not available,
# etc.).
# Enterprise Manager version number. This is used to construct the
# home name used by the installer

GNU wget is available for most platforms and can be downloaded from the following location:

http://www.gnu.org/software/wget/wget.html