There are Oracle products that currently do not bundle Oracle Configuration Manager as part of their kit. Also, there are previous product installations where Oracle Configuration Manager was installed, but not configured. The manual installation of Oracle Configuration Manager in these environments can be tedious and time consuming. Mass Deployment can facilitate the deployment of Oracle Configuration Manager in these environments, as well as update and configure various systems from a single location.
This chapter provides the following:
The Oracle Configuration Manager Mass Deployment Utility (Mass Deployment) provides a mechanism by which you can distribute Oracle Configuration Manager to any Oracle home where the Oracle Configuration Manager is not installed, or installed but not configured. Mass Deployment also updates existing homes where Oracle Configuration Manager installations are out of date, reconfigures existing installations, and instruments the database located in that Oracle home.
Mass Deployment is made up of the following components:
Manages the encryption of passwords in both the password file and the input file used in the deployment process.
Comma separated value file that maps user name and password to a group name. The group name is then used in the input file rather than the user name and password, therefore making the credentials more secure.
Causes actions to be performed in an Oracle home at a remote site.
Lists the fields used as input into the remote_op utility. Use this file as a template for your input file.
Comma separated file that provides a list of entries where each entry acts on a specified target and is input to the remote_op utility.
Results of running the remote_op utility. The format is comma separated value. Each entry from the input file will have an entry in the output file with the results of the operation.
Contains details of each action executed on the remote target home. The .log file is named like the output file but with .log appended.
The following prerequisites are needed.
To successfully use the Mass Deployment Utility, the JAVA_HOME environment variable can be set to any JDK greater than version 1.5.
For target homes, you must ensure the availability of the required JDK version (1.2.2 or later on UNIX, and 1.3.1 or later on Windows). One of the following must be true:
The JDK is installed in the target home.
A symlink to a JDK installation is present in the target home.
The JAVA_HOME environment variable, defined in the .kshrc for the user, points to the appropriate JDK installation.
The Mass Deployment Utility uses SSH to transfer files and execute remote commands (thus this installation method is not appropriate for environments that do not use, or block, SSH connections). SSH offers the following benefits:
The ability to transfer files
The ability to set/modify environments
The ability to remotely execute host commands
A high level of security compared to other remote execution methods (for example, rsh)
While SSH is typically present on most Linux/UNIX systems, Windows hosts do not usually support SSH access by default. To allow the Mass Deployment Utility to connect to Windows hosts, SSH services need to be installed. The Mass Deployment Utility needs this along with other software tools that come with the Cygwin suite. The full suite can be downloaded from:
http://www.cygwin.com
See Appendix B, "Setting Up SSH (SSHD) Server on Microsoft Windows" for information of how to do these installs.
Decide if the Support Hub is required for the targets to connect to an Oracle server. See Oracle Configuration Manager Support Hub Guide for information regarding the Support Hub. If the Support Hub is required by the targets, the Mass Deployment Utility must be set up to configure the use of the Support Hub for all targets. To enable the configuration of the Support Hub, do the following:
Edit the md.properties file located at <path>/ocm/md/config directory.
Add the following line:
md.repeater.uri=http://<host_name>:<port> where <host_name> is the host where the Support Hub is deployed <port> is the port used to access the Support Hub
When this property is set, all installations done by the Mass Deployment utility will configure the Support Hub.
For information on how to install the Companion Distribution kit, see Section 1.2, "How to Install the Companion Distribution Kit".
After you install the kit, unzip the ocm_massdeployment-10.0.1.0.0.zip file. This will install Mass Deployment in <your_directory>/ocm/md directory.
The following components in <your_directory>/ocm/md/bin directory make up the Mass Deployment Utility:
remote_op
This component installs, updates, or configures the homes on remote systems with the appropriate Configuration Manager details.
secure_password
This component manages the encryption of passwords in the password.csv file and the input file.
All configuration properties for the Mass Deployment Utility are in the <your_directory>/ocm/md/config/md.properties file. Copy the md.properties.template file to create your own md.properties file. You can edit this file to modify configuration properties. The important properties follow.
md.win.tmp
Location of the temporary directory on the remote machine with any version of Windows operating system. All the files required for remote operations are copied at this location on the remote machine. Default value is C:\
. If required you can modify the default.
Ensure that this directory is available on all the remote machines and all the users have read and write privilege on this directory.
Note:
You must use a double slash (\\) in the md.properties file to configure themd.win.tmp
file, for example, md.win.tmp=d:\\tmp\\md-tmp
.md.unix.tmp
Location of the temporary directory on the remote machine with an operating system other then Windows. All the files required for remote operations are copied at this location on the remote machine. Default value for this is /tmp
. If required you can modify the default.
Ensure that this directory is available on all the remote machines and all the users have read and write privilege on this directory.
md.repeater.uri
Use this property to provide the Support Hub URL if you need the Support Hub to connect to an Oracle server. If thisproperty is set, all installations done by this utility will configure the Support Hub.
Note: Remember to remove the number sign (#) from the beginning of the line.
When you run either of the Mass Deployment utilities for the first time, you will be prompted for a password. This password will be required each time either the remote_op or secure_password utility is used. The password must be at least 8 characters long.
Since the purpose of the Mass Deployment Utility is to take action on remote target homes in your enterprise, you need a mechanism by which to provide input to the Mass Deployment Utility. The mechanism is an input csv file which contains the necessary data.
To facilitate the use of the input file, the Mass Deployment Utility contains a template (sample_input.csv) for you to use to provide the field values.
The password.csv file is used to associate a group name with credentials (user name/password pair). By defining a password group, you can use the name of the password group as input into the user name field and leave the password field empty in the input file. This enables you to store all your passwords, in encrypted form, in one file.
When you add a password group for the first time:
Copy the password.csv.template
file located in the ocm/md/config
directory and name it password.csv
cp password.csv.template password.csv
Ensure the renamed file is in the ocm/md/config
directory
Edit the password.csv file
The password.csv file is made up of the following fields: password group name, user name, and password. The password group name replaces the user name in the input csv file. For example, the first line in the password.csv file could look like:
<group name>,<user name>,<password> where <group name> is the name of the group <user name> is the name of the user <password> is the password associated with the user name
For example, the first line of the password.csv file could be:
accounting,payables,mypswd
Therefore, a line within the input file that uses the password group could look like:
install,abc22,[accounting],,
where install is the action
abc22 is the host
[accounting] is the password group name which must be in brackets
,, denotes that the password field is left blank
Note the following:
Name of the file is password.csv, all lower case
password.csv file must be in the config directory, that is, ocm/md/config/password.csv
All types of credentials are stored in this file, for example, MetaLink, proxy, database, and so on.
The password.csv file is always encrypted whenever the secure_password or remote_op utilities are executed.
The secure_password utility encrypts passwords located in the password.csv and input files. Consider running the secure_password utility when you create or modify the password.csv file. This encrypts the passwords immediately.
An example of the output follows:
prompt>ocm/md/bin/secure_password OCM Mass Deployment Utility - Release: 10.0.1.0.0 Copyright (c) 2009, Oracle. All rights reserved. Please enter the password for Mass Deployment Utility. Password: prompt>
Lines with errors are displayed with an explanation of the errors, for example, user name missing. On success, the prompt is displayed.
Note the following:
Encrypted passwords in the password.csv and input files begin with ENCR_
Previously encrypted passwords are ignored
Passwords are encrypted on lines without errors. When input lines contain errors, the passwords, if they are present on those lines, will be encrypted but these groups will not be considered for processing.
Oracle provides a password.csv file template that contains only headers: group name, user name, password.
Files that contain encrypted data are not portable. Encryption is tied to the Mass Deployment installation.
There is a help option available for the secure_password utility. To access help, type:
secure_password -help
For example:
secure_password -help OCM Mass Deployment Utility - Release: 10.0.1.0.0 Copyright (c) 2009, Oracle. All rights reserved. Usage: secure_password [-input_file] -help : prints help for the command -input_file <input.csv> : input file to secure Example: secure_password -input_file input.csv reads the config/password.csv file and input.csv. It will modify these files by encrypting all clear text passwords.
Once the input file is created from the template, execute the Mass Deployment Utility using this file:
remote_op -input_file <input.csv> [-out_file <out_file.csv>] [-check]
for example:
bin/remote_op -input_file ~/md_scripts/install_soh_2dir.csv
You will then see the following text displayed on the screen:
OCM Mass Deployment Utility - Release: 10.0.1.0.0 Copyright (c) 2009, Oracle. All rights reserved. Please enter the password for Mass Deployment Utility. Password: [Password must be correct or execution will not occur.] Please be patient, process may take some time. Log File: /scratch/jsmith/massdeploy/ocm_companion/ocm/md/out/output-2009-07-19_04-32-43-PM-install_soh_2dir.csv.log Please see the output file /scratch/jsmith/massdeploy/ocm_companion/ocm/md/out/output-2009-07-19_04-32-43-PM-install_soh_2dir.csv
There is a help option available for the remote_op utility. To access help, type:
remote_op -help
For example:
remote_op -help OCM Mass Deployment Utility - Release: 10.0.1.0.0 Copyright (c) 2009, Oracle. All rights reserved. Usage: remote_op -input_file <input.csv> [-out_file <out.csv>] [-check] -check : actual remote operation is not performed -help : prints help for the command -input_file <input.csv> : input from this file -out_file <output.csv> : output to this file Example: remote_op -input_file input.csv reads the input.csv file and performs remote OCM operations like install, config, upgrade. It will also invoke secure_password command implicitly.
The arguments for the remote_op utility are:
-input_file
Name of the input file. There are no restrictions on the name of the file. For example, the name of the input file could be account_payables.csv
-out_file
Optional argument. If specified, this is the name of the output file. If this argument is not specified, the output file name will default to the input file name prepended by output- and the timestamp, for example, output-2009-07-21_10-39-36-AM-account_payables.csv and will be located in the ocm/md/out directory.
-check
Verifies that the information is correct in the input file without performing the actual remote operation.
The results of running the remote_op utility are as follows:
Output file
Contains the commands that were executed and the resulting status of each execution. See Section 2.4.6, "Mass Deployment Output File".
Log file
Contains detailed information about the remote operation. See Section 2.4.7, "Log File".
Credentials is the general term for the various user names and passwords in the input file (host credentials, MetaLink credentials, proxy credentials, and database credentials). There are 3 ways to provide credentials in the input file.
Use the group name defined in the password.csv file. This file is located in the ocm/md/config directory.
If you want to be prompted for the password as the remote_op utility processes the input file, type __PROMPT__ in the password fields in the input file. For example: install,host123,jsmith,__PROMPT__,
The word PROMPT is case sensitive and must be in upper case. Otherwise, the word will be considered a password. Once processed, __PROMPT__ is replaced with the encrypted password (starts with ENCR_) in the input file.
You can also use __PROMPT__ instead of the password in the password.csv file. In this case, the user will be prompted for the password when secure_password (or remote_op) is executed.
Here is an example of the output when using __PROMPT__. (The prompting is in bold.)
OCM Mass Deployment Utility - Release: 10.0.1.0.0 Copyright (c) 2009, Oracle. All rights reserved. Please enter the password for Mass Deployment Utility. Password: Password for user aime (host:abcd123): Confirm Password: Password for user joe.smith@example.com (metalink): Confirm Password: Encrypting input file /home/jsmith/md_scripts/instrument.csv Please be patient, process may take some time. Log File: /scratch/jsmith/massdeploy/ocm/md/out/output-2009-07-27_07-07-44-AM-instrument_nt.csv.log
The input file no longer contains __PROMPT__, it now contains the encrypted password.
Include the credentials in the input file and then run the secure_password utility on the input file. If you do not run secure_password on the input file, the first time you run the remote_op utility, the passwords are encrypted.
The input csv file is the input to the remote_op utility. The file contains a line for each action / host /target home combination. If a password group name is used rather than credentials, the group name in brackets replaces the user name and the password is left empty.
A template, named sample_input.csv, is available and looks like the following:
#Action,HostName,Host-user,Host-Password,Product Home Path,Oracle Config Home Path,OCM Version,OCM Status,OCM Mode (connected/disconnected),Db SID,DB Type (EM/Ebiz/db),ML-user (Metalink user ID),ML-Pwd,Proxy-Host,Proxy-Port,Proxy-user,Proxy-Pwd,DB-user (SYSDBA user),DB-Pwd,DB-App-user (Ebiz user if db type is Ebiz),DB-App-Pwd (Ebiz user password if db type is Ebiz or SYSMAN password if db type is EM),Cmd Status (Status of the remote operation)
Note that the pound sign (#) in the template is used to denote a comment. The remote_op and secure_password commands ignore lines starting with a pound sign (#).
The following table describes the elements in the input file. The sample input file is located at ocm/md/sample_input.csv. You can use a spreadsheet for easier input.
Table 2-1 Fields in the Input csv File
Field | Description |
---|---|
Mandatory field. Specifies what action is to be performed in the Oracle Home. Options are:
|
|
Mandatory field. Host domain name or host IP. |
|
Mandatory field. Host user or group name as input [group]. |
|
Host password or blank if group name is provided in the Host-User field. See Section 2.4.4, "Credentials" |
|
Mandatory field. Location where the command will be executed |
|
Optional field. Specify if this is a shared Oracle home. |
|
Output only. OCM version installed in an Oracle home. |
|
Output only. OCM status. |
|
Output only. OCM connection mode: connected, connected (unauthenticated) for e-mail only registrations, or disconnected. |
|
Database system identifier. Used for install and instrument actions. If specified for Install action, the database will automatically be instrumented. |
|
EM, ebiz, db. Specify only for Install and Instrumentation actions. |
|
MetaLink User (can be a group name [group]). Required for install, config, and chmod_con actions. |
|
MetaLink Password (blank if group name is provided in the ML-User field). This field is not mandatory. If the MetaLink password is not provided, the Oracle Configuration Manager is configured in unauthenticated registration mode. See Section 2.4.4, "Credentials" |
|
Proxy host (optional, only used if required) |
|
Proxy port (optional, only used if required) |
|
Proxy user (or group) (optional, only used if required) |
|
Proxy password (blank if group used) (optional, only used if required) |
|
SYSDBA user - This field is not required if OS Authentication is enabled on the database |
|
Password for the SYSDBA user. This field is not required if OS Authentication is enabled on the database. |
|
When DB type is Ebiz, specify the Ebiz application user name. |
|
Ebiz application user password if DB Type is Ebiz or SYSMAN password if DB type is EM. |
|
Output only. Status of the remote operation. Provides detailed error message for each operation. |
The checks performed by the Oracle Configuration Manager operations are described in Table 2-2.
Table 2-2 Checks Performed By Oracle Configuration Manager Operations
Oracle Configuration Manager Operation | Checks To Be Performed |
---|---|
install |
|
upgrade |
|
chmod_con |
|
config |
|
get_info |
|
instrument |
|
After you run the input file through the Mass Deployment Utility (remote_op), the results are in the output file. If you specify the -out_file argument and provide a file name, that is the name of the file.
However, if you do not specify the -out_file argument, the output file name will default to the input file name prepended by output- and the timestamp, for example, output-2009-07-21_10-39-36-AM-account_payables.csv and located in the ocm/md/out directory.
The fields in the out csv file are the same as the fields in the input csv file with the following fields updated.
Action
Action name is replaced with a set of double quotes ("") if the action is successful.
OCM Version
Output only. OCM version installed in an Oracle home.
OCM Status
Output only. Current OCM status (for example, idle or scheduled collection running).
OCM Mode
Output only. OCM connection mode: connected, connected (unauthenticated) for e-mail only registrations, or disconnected
Cmd Status (Status of the remote operation)
Status of the remote operation. Provides detailed error message for each operation.
Along with the output CSV file, the Mass Deployment Utility also generates a log file. This file gives details of all the files copied and commands executed along with their output on the remote host.
The log file is located in the same directory as the output file and has the same name as the output file with .log appended, for example, <output_file.csv>.log
The following restrictions apply when you are working with Mass Deployment.
For a specific user on a remote machine, only a single invocation of Mass Deployment Utility at any instance is supported. Attempting to invoke multiple instances of Mass Deployment simultaneously on a single remote machine for a specific user can result in unpredictable errors.
When Oracle makes enhancements to the Mass Deployment Utility, Oracle suggests that you upgrade your version of the utility. To upgrade Mass Deployment, perform the following steps:
Download the Companion Distribution kit
Copy the ocm_companion-10.0.1.0.0.zip
file to the location where you want to install the Companion Distribution kit.
Unzip the file as follows:
unzip -d <full_path> ocm_companion-10.0.1.0.0.zip
where <full_path> represents the full path where you want to locate the companion distribution kit
For example:
unzip -d /scratch/jsmith/install/ocm_companion-10.0.1.0.0.zip
As a result, the Mass Deployment Utility kit (ocm_massdeployment-10.0.1.0.0.zip
) will be placed in the ocm_companion/distribution
destination directory. For example,
ocm_companion/distributions ocm_massdeployment-10.0.1.0.0.zip (Mass Deployment Utility kit)
Copy the ocm_massdeployment-10.0.1.0.0.zip
file to the location where you want to install the Mass Deployment Utility.
Install the Mass Deployment Utility
Unzip the ocm_massdeployment-10.0.1.0.0.zip
file. This will install the Mass Deployment Utility in <your_directory>/ocm/md directory.
In the Mass Deployment input file, enter the information for your Oracle Home locations.
To identify which of your Oracle Homes have the unauthenticated Oracle Configuration Managers, use the Mass Deployment action get_info
. In the output file, check the value of the OCM Mode field for any homes with the value of "Connected (unauthenticated)" and check the MetaLink User field which indicates the MetaLink User who can access the authentication mode. See Example 2-1 and Example 2-2.
#Action,HostName,Host-user,Host-Password,Product Home Path,Oracle Config Home
Path,OCM Version,OCM Status,OCM Mode (connected/disconnected),Db SID,DB Type
(EM/Ebiz/db),ML-user (Metalink user ID),ML-Pwd,Proxy-Host,Proxy-Port,Proxy-user,Proxy-Pwd,DB-user (SYSDBA
user),DB-Pwd,DB-App-user (Ebiz user if db type is Ebiz),DB-App-Pwd (Ebiz user
password if db type is Ebiz or SYSMAN password if db type is EM),Cmd Status
(Status of the remote operation)
get_info,mycompany.com,jsmith,ENCR
075ACDEB39C61A874BA0F6FD4B93BF52,/home/jsmith/db10g,,,,,,,,,,,,,,,,,
#Action,HostName,Host-user,Host-Password,Product Home Path,Oracle Config Home Path,OCM Version,OCM Status,OCM Mode (connected/disconnected),Db SID,DB Type (EM/Ebiz/db),ML-user (Metalink user ID),ML-Pwd,Proxy-Host,Proxy-Port,Proxy-user,Proxy-Pwd,DB-user (SYSDBA user),DB-Pwd,DB-App-user (Ebiz user if db type is Ebiz),DB-App-Pwd (Ebiz user password if db type is Ebiz or SYSMAN password if db type is EM),Cmd Status (Status of the remote operation) ,mycompany.com,jsmith,ENCR 075ACDEB39C61A874BA0F6FD4B93BF52,/home/jsmith/db10g,,10.3.1.0.0,idle,Connected (unauthenticated),,,foo@bar.com,,,,,,,,,,Success: get_info operation
To convert unauthenticated Oracle Configuration Managers to authenticated ones, use the Mass Deployment action config
. See Example 2-3 and Example 2-4.
#Action,HostName,Host-user,Host-Password,Product Home Path,Oracle Config Home
Path,OCM Version,OCM Status,OCM Mode (connected/disconnected),Db SID,DB Type
(EM/Ebiz/db),ML-user (Metalink user
ID),ML-Pwd,Proxy-Host,Proxy-Port,Proxy-user,Proxy-Pwd,DB-user (SYSDBA
user),DB-Pwd,DB-App-user (Ebiz user if db type is Ebiz),DB-App-Pwd (Ebiz user
password if db type is Ebiz or SYSMAN password if db type is EM),Cmd Status
(Status of the remote operation)
config,mycompany.com,jsmith,ENCR
075ACDEB39C61A874BA0F6FD4B93BF52,/home/jsmith/db10g,,,,,,,joe.smith@example.com,ENC
_8EBB07D9D486C17A4BA0F6FD4B93BF52,,,,,,,,,
#Action,HostName,Host-user,Host-Password,Product Home Path,Oracle Config Home
Path,OCM Version,OCM Status,OCM Mode (connected/disconnected),Db SID,DB Type
(EM/Ebiz/db),ML-user (Metalink user
ID),ML-Pwd,Proxy-Host,Proxy-Port,Proxy-user,Proxy-Pwd,DB-user (SYSDBA
user),DB-Pwd,DB-App-user (Ebiz user if db type is Ebiz),DB-App-Pwd (Ebiz user
password if db type is Ebiz or SYSMAN password if db type is EM),Cmd Status
(Status of the remote operation)
,mycompany.com,jsmith,ENCR
075ACDEB39C61A874BA0F6FD4B93BF52,/home/jsmith/db10g,,10.3.1.0.0,idle,Connected,,,
oe.smith@example.com,ENCR_8EBB07D9D486C17A4BA0F6FD4B93BF52,,,,,,,,, Success: config
operation
You may see the following errors when running Mass Deployment:
If a user moves a password or input file from one Mass Deployment installation to another, the encryption will not work (it is unique to the installation), the output file will contain the following error:
"Error in Decrypting credentials for host, metalink, proxy. This can happen if credentials are encrypted using a different password. Type the credentials in clear text and re-try the operation."
If JAVA_HOME is not set to jdk1.5, you will see an error like the following:
Java Version 1.4.2_14 is less than minimum required (1.5). JAVA_HOME does not contain a valid JDK/JRE.