Enterprise Manager Control (EMCTL) is a command line utility installed with EM to administer or control the core components of Enterprise Manager Cloud Control, particularly Oracle Management Service (OMS) and Oracle Management Agent (Management Agent). The utility is available by default with every Enterprise Manager installation.
This chapter explains the following:
Guidelines for Starting Multiple Enterprise Manager Components on a Single Host
Starting and Stopping Oracle Enterprise Manager 12c Cloud Control
Services That Are Started with Oracle Management Service Startup
Starting and Stopping the Oracle Management Service and Management Agent on Windows
Specifying New Target Monitoring Credentials in Enterprise Manager
EMCTL Commands:
Troubleshooting:
In UNIX systems, to run EMCTL commands for Oracle Management Service (OMS), navigate to the <OMS_HOME>/bin directory and run the desired command. To run EMCTL commands for Management Agent, navigate to the <AGENT_HOME>/bin directory and run the desired command.
Similarly, for Windows systems, to run EMCTL commands for OMS, navigate to the <OMS_HOME>\bin directory and to <AGENT_HOME>\bin directory for Management Agent commands.
Oracle Enterprise Manager components are used to manage a variety of Oracle software products. In most cases, in a production environment, you will want to distribute your database and WebLogic Server instances among multiple hosts to improve performance and availability of your software resources. However, in cases where you must install multiple WebLogic Servers or databases on the same host, consider the following guidelines.
When you start Fusion Middleware Control, the Management Agent, or Database Control, Enterprise Manager immediately begins gathering important monitoring data about the host and its managed targets. Keep this in mind when you develop a process for starting the components on the host.
Specifically, consider staggering the startup process so that each Enterprise Manager process has a chance to start before the next process begins its startup procedure. Using a staggered startup procedure ensures that the processes are not in contention for resources during the CPU-intensive startup phase for each component. However, in the case of a system restart, /etc/init.d/gcstartup script which is registered during the EM deployment ensures that the OMS and the Management Agent are started automatically in a staggered manner.
The following sections describe how to stop and start all the Cloud Control components that are installed by the Oracle Enterprise Manager 12c Cloud Control Console installation procedure.
You can use these procedure to start all the framework components after a system reboot or to shutdown all the components before bringing the system down for system maintenance.
The following procedures are covered under this section:
The following procedure summarizes the steps required to start all the components of the Cloud Control. For example, use this procedure if you have restarted the host computer and all the components of the Cloud Control have been installed on that host.
To start all the Cloud Control components on a host, use the following procedure:
If your Oracle Management Repository resides on the host, change directory to the Oracle Home for the database where you installed the Management Repository and start the database and the Net Listener for the database:
Set the ORACLE_HOME environment variable to the Management Repository database home directory.
Set the ORACLE_SID environment variable to the Management Repository database SID (default is asdb).
Start the Net Listener:
$PROMPT> $ORACLE_HOME/bin/lsnrctl start
Start the Management Repository database instance:
ORACLE_HOME/bin/sqlplus /nolog
SQL> connect SYS as SYSDBA
SQL> startup
SQL> quit
Start the Oracle Management Service:
$PROMPT> OMS_HOME/bin/emctl start oms
Change directory to the home directory for the Oracle Management Agent and start the Management Agent:
$PROMPT> AGENT_HOME/bin/emctl start agent
Note:
Be sure to run theemctl start agent command in the Oracle Management Agent home directory and not in the Management Service home directory.The following procedure summarizes the steps required to stop all the components of the Cloud Control. For example, use this procedure if you have installed all the components of the Cloud Control on the same host you want to shut down or restart the host computer.
To stop all the Cloud Control components on a host, use the following procedure:
Stop the Oracle Management Service:
$PROMPT> $ORACLE_HOME/bin/emctl stop oms -all
Change directory to the home directory for the Oracle Management Agent and stop the Management Agent:
$PROMPT> AGENT_HOME/bin/emctl stop agent
Note:
Be sure to run theemctl stop agent command in the Oracle Management Agent home directory and not in the Oracle Management Service home directory.If your Oracle Management Repository resides on the same host, follow these steps:
Set the ORACLE_HOME environment variable to the Management Repository database home directory.
Set the ORACLE_SID environment variable to the Management Repository database SID (default is asdb).
Stop the database instance:
$PROMPT> ORACLE_HOME/bin/sqlplus /nolog SQL> connect SYS as SYSDBA SQL> shutdown SQL> quit
See Also:
Oracle Database Administrator's Guide for information about starting and stopping an Oracle Database.Stop the Net Listener:
$PROMPT> $ORACLE_HOME/bin/lsnrctl stop
When you start the Management Service, the following services are started:
OPMN process. This is the watchdog for the Apache process. The OPMN process starts the Apache process if it crashes.
Apache processes to start the HTTP server.
Node Manager Java process. This is the watchdog for the Managed Server and Admin Server processes. It restarts the Managed Server and Admin Server processes if they crash.
Admin Server Java process (if the command to start OMS is executed on the first OMS machine). This is the WebLogic Server instance that maintains configuration data for configured Enterprise Manager domain.
Managed Server Java process. This is the Managed WebLogic Server on which Enterprise Manager application is deployed.
(On Windows only) Node Manager service process. This is the Windows service for starting and stopping the Node Manager (equivalent to the Node Manager process on Linux).
(On Windows only) OMS service process. This is the Windows service for starting and stopping the OMS.
BI Publisher Server Java process, if it has been configured on the system. This is the Managed WebLogic Server on which the Oracle BI Publisher application is deployed.
When you install the Oracle Management Service (OMS) or the Management Agent on a Windows system, the installation procedure creates new services in the Services control panel.
The procedure for accessing the Services control panel varies, depending upon the version of Microsoft Windows you are using. For example, on Windows 2000, locate the Services control panel by selecting Settings, then Administrative Tools from the Start menu.
Note:
Theemctl utility is available in the bin subdirectory of the Oracle home where you have installed the OMS or Management Agent; however, Oracle recommends that you use the Services control panel to start and stop OMS or Management Agent on Windows systems.Table 22-1 describes the Windows service that you use to control the OMS and Management Agent.
Table 22-1 Service Installed and Configured When Installing the OMS and Management Agent on Windows
| Component | Service Name Format | Description |
|---|---|---|
OracleManagementServer_EMGC_OMS1_1 |
Use this service to start and stop all components that were installed and configured as part of the Management Service J2EE application. |
|
|
Oracle Management Agent |
Oracle<agent_home>Agent For example: OracleOraHome1Agent |
Use this service to start and stop the Management Agent. |
Use the following command to perform an immediate reevaluation of a metric collection:
emctl control agent runCollection <targetName>:<targetType> <colletionItemName>
where <collectionItemName> is the name of the Collection Item that collects the metric.
Related metrics are typically collected together; collectively a set of metrics collected together is called a Metric Collection. Each Metric Collection has its own name. If you want to reevaluate a metric, you first need to determine the name of the Metric Collection to which it belongs, then the CollectionItem for that Metric Collection.
When you run the command above to reevaluate the metric, all other metrics that are part of the same Metric Collection and Collection Item will also be reevaluated.
Perform the following steps to determine the Metric Collection name and Collection Item name for a metric:
Go to $INSTALL_BASE/ngagent/plugins directory, where $INSTALL_BASE is the root of the installation. The Oracle Home of the Management Agent exists in this directory.
Locate the XML file for the target type. For example, if you are interested in the host metric 'Filesystem Space Available(%)' metric, look for the host.xml file.
In the xml file, look for the metric in which you are interested. The metric that you are familiar with is actually the display name of the metric. The metric name would be preceded by a tag that started with:
<Label NLSID=
For example, in the host.xml file, the metric 'Filesystem Space Available(%)" would have an entry that looks like this:
<Label NLSID="host_filesys_pctAvailable">Filesystem Space Available (%) </Label>
Once you have located the metric in the xml file, you will notice that its entry is part of a bigger entry that starts with:
<Metric NAME=
Take note of the value defined for "Metric NAME". This is the Metric Collection name. For example, for the 'Filesystem Space Available(%)' metric, the entry would look like this:
<Metric NAME="Filesystems"
So for the 'Filesystem Space Available(%)' metric, the Metric Collection name is 'Filesystems'.
The Collection Item name for this Metric Collection needs to be determined next. Go to the $INSTALL_BASE/plugins/<plugin id directory, where $INSTALL_BASE is the Oracle Home of the Management Agent.
In this directory, look for the collection file for the target type. In our example, this would be host.xml.
In cases where a Metric Collection is collected by itself, there would be a single Collection Item of the same name in the collection file. To determine if this is the case for your Metric Collection, look for an entry in the collection file that starts with:
<CollectionItem NAME=
where the value assigned to the CollectionItem NAME matches the Metric NAME in step (4).
For the 'Filesystem Space Available(%)' metric, the entry in the collection file would look like:
<CollectionItem NAME = "Filesystems"
If you find such an entry, then the value assigned to "CollectionItem NAME" is the collection item name that you can use in the emctl command.
Otherwise, this means the Metric Collection is collected with other Metric Collections under a single Collection Item. To find the Collection Item for your Metric Collection, first search for your Metric Collection. It should be preceded by the tag:
<MetricColl NAME=
Once you have located it, look in the file above it for: <CollectionItem NAME=
The value associated with the CollectionItem NAME is the name of the collection item that you should use in the emctl command.
For example if the you want to reevaluate the host metric "Open Ports", using the previous steps, you would do the following:
Go to the $INSTALL_BASE/plugins/<plugin id directory where $INSTALL_BASE is the Oracle Home of the Management Agent. Look for the host.xml file and in that file locate: <Metric NAME="openPorts".
Then go to the $INSTALL_BASE/ngagent/plugins/default_collection directory. Look for the host.xml file and in that file look for <CollectionItem NAME="openPorts".
Failing this, look for <MetricColl NAME="openPorts".
Look above this entry in the file to find the <CollectionItem NAME= string and find <CollectionItem NAME="oracle_security".
The CollectionItem NAME oracle_security is what you would use in the emctl command to reevaluate the Open Ports metric.
To monitor the performance of your database targets, Enterprise Manager connects to your database using a database user name and password. This user name and password combination is referred to as the database monitoring credentials.
Note:
The instructions in this section are specific to the monitoring credentials for a database target, but you can use this procedure for any other target type that requires monitoring credentials. For example, you can use this procedure to specify new monitoring credentials for your Oracle Management Service and Management Repository.When you first add an Oracle9i Database target, or when it is added for you during the installation of the Management Agent, Enterprise Manager uses the DBSNMP database user account and the default password for the DBSNMP account as the monitoring credentials.
When you install Oracle Database 11g, you specify the DBSNMP monitoring password during the database installation procedure.
As a result, if the password for the DBSNMP database user account is changed, you must modify the properties of the database target so that Enterprise Manager can continue to connect to the database and gather configuration and performance data.
Similarly, immediately after you add a new Oracle Database 11g target to the Cloud Control, you may need to configure the target so it recognizes the DBSNMP password that you defined during the database installation. Otherwise, the Database Home page may display no monitoring data and the status of the database may indicate that there is a metric collection error.
Note:
You can modify the Enterprise Manager monitoring credentials by using the Oracle Enterprise Manager 12c Cloud Control Console.Table 22-2 lists the EMCTL commands for OMS.
Table 22-2 EMCTL Commands for OMS
| EMCTL Command | Description |
|---|---|
|
|
Shows the version of the OMS instance. |
|
|
Starts the Fusion Middleware components required to run the OMS application. Specifically, this command starts HTTP Server, the Node Manager, OPMN process, and the managed server on which the Management Service is deployed. In addition, if this command is run on the host that has the Administration Server, then the Administration Server is also started. Similarly, if this command is run on a host that has Oracle BI Publisher configured, then Oracle BI Publisher is also started. Note: Only the Oracle software owner can start or stop the OMS. |
|
|
Starts only the Administration Server of the domain. |
|
|
Starts only the BI Publisher server. |
|
|
Stops the OMS managed server and HTTP server but leaves Node Manager and Administration Server running. Note: The |
|
|
Stops all Enterprise Manager processes including Administration Server, OMS, HTTP Server, Node Manager, Management Server, and Oracle BI Publisher (if it is configured on the host). |
|
and
|
Stops the OMS. The parameter |
|
|
Stops only the BI Publisher server. The parameter |
|
|
Lists the statuses of the OMS and the BI Publisher server. |
|
|
Lists the status of only the BI Publisher server. |
|
|
Lists the OMS details such as:
The |
|
|
Sets the values of the OMS configuration properties. By default, the command Note: From Enterprise Manager 12.1.0.2.0 onwards, you can also view and edit OMS properties from the Cloud Control console as follows:
|
|
|
Displays the values of OMS configuration properties. |
|
|
Displays the value of the specified property.
|
|
|
Sets the value of the specified property. The parameters are explained below:
|
|
|
Sets the values of the properties in the specified file. The parameters are explained below:
|
|
|
Deletes the configured value of the specified property and sets it to the default value.
|
|
|
Displays the properties of all OMSs. Use |
|
|
Displays the values of all the customer visible OMS properties. The parameters are explained below:
|
|
|
Displays the OMS repository details. |
|
|
Configures the OMS to use the specified database as the Management Repository. All the additional parameters mentioned in the command need to be specified. |
|
|
Changes the password of root user (SYSMAN) in the repository database and in the OMS. To change the Enterprise Manager root user (SYSMAN) password:
|
|
|
Configures the password used by OMS for MGMT_VIEW user that is used for report generation. To change the Enterprise Manager MGMT_VIEW user password:
|
|
|
Sets up the SSL configuration for OMS. |
|
|
Generates and saves the emcli tracing performance report.
|
|
|
Generates the performance report for user interface (UI) access. The parameters are explained below:
|
|
|
Configures the startup mode of the OMS. This command cannot be executed on the primary OMS. The three startup modes are as below:
|
|
|
Displays the OMS startup mode of the current OMS. |
|
|
Configures Enterprise Manager (EM) to use Oracle SSO (OSSO) for authentication. To run this command you should have registered the EM site with the OSSO server, as you will need the generated registration file as an input for this command. |
|
|
Updates a new password for the specified datasource. In the command, |
|
|
Changes the password, and optionally the user name used by the Enterprise Manager to access the installed BI Publisher Web Server. The This command is operational only if the BI Publisher is installed. It is not necessary for you to restart any OMS (i.e. EMGC_OMS####, BIP####) for this command. |
|
|
Sets the shared storage for BI Publisher, in preparation of adding an OMS (which will also contain a scaled-out BI Publisher). Adding an OMS automatically adds a BI Publisher server that functions in a High Availability environment. Therefore, the BI Publisher will support both redundancy and scalability. This command is used to set up or move a shared storage location in preparation of running the BI Publisher in a High Availability (HA) environment. The parameter The parameter This command is normally run only once on the system that contains the primary OMS and the primary BI Publisher. |
|
|
Executes the The The |
|
|
Registers the metadata. The |
|
|
Registers a target type when these two commands are executed, one after the other. The parameter |
|
|
Erases the metadata. The |
Table 22-3 lists the EMCTL commands for Management Agents.
Table 22-3 EMCTL Commands for Management Agent
| EMCTL Command | Description |
|---|---|
|
|
Starts the Management Agent. On IBM AIX environment with a large memory configuration where the Management Agent is monitoring a large number of targets, the Agent may not start. To prevent this issue, prior to starting the Management Agent, add the following parameters to the common environment file: LDR_CNTRL="MAXDATA=0x80000000"@NOKRTL AIXTHREAD_SCOPE=S The |
|
|
Stops the Management Agent. |
|
|
Lists the status of Management Agent. If the Management Agent is running, this command displays status information about the Management Agent, including the Agent Home, the process ID, and the time and date of the last successful upload to the Management Repository (). Note: On a Windows system change the directory to the |
|
|
Lists the secure status of the Mangement Agent and the secure mode port on which the Management Agent is running. It also lists the OMS security status and the port. |
|
|
Lists all the running, ready, and scheduled collection threads. |
|
|
Lists the status of the jobs that are running at present on the Management Agent. |
|
|
Lists the detailed status of the specified targets such as target name, target type, and so on. You can also provide a particular metric name in the |
|
|
Lists the names of the metrics whose values are present in the metric cache. |
|
|
Uploads the |
|
Use this command to force an immediate upload of the current management data from the managed host to the Management Service. Use this command instead of waiting until the next scheduled upload of the data. |
|
|
This command can be used to apply the changes after you have manually modified the Note: Oracle does not support manual editing of the |
|
|
|
Recomputes the dynamic properties of a target and displays them. |
|
|
Pings the OMS to check if the Management Agent is able to connect to the OMS. Management Agent will wait for the reverse ping from the OMS so that Management Agent can confirm that the |
|
|
Configures the current time zone as set in the environment. |
|
|
Displays the supported time zone based on the setting in the environment. |
|
|
Configures the console based on the configuration entries mentioned in the file The |
|
|
Lists all the target names and types monitored by the Management Agent, that are present in The |
|
|
Allows you to manually run the collections for a particular metric of a target. For example, |
|
|
Performs an immediate reevaluation of a metric collection Executing this command causes the reevaluated value of the metric to be uploaded into the Management Repository, and possibly trigger alerts if the metric crosses its threshold. To identify the metric name and the collection item name associated with the metric, see Section 22.6. |
|
|
Resets the time zone of the Management Agent. To change the current time zone to a different time zone, stop the Management Agent and then run this command. You can then start the Management Agent. Important: Before you change the Management Agent time zone, first check to see if there are any blackouts that are currently running or scheduled to run on any targets managed by that Management Agent. Refer to Section 5.1.3.1 to know how to check for blackouts. If any blackouts exist, then from the Cloud Control Console, stop all the scheduled and all the currently running blackouts on all targets monitored by that Management Agent. You can then change the Management Agent's time zone and later create new blackouts on the targets as needed. |
|
|
Prints the version of the Management Agent. |
|
|
Generates the dumps for the Management Agent. This command allows you to analyze the memory/CPU issues of the Management Agent. |
|
|
Generates the sudo properties of the Management Agent. |
|
|
Clears the sudo properties. |
|
|
Clears the state directory contents. The files that are located in the |
|
|
Prints the Management Agent home directory. |
|
|
Starts blackout on a target. If the parameter |
|
|
Stops the blackout that was started on a particular target. Only those blackouts that are started by the emctl tool can be stopped using emctl. This command cannot stop the blackouts that are started using the console or em cli utility. |
|
|
Provides the status of the target blackout. The status includes the type of blackout and whether it is a one-time action, or repeating, or a scheduled blackout. This command also specifies whether the blackout has started or stopped. |
|
|
Secures the Management Agent with an OMS. The registration password is essential, as you will be prompted for it if you do not provide it along with the command. The The |
|
|
Un-secures the Management Agent. This command changes the Management Agent's port to a HTTP port. After executing this command the Management Agent will be able to upload to the OMS on HTTP by connecting to OMS's HTTP upload port instead of the HTTPS upload port. |
|
|
Verifies the communication between the OMS and Management Agent by sending |
|
|
Creates and deploys only the Management Agent. The parameters are explained below:
|
|
|
Configures the specified property name and value in the Management Agent configuration file. The flag, |
|
|
Gets the specified properties or a category of properties from the Management Agent configuration files. Currently, this command does not support spaces in the name. The flag, |
|
|
Clears the value of the specified property in the Management Agent configuration file. |
|
|
Verifies that the Management Agent is live. |
This section explains the EMCTL security commands.
The topics covered in this section are:
Table 22-6 lists the general EMCTL security commands.
Table 22-4 EMCTL Secure Commands
| EMCTL Command | Description |
|---|---|
|
|
Sets up the SSL configuration for the HTTPS console port of the OMS. |
|
|
Locks the OMS upload and console, thereby avoiding HTTP access to the OMS. The The The |
|
|
Unlocks the OMS upload and console thereby allowing HTTP access to the OMS. The The The |
|
|
Creates a new Certificate Authority (CA) which is used to issue certificates during subsequent securing of OMS and Management Agents. |
|
|
Adds a new Management Agent registration password. |
|
|
Verifies if the Management Repository is up. |
|
|
Re-creates the Administrator Credentials wallet. |
|
|
The |
|
|
The |
The parameter descriptions for the above commands are explained below.
-host: Indicates the Software Load Balancer (SLB) or virtual host name.
-ms_hostname: Indicates the actual host name of the machine where the OMS is running.
-slb_port: Indicates the HTTPS port configured on SLB for uploads.
-slb_console_port: Indicates the HTTPS port configured on SLB for console access.
-no_slb: Removes the SLB configuration.
-secure_port : Specifies the HTTPS upload port change on WebTier.
-upload_http_port: Specifies the HTTP upload port change on WebTier.
-reset: Creates new CA.
-force_newca: Forces OMS to secure with the new CA, even when there are Management Agents secured with the older CA.
-console: Creates a certificate for console HTTPS port as well.
-lock_upload: Locks upload.
-lock_console: Locks console.
-unlock_upload: Unlocks upload.
-unlock_console: Unlocks console.
-wallet: Indicates the directory where the external wallet is located.
-trust_certs_loc: Indicates the file containing all the trusted certificates.
-key_strength: 512|1024|2048
-sign_alg: Signature Algorithm; md5|sha1|sha256|sha384|sha512.
-cert_validity: Indicates the number of days the certificate should be valid. The minimum value is 1 and the maximum value is 3650.
-protocol: Indicates the SSL protocol to be used on WebTier. The valid values for <protocol> are the allowed values for Apache's SSL protocol directive.
-jks_loc: Indicates the location of JKS containing the custom certificate for administrator and managed servers.
-jks_pvtkey_alias: Indicates the JKS private key alias.
-jks_pwd: Indicates the JKS key store password.
-jks_pvtkey_pwd: Indicates the JKS private key password.
-wallet: Indicates the location of the wallet containing the custom certificate for administrator and managed servers.
-use_demo_cert: Configures the demonstration certificate for administrator and managed servers.
Table 22-5 lists the EMCTL security diagnostic commands.
Table 22-5 EMCTL Security Diagnostic Commands
| EMCTRL Command | Description |
|---|---|
|
|
Diagnoses the connectivity issues to the specified URL. The parameter descriptions are as follows:
|
|
|
Displays the trust certificates stored in the specified repository. |
|
|
Displays the trust certificates present in the specified key store, or wallet, or base64 file. |
Table 22-6 lists the EMCTL EM Key commands.
Table 22-6 EMCTL EM Key Commands
| EMCTL Command | Description |
|---|---|
|
|
Displays the health or status of the |
|
|
Copies the |
|
|
Removes the |
|
|
Copies the |
|
|
Copies the |
|
|
Copies the |
|
|
Copies the |
This section explains the EMCTL commands for configuring authentications.
The commands covered in this section are:
The parameter descriptions for all these commands are as below:
-enable_auto_provisioning: Enables automatic-provisioning in EM, wherein external LDAP users need not be provisioned manually in EM.
-auto_provisioning_minimum_role <min_role>: Automatically provisions only those external users in EM who have the min_role granted to them in LDAP.
-minimum_privilege <min_priv>: Prevents access to EM to users who do not have the min_priv granted to them.
-use_ssl: Indicates the SSL to connect to the LDAP server.
-cert_file <cert>: Indicates the LDAP server certificate to establish trust while connecting to LDAP server over SSL. Specify this option if the LDAP server has the certificate signed by a non-popular (or non-trusted) certificate authority.
Note:
This parameter accepts only a single certificate. Importing certificate chains is not supported. Import the certificate usingkeytool utility before running this command.-trust_cacerts: Establishes trust to the LDAP server's certificate while connecting to the LDAP server. This parameter is typically used if the certificate is signed by a well known certificate authority.
-keystore_pwd <passwd>: Indicates the password for the default DemoTrust.jks keystore (if the default password has changed), or any custom keystore to which the LDAP server's certificate will be imported as a part of validation.
-use_anonymous_bind: Uses anonymous bind to connect to LDAP server.
EMCTL OSSO authentication command configures the Enterprise Manager to use the Oracle Application Server Single Sign-On to register any single sign-on user as an Enterprise Manager administrator. The EMCTL command to configure OSSO authentication is:
emctl config auth sso -ossoconf <conf file loc> -dasurl <DAS URL> [-unsecure] [-sysman_pwd <pwd>] [-domain <domain>] -ldap_host <ldap host> -ldap_port <ldap port> -ldap_principal <ldap principal> [-ldap_credential <ldap credential>] -user_base_dn <user base DN> -group_base_dn <group base DN> [-logout_url <sso logout url>] [-enable_auto_provisioning] [-auto_provisioning_minimum_role <min_role>] [-minimum_privilege <min_priv>] [-use_ssl] [-cert_file <cert>] [-trust_cacerts] [-use_anonymous_bind] [-keystore_pwd <passwd>]
For example, emctl config auth sso -ossoconf $T_WORK/osso.conf -dasurl "http://xxx.oracle.com:11" -sysman_pwd sysman -ldap_host xxx.oracle.com -ldap_port 111 -ldap_principal cn=orcladmin -ldap_credential ackdele1 -user_base_dn "cn=Users,dc=us,dc=oracle,dc=com" -group_base_dn "cn=Groups,dc=us,dc=oracle,dc=com" -logout_url "http://xxx.oracle.com:11/pls/orasso/orasso.wwsso_app_admin.ls_logout?p_done_url=https//xyy.oracle.com:216/em.
Oracle Access Manager authentication is the Oracle Fusion Middleware single sign-on solution. This authentication scheme is used for data centers that have standardized on Oracle Access Manager as the central tool for authentication across all enterprise applications. The EMCTL command to configure OAM authentication is:
emctl config auth oam [-sysman_pwd <pwd>] -oid_host <host> -oid_port <port> -oid_principal <principal> [-oid_credential <credential>] [-use_anonymous_bind] -user_base_dn <dn> -group_base_dn <dn> -oam_host <host< -oam_port <port> [-logout_url <url>] [-is_oam10g] [-user_dn <dn>] [-group_dn <dn>] [-enable_auto_provisioning] [-auto_provisioning_minimum_role <min_role>] [-minimum_privilege <min_priv>] [-use_ssl] [-cert_file <cert>] [-trust_cacerts] [-keystore_pwd <passwd>]
For example, emctl config auth oam -oid_host "xxx.oracle.com" -oid_port "111" -oid_principal "cn=orcladmin" -user_base_dn "cn=users,dc=us,dc=oracle,dc=com" -group_base_dn "cn=groups,dc=us,dc=oracle,dc=com" -oam_host "xxx.oracle.com" -oam_port "555" -oid_credential "eldleco1" -sysman_pwd "sysman" -logout_url http://xxx.oracle.com:23716/oam/server/logout?end_url=https://yyy.oracle.com:5416/em -enable_auto_provisioning -auto_provisioning_minimum_role ”EM_DBA”.
The EMCTL command for configuring OID authentication is as below. For AD, replace the command syntax emctl config auth oid below with emctl config auth ad. All other parameters remain the same.
OID authentication command configures the Oracle Internet Directory as the identity store for all the applications to authenticate it's users against the OID.
Similarly, AD authentication command configures the Microsoft Active Directory as the identity store for all the applications to authenticate it's users against the AD.
emctl config auth oid -ldap_host <ldap host> -ldap_port <ldap port> -ldap_principal <ldap principal> [-ldap_credential <ldap credential>] [-sysman_pwd <pwd>] -user_base_dn <user base DN> -group_base_dn <group base DN> [-user_dn <dn>] [-group_dn <dn>] [-enable_auto_provisioning] [-auto_provisioning_minimum_role <min_role>] [-minimum_privilege <min_priv>] [-use_ssl] [-cert_file <cert>] [-trust_cacerts] [-use_anonymous_bind] [-keystore_pwd <passwd>]
For example, emctl config auth oid -ldap_host "xxx.oracle.com" -ldap_port "111" -ldap_principal "cn=orcladmin" -user_base_dn "cn=users,dc=us,dc=oracle,dc=com" -group_base_dn "cn=groups,dc=us,dc=oracle,dc=com" -ldap_credential "elecmee1" -sysman_pwd "sysman" –use_ssl –cert_file ”/scratch/oidcert.txt”.
The repository authentication command validates the user credentials against the Management Repository for authentication. The EMCTL command to configure the repository authentication is:
emctl config auth repos [-sysman_pwd <pwd>]
Table 22-7 lists the EMCTL HA configuration commands.
Table 22-7 EMCTL HA Configuration Commands
| EMCTL Commands | Description |
|---|---|
|
|
Exports a snapshot of the OMS configuration to the specified directory. It is recommended to save the configuration details in a secure location and to save it every time there is a change in the configuration. These details will be required during a system recovery. The parameter descriptions are as below:
|
|
|
Imports the OMS configuration from the specified backup file. This command is used during a system recovery. The parameter descriptions are as below:
|
|
|
Configures the OMS and repository target. This command is used to change the monitoring Agent for the target and/or the connection string used to monitor this target. The parameter descriptions are as below:
|
|
|
Configures the repository database target. This command is used to change the monitoring Agent for the target and/or the monitoring properties (host name, Oracle Home and connection string used to monitor this target). The parameter descriptions are as below:
|
|
|
Enrolls the OMS on to the specified Administration Server host. This command is used in the process of recovering an OMS in a multi-OMS environment. The parameter descriptions are as below:
|
Table 22-8 lists the EMCTL resync commands.
Table 22-8 EMCTL Resync Commands
| EMCTL Commands | Description |
|---|---|
|
|
Submits a repository re-synchronization operation. When the The Note: To use this command shut down the OMSes first and then submit the |
|
|
Aborts the currently running repository re-synchronization operation. The |
|
|
Lists the status of the given repository re-synchronization operation. |
The EMCTL command to add and register a custom template on Enterprise Manager is:
emctl register_template connector [-t <template.xml>] [-repos_pwd <repos password>] [-cname <connectorName>] [-iname <internalName>] [-tname <templateName>] [-ttype <templateType>] [-d <description>]
The parameter descriptions are as below:
-t: Indicates the full path of the template.
-repos_pwd: Indicates the Enterprise Manager root (SYSMAN) password.
-cname: Indicates the connector name.
-iname: Indicates the internal name of the template.
-tname: Indicates the displayed template name.
-ttype: Indicates the template type. The different template types are:
<templateType> 1: inbound transformation
<templateType> 2: outbound transformation
<templateType> 3: xml based outbound transformation
-d: Indicates the description.
Table 22-9 lists the EMCTL patch repository commands.
Table 22-9 EMCTL Patch Repository Commands
| EMCTL Commands | Description |
|---|---|
|
|
Loads the |
|
|
Recalls the |
The emctl create service command creates a service for the OMS on Windows. Use this command to manage the Windows service for the OMS on a failover host in a Cold Failover Cluster setup. This command is applicable only on Windows NT. The syntax of the command is:
emctl create service [-oms_svc_name <oms_service_name> -user <username>] [-passwd <password>]
The parameter descriptions are as below:
-oms_svc_name <servicename>: Indicates the name of the OMS service to be created. If a name is not specified, the system uses the service names in the EM properties file.
-user <username>: Indicates the OS user name to register the service with. If the user name is not specified, the system registers it as LocalSystem.
-passwd <password>: OS password for the OS user specified.
The emctl delete service command deletes the service for the OMS on Windows. This command is applicable only on Windows NT. The command syntax is as below, where, -oms_svc_name <servicename> indicates the name of OMS service to be deleted.
emctl delete service [-oms_svc_name <oms_service_name>]
The emctl partool utility helps you:
Export deployment procedures, and its associated components and directives as par files
Import par files to the same instance or any other instance of Cloud Control
The different flavors of the emctl partool command are listed below:
emctl partool <deploy|view> -parFile <file> -force(optional)
emctl partool <deploy|view> -parFile <file> -force(optional) -ssPasswd <password>
emctl partool <deploy|view> -parDir <dir> -force(optional)
emctl partool export -guid <procedure guid> -file <file> -displayName <name> -description <desc> -metadataOnly(optional)
emctl partool check
emctl partool help
Table 22-10 lists the EMCTL partool command options.
Table 22-10 EMCTL Partool Command Options
| EMCTL Command Option | Description |
|---|---|
|
|
Deploys, displays, or exports the |
|
|
Indicates the repository password. |
|
|
Forces the |
|
|
Checks if the software library is configured. |
|
f |
Indicates the |
|
|
Indicates the |
|
|
Displays the help message. |
|
|
Indicates the |
|
|
Indicates the directory where the |
|
|
Filters for metadata-only exports. |
|
|
Indicates the procedure |
|
|
Indicates the path of the |
|
|
Indicates the |
|
|
This parameter is optional. This parameter creates an Oracle Wallet with the specified password to store the value of the secret property in the exported software library entity. The user must use the same password while importing the |
Note:
For more information onemctl partool command see the topic Using emctl partool Utility in the Oracle Enterprise Manager Lifecycle Management Administrator's Guide.The EMCTL plug-in command is used to resume a previous plug-in upgrade session that had failed. If the previous failure had occurred in a schema manager session, then the execution will be resumed from failed PL/SQL block. The command syntax is:
emctl resume_plugin_upgrade
Note:
To know the status of the plug-in deployments run the commandemctl status oms -details [-sysman_pwd <pwd>].The EMCTL command to sync roles and users between the EM repository and the OPSS policy store is:
emctl sync_opss_policy_store [-force]
Note:
If-force parameter is specified, it removes the OPSS application roles and role memberships that are not present in the EM.This section contains the following:
Table 22-11 lists the commands used to administer JVMD Engines.
Table 22-11 EMCTL Commands for JVMD Engines
| Command | Purpose |
|---|---|
|
|
Lists all the JVMD Engines. |
|
|
Starts specified JVMD Engines. Accepts the engine names as a comma separated list. |
|
|
Starts all JVMD Engines. |
|
|
Stops specified JVMD Engines. Accepts the engine names as a comma separated list. |
|
|
Stops all JVMD Engines. |
|
|
Displays the status of specified JVMD Engines. Accepts the engine names as a comma separated list. |
|
|
Displays the status of all JVMD Engines. |
|
|
Displays the list of available commands for the JVMD verb. |
Table 22-12 lists the commands used to administer ADP Engines.
Table 22-12 EMCTL Commands for ADP Engines
| Command | Purpose |
|---|---|
|
|
Lists all ADP Engines. |
|
|
Starts specified ADP Engines. Accepts the engine names as a comma separated list. |
|
|
Starts all ADP Engines. |
|
|
Stops specified ADP Engines. Accepts the engine names as a comma separated list. |
|
|
Stops all ADP Engines. |
|
|
Displays the status of specified ADP Engines. Accepts the engine names as a comma separated list. |
|
|
Displays the status of all ADP Engines. |
|
|
Displays the list of available commands for the ADP verb. |
Following are the log files you can check if the Oracle Management Service (OMS) fails to start:
Oracle Management Service Fails to Start
Check the logs located as indicated in Table 22-13. The INSTANCE_HOME mentioned in the table is the OMS instance home and n is the index of the OMS server.
Table 22-13 OMS Log Files Location
| OMS Log File | Log File Location |
|---|---|
|
EMCTL log file |
$INSTANCE_HOME/sysman/log/emctl.log file |
|
Managed Server log files |
$INSTANCE_HOME/user_projects/domains/<DOMAIN_NAME>/servers/EMGC_OMS<n>/logs/EMGC_OMS<n>.log $INSTANCE_HOME/user_projects/domains/<DOMAIN_NAME>/servers/EMGC_OMS<n>/logs/EMGC_OMS<n>.out |
|
OMS log files |
$INSTANCE_HOME/sysman/log/emoms_pbs.log $INSTANCE_HOME/sysman/log/emoms_pbs.trc $INSTANCE_HOME/sysman/log/emoms.trc $INSTANCE_HOME/sysman/log/emoms.log |
|
Node Manager log files |
$INSTANCE_HOME/NodeManager/emnodemanager/nodemanager.log |
WebTier Service Fails to Start
Check logs under <WebTier Instance Home>/diagnostics folder in case WebTier start fails.
If the agent fails to start, see the emctl.log and emagent.nohup log files for details. The log files are saved in the $AGENT_INSTANCE_HOME/sysman/logs directory. Following are common issues and troubleshooting suggestions:
Management Agent fails to start due to time zone mismatch between agent and OMS
Management Agent fails to start due to possible port conflict
Management Agent fails to start due to failure of securing or unsecuring
The Management Agent goes through the following process when it starts up:
Starting up (the Management Agent has just received the request to start up and is going to start the initialization sequence)
Initializing (the Management Agent is iterating over each of its components and is initializing them)
Ready (All components have been initialized and the Management Agent is ready to accept requests)
The command to start the Management Agent (emctl start agent) has a default timeout of 120 seconds. At the end of that timeout, it will return control to the caller and will indicate what the last state of the Management Agent was when it returns control. Depending on the number of targets being monitored by the Management Agent, step 2 listed above could take a long time and it is possible that when the command exits, the state of the agent is "Initializing" and the command reports that the "agent is running but is not ready".
You can increase the timeout by setting an environment variable "EMAGENT_TIME_FOR_START_STOP". The value should indicate the number of seconds to wait before returning control to the caller.
The Management Agent uses the time zone set in emd.properties file. During the install process of the Management Agent, the agent and the host target are registered with the OMS along with the time zone. If the Management Agent's time zone is modified at any point after the installation, the OMS will signal the Management Agent to shut down as soon as it detects this mismatch.
To reset the Management Agent's time zone, run the following command:
emctl resetTZ agent
For more information about setting the time zone for the agent, see the description of the emctl resetTZ agent command in the Table 22-3.
If the Management Agent cannot start and EMCTL reports that there is a possible port conflict, check the Management Agent's port (based on emd.properties:EMD_URL) and see if there is another application, such as another agent, running on the machine that is already bound to the port.
To resolve this issue, stop the application currently bound to the Management Agent's port.
Securing or unsecuring of the Management Agent can fail if the password to secure the agent against the OMS is incorrect or if the OMS is locked or down. You can find the reason for the failure in the <agent state directory>/sysman/log/secure.log file.
The emctl.log file is a file that captures the results of all EMCTL commands you run. For Management Agent, the log file resides in the $AGENT_INSTANCE_HOME/sysman/log directory of the Management Agent, and for OMS, the log file resides in the $OMS_INSTANCE_HOME/em/EMGC_OMS<n>/sysman/log/ directory. The file is updated every time you run an EMCTL command. If your EMCTL command fails for some reason, access this log file to diagnose the issue.
For example, run the following command from the Oracle home directory of the Management Agent to check its status:
For Unix:
<agent_instance_home>/bin/emctl status agent
For Windows:
<agent_instance_home>\bin\emctl status agent
After running the command, navigate to the log directory to view the following information in the emctl.log file:
1114306 :: Wed Jun 10 02:29:36 2011::AgentLifeCycle.pm: Processing status agent 1114306 :: Wed Jun 10 02:29:36 2011::AgentStatus.pm:Processing status agent 1114306 :: Wed Jun 10 02:29:37 2011::AgentStatus.pm:emdctl status returned 3
Here, the first column, that is, 1114306, is the PID that was used to check the status. The second column shows the date and time when the command was run. The third column mentions the Perl script that was run for the command. The last column describes the result of the command, where it shows the progress made by the command and the exit code returned for the command. In this case, the exit code is 3, which means that the Management Agent is up and running.
Similarly, for the OMS, you can run the following command from the Oracle home directory of the Management Service to check its status:
For Unix:
<OMS_HOME>/bin/emctl status oms
For Windows:
<OMS_HOME>\bin\emctl status oms
Example 22-1 Sample Log Content for OMS
2013-06-23 22:50:25,686 [main] INFO wls.OMSController main.219 - Executing emctl command : status 2013-06-23 22:50:26,281 [main] INFO commands.BaseCommand printMessage.404 - statusOMS finished with result: 0 2013-06-23 22:50:35,885 [main] INFO wls.OMSController main.219 - Executing emctl command : status 2013-06-23 22:50:36,464 [main] INFO commands.BaseCommand printMessage.404 - statusOMS finished with result: 0
In another example, run the following command from the Oracle home directory of the Management Agent to upload data:
For Unix:
<Agent_Instance_Home>/bin/emctl upload agent
For Windows:
<Agent_Instance_Home>\bin\emctl upload agent
After running the command, navigate to the log directory to view the following information in the emctl.log file:
1286220 :: Tue Jun 9 07:13:09 2011::AgentStatus.pm:Processing upload 1286220 :: Tue Jun 9 07:13:10 2011::AgentStatus.pm:emdctl status agent returned 3 1286220 :: Tue Jun 9 07:13:41 2011::AgentStatus.pm: emdctl upload returned with exit code 6
Here, the entries are similar to the entries in the first example, but the exit code returned is 6, which means the upload operation is failing for some reason.
The exit codes returned depend on the emctl command executed. In general, exit code of zero means success and any exit code other than zero means failure. For details about the cause of failure, view the error message.