4 opmnctl Commands

This chapter provides an overview of opmnctl commands for Oracle Fusion Middleware components managed by OPMN. It features the following topics:

• opmnctl

• opmnctl Command Quick Reference

• opmnctl Detailed Command Description

4.1 opmnctl

opmnctl is the supported tool for starting and stopping all components in an Oracle instance, with the exception of the Fusion Middleware Control Console. opmnctl provides a centralized way to control and monitor system components from the command line.

If OPMN is configured to discover other Oracle instances, you can use opmnctl to execute control and monitoring commands across multiple Oracle instances simultaneously.

The location of the opmnctl script determines which opmnctl commands you can use.

The opmnctl command exists in two distinct directory location paths:

• ORACLE_HOME/opmn/bin/opmnctl: The opmnctl command ORACLE_HOME/opmn/bin/opmnctl location can only be used to create an Oracle instance or a component for an Oracle instance on the local system. opmnctl commands generated from this location cannot be used to manage system processes

• ORACLE_INSTANCE/bin/opmnctl: The other opmnctl command which is located in the ORACLE_INSTANCE/bin/ directory location provides a per Oracle instance instantiation of opmnctl. The opmnctl command in this location must be used for managing processes for this Oracle instance and can also be used for creating components for the Oracle instance.

Note:

Oracle Fusion Middleware components managed by OPMN should never be started or stopped manually. Do not use command line scripts or utilities from previous versions of Oracle Fusion Middleware for starting and stopping system components. Use the Fusion Middleware Control Console and the opmnctl command line utility to start or stop system components.

Note:

Oracle recommends starting OPMN as the user that has installed Oracle Fusion Middleware.

4.1.1 opmnctl Syntax

The following command shows an example of the syntax of the opmnctl command:

opmnctl [verbose] <command> [<options>]

Table 4-1 provides a description about opmnctl syntax.

Table 4-1 opmnctl Syntax

Syntax	Description
verbose	Prints detailed execution message, if available.
command	Specifies an opmnctl command. Refer to Example 4-1 for a list of commands.
options	Specifies options for the command. Refer to Section 4.3.5.1.1 for a list of command options.

4.2 opmnctl Command Quick Reference

Example 4-1 lists opmnctl commands for quick reference. You can obtain the same output information by executing the opmnctl help command.

Example 4-1 opmnctl Commands

opmnctl help

usage: opmnctl [verbose] [<scope>] <command> [<options>]

verbose: print detailed execution message if available

Permitted <scope>/<command>/<options> combinations are:

scope     command    options
-------  ---------   ---------
          start                         - Start opmn
          startall                      - Start opmn & all managed processes
          stopall                       - Stop opmn & all managed processes
          shutdown                      - Shutdown opmn & all managed processes
[<scope>] startproc   [<attr>=<val> ..] - Start opmn managed processes
[<scope>] restartproc [<attr>=<val> ..] - Restart opmn managed processes
[<scope>] stopproc    [<attr>=<val> ..] - Stop opmn managed processes
[<scope>] reload                        - Trigger opmn to reread opmn.xml
[<scope>] status      [<options>]       - Get managed process status
[<scope>] metric      [<attr>=<val> ..] - Get DMS metrics for managed processes
[<scope>] dmsdump     [<dmsargs>]       - Get DMS metrics for opmn
[<scope>] debug       [<attr>=<val> ..] - Display opmn server debug information
[<scope>] set         [<attr>=<val> ..] - Set opmn log parameters
[<scope>] query       [<attr>=<val>]    - Query opmn log parameters
          launch      [<attr>=<val> ..] - Launch a configured target process
          phantom     [<attr>=<val> ..] - Register phantom processes
          ping        [<max-retry>]     - Ping local opmn
          validate    [<filename>]      - Validate the given opmn xml file
          help                          - Print brief usage description
          usage       [<command>]       - Print detailed usage description
          createinstance                - Create an Oracle Instance
          createcomponent               - Create a specified component
          deleteinstance                - Delete an instance and components
          deletecomponent               - Delete a specified component
          registerinstance              - Register with admin server
          unregisterinstance            - Unregister with admin server
          updateinstanceregistration    - Update instance registration
          updatecomponentregistration   - Update component registration

4.3 opmnctl Detailed Command Description

The following sections contains detailed descriptions of the opmnctl commands listed in Example 4-1. The opmnctl commands are displayed in the following sections:

• Command Definitions

• Server Control Commands

• Process Control Commands

• Provisioning Commands

• Status Commands

• Help Commands

4.3.1 Command Definitions

opmnctl features command definitions that enable you to further define the action you would like to execute with OPMN.

This section describes the command definitions available with the opmnctl command. It includes the following sections:

• Scope

• Attributes

• Verbose

4.3.1.1 Scope

The scope option specifies which Oracle instance the opmnctl command applies to. Unlike prior releases of Oracle Fusion Middleware, the force option in this release is not used and kept here for backward compatibility.

4.3.1.2 Attributes

syntax: <attribute>=<value>

The opmnctl attributes enable you to apply process control operations to specific system components.

For example, the following command starts all system processes configured for Oracle Web Cache:

opmnctl startproc ias-component=webcache1

Refer to Chapter 5 for additional opmnctl command examples.

Table 4-2 lists the attribute names and values that can be used with the opmnctl command:

Table 4-2 opmnctl Attribute Names and Values

Attribute Name	Attribute Values
ias-instance	Value should be the same as the value for the id attribute for the <ias-instance> element in the opmn.xml file.
ias-component	Value should be the same as the value for the id attribute for the <ias-component> element in the opmn.xml file.
process-type	Value should be the same as the value for the id attribute for the <process-type> element in the opmn.xml file.
process-set	Value should be the same as the value for the id attribute for the <process-set> element in the opmn.xml file.
mode	Value can either be sync or async. The default value is "sync, meaning that this request operates synchronously, and waits for the operation to complete before returning. "async indicates that the request returns immediately, while OPMN continues to perform the request until the operation finishes.
timeout	This can only be specified in sync mode. The value is in seconds. After this timeout expires, OPMN does not continue to perform the request for startproc operations. The request does continue for restartproc and stopproc operations. The timeout attribute overrides the configured timeout value for the request to take for each ias-instance, ias-component, process-type, and process-set value.
uniqueid	This value is assigned by OPMN after starting up. You can use this value when you execute the opmnctl restartproc and opmnctl stopproc commands.
sequential	If the value of the sequential attribute is true, each process or application targeted by the request is acted upon sequentially (one at a time). The request order of affected managed-process dependencies is honored.
report	If the value of the report attribute is true, OPMN reports the results of each part of the request as it completes (as each process starts, for example). The default behavior is for OPMN to wait until the entire request has completed before sending all of the results at once.

The target attributes of ias-instance, ias-component, process-type, and process-set may be specified in a hierarchical manner, with an ias-instance, a single ias-component within that ias-instance, a single process-type within the ias-component, and a single process-set within the process-type. Any of these attributes may be omitted, and treated as a wildcard (process-set is omitted, for example, then all process-sets under the specified process-type matches the request).

The target attributes may also be specified in a list of a single hierarchical type (a list of ias-components, for example).

Note:

If Oracle Internet Directory is managed by OPMN and an Oracle Internet Directory dependency (not a managed-process dependency for Oracle Internet Directory) is encountered as part of the request, and the request is expected to start both Oracle Internet Directory processes (such as an opmnctl startall request), the Oracle Internet Directory process will not start unless it has been configured in the opmn.xml file previously. Otherwise, the request times out with an Oracle Internet Directory dependency failure.

See Also:

Chapter 5 for OPMN command-line examples

4.3.1.3 Verbose

Syntax: opmnctl verbose command

The opmnctl verbose option enables you to obtain detailed information about the command you are executing.

For example, the following command outputs the information shown in Example 4-2:

prompt> opmnctl verbose startproc ias-component=ohs1

Example 4-2 opmnctl verbose output

opmnctl startproc: starting opmn managed processes... 

HTTP/1.1 200 OK
Content-Length: 661
Content-Type: text/html
Response: 1 of 1 processes started.

<?xml version='1.0' encoding='WINDOWS-1252'?>
<response>
<opmn id="stapk08:6704" http-status="200" http-response="1 of 1 processes
 started.">
  <ias-instance id="instance1">
    <ias-component id="ohs1">
      <process-type id="OHS">
         <process-set id="OHS">
            <process id="1792746301" pid="5106" status="Alive" index="1"
             log="/scratch/lbottlem/product/11.1.1/as
             1/instances/instance1/diagnostics/logs/OHS/ohs1/console~OHS~1.log"
             operation="request" result="success">
            <msg code="0" text="">
          </msg>
         </process>
        </process-set>
       </process-type>
      </ias-component>
    </ias-instance>
   </opmn>
 </response>

4.3.2 Server Control Commands

The opmnctl start, startall, reload, stopall, and shutdown commands enable you to control the OPMN server.

• Server Control Commands on Microsoft Windows

• opmnctl start

• opmnctl startall

• opmnctl stopall

• opmnctl shutdown

• opmnctl reload

Output is not generated for the successful execution of an opmnctl server control command. Refer to Appendix B if you receive any error messages during opmnctl command execution.

4.3.2.1 Server Control Commands on Microsoft Windows

On the Microsoft Windows operating system, OPMN is installed as a Windows service (Oracle<OracleHomename>ProcessManager) and it starts up automatically when you restart your computer. When you start or stop OPMN using Microsoft Windows Services you start or stop all system components on the local Oracle instance.

Use the Fusion Middleware Control Console and the opmnctl command line utility to start or stop system components.

4.3.2.2 opmnctl start

Syntax: opmnctl start

Use this command to start the OPMN server for a local Oracle instance without starting system processes.

Note:

OPMN starts up automatically on Microsoft Windows when you start or restart your computer. All system component processes are also started.

See Also:

Chapter 5 for OPMN command-line examples

4.3.2.3 opmnctl startall

Syntax: opmnctl startall [timeout=<seconds>]

Use this command to start OPMN as well as the system processes for a local Oracle instance. The startall is equivalent to the start command and the startproc command without arguments. Oracle recommends using the start or startproc command.

This command operates synchronously and waits for the operation to complete before returning. To set a timeout for the request, specify the timeout value in seconds.

Components with id-matching="true" will not start.

Enter the following command for additional detailed information:

opmnctl usage startall

On Microsoft Windows, you can also perform an opmnctl startall by starting the Oracle<OracleHomename>ProcessManager service in the Windows services control panel. The Oracle<OracleHomename>ProcessManager starts automatically when you start or restart your computer.

4.3.2.4 opmnctl stopall

Syntax: opmnctl stopall

Use the opmnctl stopall command to shut down the OPMN server as well as the system processes for the local Oracle instance. This request operates synchronously; it waits for the operation to complete before returning.

Shutting down the OPMN server is not necessary during normal operation. Shutting down the OPMN server prevents remote commands to OPMN from executing on the Oracle instance until OPMN is restarted.

The opmnctl stopall command should only be executed prior to shutting down OPMN and your computer. This request first tries to stop all system components gracefully. Processes which will not stop gracefully is forcefully shutdown. After stopping all managed processes, the OPMN daemon shutdowns itself.

The opmnctl stopall command should only be used when it is necessary to stop the OPMN daemon quickly in case of an emergency. Once started, the OPMN daemon should remain up until it is necessary to restart the computer or some other unforeseen administrative event occurs.To stop all system components without stopping the OPMN daemon, consider using the opmnctl stopproc command without any arguments.To restart the OPMN daemon without restarting any system components, consider using the opmnctl reload command. The opmnctl reload command is the appropriate command to use when the only goal is to restart the opmn daemon with a new configuration.

Use the opmnctl stopproc command if you want to stop all system processes.

Use the opmnctl reload if you want OPMN to reread its configuration.

Enter one of the following commands to obtain additional information:

opmnctl usage stopall

or

opmnctl usage shutdown

4.3.2.5 opmnctl shutdown

Syntax: opmnctl shutdown

Use the opmnctl shutdown command to shut down the OPMN server as well as the system processes for the local Oracle instance.

The opmnctl shutdown command quickly shutdowns the OPMN daemon and system components for the local Oracle instance.The opmnctl shutdown command is similar to the opmnctl stopall command but waits less time before initiating a forceful termination of system components. After all of the system components are stopped, the OPMN daemon shutdowns itself.

The opmnctl shutdown command should only be performed when it is necessary to stop the OPMN daemon. Once started, the OPMN daemon should remain up until it is necessary to restart the computer or some other unforeseen administrative event occurs.To stop all system components without stopping the OPMN daemon, consider using the opmnctl stopproc command without any arguments.To restart the OPMN daemon without restarting any system components, consider using the opmnctl reload command. The opmnctl reload command is the appropriate command to use when the objective is to restart the OPMN daemon with a new configuration.

On Microsoft Windows, you can also perform an opmnctl shutdown by stopping the Oracle<OracleHomename>ProcessManager service in the Windows services control panel.

Use the opmnctl stopproc command if you want to stop all system component processes.

Use the opmnctl reload if you want OPMN to reread its configuration.

Enter one of the following commands to obtain additional information:

opmnctl usage stopall

or

opmnctl usage shutdown

4.3.2.6 opmnctl reload

Syntax: opmnctl reload

Use this command to trigger the OPMN to reread its configuration files. This command restarts the OPMN server without restarting any system processes managed by OPMN. The OPMN server for the Oracle instance must be up and running.

Note:

On Microsoft Windows, you can highlight the Oracle<OracleHomename>ProcessManager in the services control panel and select Restart. The restart of the service is not equivalent to an opmnctl reload, however. This action is equivalent to an opmnctl shutdown followed by an opmnctl startall. It is a much slower operation than opmnctl reload because it restarts OPMN and all the processes managed by OPMN.

Enter the following command for additional detailed information:

opmnctl usage reload

See Also:

Section 4.3.1 for OPMN command definitions

4.3.3 Process Control Commands

The opmnctl process control commands enable you to start, stop, or restart single or multiple system components. You can control a system component at the <ias-component>, <process-set>, or <process-type> level.

This section describes the process control commands available with opmnctl. It includes the following process control commands:

• opmnctl startproc, opmnctl restartproc and opmnctl stopproc

• Progressive Request Reports

• Sequential Requests

Output is not generated for the successful execution of an opmnctl process control command. Refer to Appendix B if you receive any error messages during opmnctl command execution.

4.3.3.1 opmnctl startproc, opmnctl restartproc and opmnctl stopproc

Syntax: opmnctl startproc [<attr>=<value>...]

              opmnctl restartproc [<attr>=<value>...]

              opmnctl stopproc [<attr>=<value>...]

Use these commands to start, restart, or stop system processes. The OPMN server for the Oracle instance must be up and running.

You can use attributes for these commands. If no attribute is supplied when executing startproc, stopproc, and restartproc, all system processes except components with id-matching="true" in the opmn.xml file is started.

The following attributes and values can be used with the startproc, stopproc, and restartproc commands:

• ias-component, process-type, and process-set: The values for these attributes should be the same as the id value specified in the opmn.xml file. If no attribute is supplied, the command is applied to all system component processes other than those that are configured in the opmn.xml file with id-matching="true". To execute commands on components configured with id-matching="true", it is necessary to specify the ias-component argument.

• mode: The mode attribute value can be either sync or async; the default value is sync. The sync value for mode causes the opmnctl command to operate synchronously and wait for the command to be executed completely before a return prompt is displayed. The timeout element can only be specified when the value of mode is sync. The value is specified in number of seconds. After the specified timeout expires, the operation is aborted for startproc but not for restartproc or stopproc. The opmnctl command prompt returns, the OPMN server continues to perform the opmnctl restartproc or stopproc command request until the operation is finished.

  The async value for mode causes the return prompt to be displayed immediately, while the OPMN server continues to perform the opmnctl command request until the operation is finished.

• uniqueid: This value is assigned by OPMN after starting up. You can use this value when you execute the restartproc and stopproc commands. You can obtain this value by entering the following command and obtaining the unique number for the system component in the uid column of the generated output:

  opmnctl status -l
  

Attribute names other than those listed may be specified for some types of system processes managed by OPMN. Unique attribute name should be specific to each type of system process.

Using the opmnctl startproc, restartproc, or stopproc commands and attributes enables control of specific processes in your Oracle instance. You can execute the opmnctl startproc, restartproc, or stopproc commands at the <ias-component>, <process-type> and the <process-set> level.

The following command restarts Oracle Web Cache at the <process-type> level:

opmnctl restartproc ias-component=webcache1 process-type=WebCache

The following command stops Oracle HTTP Server at the <ias-component> level:

opmnctl stopproc ias-component=ohs1

Enter one of the following commands to obtain additional information:

opmnctl usage startproc

or

opmnctl usage restartproc

or

opmnctl usage stopproc

See Also:

• Section 4.3.1 for OPMN command definitions

• Chapter 5 for OPMN command-line examples

4.3.3.2 Progressive Request Reports

The report=true attribute when used with startproc, restartproc, or stopproc enables OPMN to report back on each part of a request as it completes. For example, if an opmnctl startproc request attempts to start 4 processes, OPMN reports back to the user the result of each process start attempt as soon as it completes.

4.3.3.3 Sequential Requests

By default an OPMN request is run for all affected processes at the same time, unless a dependency dictates a specific ordering. If the attribute sequential=true is specified when used with the startproc, restartproc, or stopproc command, then OPMN runs the request on a single process at a time, waiting for the request to complete on the first before running the request on the second. When the request has finished on one process, it works on the next.

Note that dependencies are still honoured, and take part in the request sequentially as well.

As shown in Figure 4-1, by default OPMN issues jobs for all processes in parallel such that they run at the same time (except when honoring dependencies). For example, with the following command:

> opmnctl startproc 

Figure 4-1 Processes in Parallel

Description of "Figure 4-1 Processes in Parallel"

If the sequential attribute is set to true, OPMN performs the request upon one process at a time (shown in Figure 4-2).

For example the following command:

% opmnctl startproc sequential=true

starts all of the managed system processes sequentially.

Figure 4-2 Managed Process Sequential Request #1

Description of "Figure 4-2 Managed Process Sequential Request #1"

OPMN is processing one managed process, before moving on the next shown in Figure 4-3.

As shown in Figure 4-3, when the request completes for the first managed process, the request starts on the next managed process.

Figure 4-3 Managed Process Sequential Request #2

Description of "Figure 4-3 Managed Process Sequential Request #2"

As shown in Figure 4-4, all affected managed processes have completed the request.

Figure 4-4 Managed Process Sequential Request #3

Description of "Figure 4-4 Managed Process Sequential Request #3"

4.3.4 Provisioning Commands

The opmnctl provisioning commands are used for provisioning system components within an Oracle instance. Use these commands to:

• Create and delete an Oracle instance or system component.

• Register and unregister an Oracle instance with a WebLogic domain for management using the Fusion Middleware Control Console.

• Update an Oracle instance or system component registration with the WebLogic domain.

Note:

The opmnctl provisioning commands must use the following naming conventions:

1. Name must begin with a letter and contain only alphanumerics, hyphen(-) and underscore(_) characters.

2. Name must be no more than 30 characters long.

3. Name must be at least 4 characters long.

This section includes the following topics:

• General Syntax

• Alternative Syntax for Provisioning Commands

• Common Arguments

• Commands

4.3.4.1 General Syntax

opmnctl provisioning commands are invoked using the following syntax:

opmnctl  command  [-argName1  value1]  [-argName2  value2]  ...

The following provisioning commands are supported:

• createinstance

• createcomponent

• deleteinstance

• deletecomponent

• registerinstance

• unregisterinstance

• updateinstanceregistration

• updatecomponentregistration

4.3.4.2 Alternative Syntax for Provisioning Commands

Provisioning commands can also be invoked with the syntax used by other opmnctl commands:

opmnctl command [argName1=value1] [argName2=value2] ...

This alternate syntax follows the Attributes style (refer to Section 4.3.1.2) and accepts argument names presented in lower case. The alternate syntax is provided to allow greater uniformity between opmnctl commands.

Any opmnctl provisioning commands can be entered using either syntax.

For example, the following commands are equivalent:

opmnctl createcomponent -componentType OHS -componentName ohs1
opmnctl createcomponent componenttype=OHS componentname=ohs1

Both syntax styles can be combined within the same command.

4.3.4.3 Common Arguments

The following arguments generally apply to all provisioning commands, with the exception with component specific arguments that apply only to component-related commands:

• Adminserver Arguments

• Logging Arguments

• Oracle Instance Arguments

• Component Specific Arguments

4.3.4.3.1 Adminserver Arguments

administrative server (Adminserver) arguments denote how opmnctl should contact the Adminserver of the Oracle WebLogic Server domain.

The Adminserver values are stored in the Oracle instance as defaults for subsequent commands. opmnctl does not use or require the Adminserver values for a non-registered Oracle instance. See Section 4.3.4.4.1 about the createinstance command for creating a non-registered instance.

The Adminserver arguments are:

• -adminHost : the Weblogic Adminserver host. The default value is the last successful command for the Oracle instance or local host.

• -adminPort: the Weblogic Adminserver port. The default value is the last successful command for the Oracle instance; or 7001.

• -adminProtocol: Weblogic Adminserver protocol. The default value is the last successful command for the Oracle instance; or t3.

• -adminUsername: the Weblogic Adminserver login user name. The default value is the last successful command for the Oracle instance; otherwise you are prompted to type in their login user name.

• -adminPasswordFile: the location of the file containing the administrative user (admin user) password. The default value is the last successful command for the Oracle instance; otherwise you are prompted to type in your admin user password.

4.3.4.3.2 Logging Arguments

By default, opmnctl logs the detailed provisioning errors and exceptions in the ORACLE_INSTANCE/diagnostics/logs/OPMN/opmn/provision.log file. For certain errors during execution of the createinstance command, specifically when the provision.log file has not been created yet, the detailed exception is indicated on the console. Log file locations can be specified using the -logFile argument.

• -logFile: the location of provisioning log file.

• -logLevel: the logging level of provisioning log. For example, INFO or FINER.

4.3.4.3.3 Oracle Instance Arguments

The -oracleInstance and -instanceName arguments are used primarily for the createinstance command. After the Oracle instance is created, the ORACLE_INSTANCE/bin/opmnctl directory provides a default Oracle instance home. The Oracle instance name is determined automatically.

The Oracle instance arguments are:

• -oracleInstance: the Oracle instance root directory. This directory is only required when the opmnctl command is not executed from the Oracle instance home.

• -instanceName: this command option is used for assigning an Oracle instance name when the Oracle instance is created or to verify the Oracle instance name afterward.

For the createinstance command, if the instanceName is not provided directly, the last directory name of the -oracleInstance is used as the Oracle instance name.

4.3.4.3.4 Component Specific Arguments

Commands that target a single component can accept arguments specific to the component type. For example, the -wcAdminPasswordFile argument is accepted when creating an Oracle Web Cache component but not when creating an OHS component.

These arguments are syntactically optional but must be understood to ensure proper configuration.

For details covering these specific arguments and how they should be used, refer to the Oracle Fusion Middleware Administrator's Guide.

A list of the arguments applicable to a system component can be displayed by including the component type when executing the opmnctl usage command.

For example:

opmnctl usage createcomponent -componentType OHS

4.3.4.4 Commands

This section describes the create series of commands. It includes the following sections:

• createinstance

• createcomponent

• deleteinstance

• deletecomponent

• registerinstance

• unregisterinstance

• updateinstanceregistration

• updatecomponentregistration

4.3.4.4.1 createinstance

The createinstance command creates an Oracle instance and registers It uses the following arguments:

• Adminserver

• Logging

• Oracle Instance

• -adminRegistration: the registration status for the created Oracle instance. Supported values are ON (registered) and OFF (non-registered). The default value is ON.

• -opmnRemoteHost: the OPMN remote host. The default value is the computer canonical host name.

• -opmnLocalPort: the OPMN local port value. The default port value is 6700 if the port is available.

• -opmnRemotePort: the OPMN remote port value. The default port value is 6701 if the port is available.

For example:

opmnctl createinstance -oracleInstance /foo/bar/inst1 -adminHost myadminserver -adminPort 7001

or

opmnctl createinstance -oracleInstance /foo/bar/inst1 -adminRegistration OFF

4.3.4.4.2 createcomponent

The createcomponent command creates a component within an Oracle instance. The created component is consistent with the Oracle instance in regard to its registration state.

The createcomponent command uses the following arguments:

• Adminserver

• Logging

• Oracle Instance

• Component Specific Arguments

• -componentType : the system component type

• -componentName : the system component name

For example:

opmnctl createcomponent -componentType OHS -componentName ohs1 -proxyPort 8888

It is important to note that different system components feature different sets of arguments that are available for configuration. In the above command example, the -proxyPort usage is specific to the OHS component. For more information about component specific arguments refer to Section 4.3.4.3.4.

4.3.4.4.3 deleteinstance

The deleteinstance command deletes an Oracle instance and unregisters the Oracle instance and associated system components. A successful Oracle instance deletion removes all files of the Oracle instance except for the default provision.log file.

For example:

opmnctl deleteinstance

The deleteinstance command uses the following arguments:

• Adminserver

• Logging

• Oracle Instance

• -force: The -force argument forces the opmnctl deleteinstance command to proceed regardless of discrepancies in the Oracle instance. The command is enabled only with a value of true. The default value is false.

  Please note that the -force option circumvents most pre-validation checks. Therefore, Oracle recommends using the -force option with caution. An example is shown in section Force deleteinstance.

Force deleteinstance

The deleteinstance command operates in a forced mode if the option -force true is included in the command. When used, this option directs opmnctl to proceed with the operation regardless of warnings and errors detected for the Oracle instance. Because the Oracle instance may be in a bad or non-responsive state, Oracle recommends explicitly providing non-required values that are associated and appropriate for the Oracle instance (for example, -instanceName, -adminHost, -adminPort) to ensure that the proper values are used.

During the course of cleanup, the forced deleteinstance command displays warnings and exceptions consistent with the damaged state of the Oracle instance. These warnings and exceptions are provided as visual feedback for the inconsistencies encountered and do not necessarily indicate that further corrective action is needed.

For example:

opmnctl deleteinstance -force true -instanceName instance1 -adminHost myadminserver -adminPort 7001

or

opmnctl deleteinstance -force true -instanceName instance1

4.3.4.4.4 deletecomponent

The deletecomponent command deletes a system component.

The deletecomponent command uses the following arguments:

• Adminserver

• Logging

• Oracle Instance

• -componentName: The system component name.

For example:

opmnctl deletecomponent -componentName ohs1

4.3.4.4.5 registerinstance

The registerinstance command switches the Oracle instance to a registered state and updates the Adminserver value.

The registerinstance command uses the following arguments:

• Adminserver

• Logging

• Oracle Instance

For example:

opmnctl registerinstance -adminHost myhostname -adminPort 8000

4.3.4.4.6 unregisterinstance

The unregisterinstance command switches the Oracle instance to a non-registered state and updates the Adminserver value.

For example:

opmnctl unregisterinstance

The unregisterinstance command uses the following arguments:

• Adminserver

• Logging

• Oracle Instance

• -force: directs the opmnctl unregisterinstance command to proceed regardless of discrepancies in the Oracle instance. This option is only enabled with a value of true. The default value is false.

  Please note that the -force option circumvents most pre-validation checks. Therefore, Oracle recommends using the -force option with caution. An example is shown in section Forced unregisterinstance

Forced unregisterinstance

The unregisterinstance command can operate in a forced mode when the option -force true is included.

This option directs opmnctl unregisterinstance to unregister the Oracle instance but limits the scope of these changes exclusively to the Adminserver. In other words, it unregisters an Oracle instance name from the Adminserver without examining or interacting with an Oracle instance (except optionally for writing to the provision.log file).

This mode can readily break registration associations. For example, executing this command with the name of a operational registered Oracle instance would put Adminserver and the Oracle instance out of synchronization. Afterward, the Adminserver no longer lists the Oracle instance or associated system components; however, in this example, the Oracle instance would still be configured as registered and but would fail most provisioning commands. Therefore, Oracle recommends using the -force option with caution.

For example:

opmnctl unregisterinstance -force true -instanceName instance1 -adminHost myadminserver -adminPort 7001

4.3.4.4.7 updateinstanceregistration

The updateinstanceregistration command updates information registered on the Adminserver for the Oracle instance. Specifically, the updateinstanceregistration command updates the registered OPMN remote port, OPMN remote host and OPMN wallet from the current OPMN settings.

The updateinstanceregistration command uses the following arguments:

• Adminserver

• Logging

• Oracle Instance

For example:

opmnctl updateinstanceregistration

4.3.4.4.8 updatecomponentregistration

The updatecomponentregistration command updates settings registered on the Adminserver for the subject system component. These settings include the component proxy port, component proxy wallet, component mbean properties and Fusion Middleware Control Console component properties, plus other values specific to the type of component.

The updatecomponentregistration command uses the following arguments:

• Adminserver

• Logging

• Oracle Instance

• Component Specific Arguments

• -componentName: the system component name

For example:

opmnctl updatecomponentregistration -componentName ohs1 -proxyPort 8889 ....

4.3.5 Status Commands

The opmnctl status commands enable you to determine the status of system component processes.

This section describes the command options available with the opmnctl command. It includes the following sections:

• opmnctl status

• opmnctl metric

• opmnctl dmsdump

• opmnctl ping

• opmnctl set

• opmnctl query

See Also:

• Section 4.3.1.2 for information about attributes

• Section 4.3.5.1.1 for information about the options for the status command of opmnctl

• Section 4.3.5.1.2 for information about the opmnctl status -port command

4.3.5.1 opmnctl status

Syntax: opmnctl status [<options>]

The status command enables you to obtain information on the system processes managed by OPMN.

The output is a text table. Each row in the table represents one system process.

You can customize the status command in the following ways:

• Change the information displayed about each system process

• Remove the table headers from the output

• Change the field separator

• Change the record separator

• Change the width of individual columns

• Change the justification of the data in an individual column

Enter the opmnctl usage status command to obtain full details on how to use the status command.

Example 4-3, "opmctl Status Output" shows the output after entering the opmnctl status command for the AppSrv1 Oracle instance on host comp1 for the domain yourcompany.com:

Example 4-3 opmctl Status Output

opmnctl status

Processes in Instance: Instance1
-------------------------+-----------------+--------+---------
Monitor                  | MONITOR         |   6720 | Alive
webcache1                | WebCache-admin  |    N/A | Down
webcache1                | WebCache        |    N/A | Down
ohs1                     | OHS             |   5106 | Alive

4.3.5.1.1 Options for the Status Command of opmnctl

The following are the options you can specify for the <options> parameter:

• -l: Use this option to obtain the uniqueid (uid) value and other specific process parameter information.

  opmnctl status -l
  

  For example, the command outputs the information shown in Example 4-4 (some columns are not shown to improve readability).

  Example 4-4 opmnctl status -l output

  Processes in Instance: instance1
  --------------------+---------------+---------+---------+------------+----------+-----------+------
  ias-component       | process-type  |     pid | status  |        uid |  memused |   uptime  | ports
  ------------------------------------+---------+---------+------------+----------+-----------|------
  webcache1           | WebCache-admin|    1544 | Alive   | 1133202830 |   44216  |   0:04:39 | http_
  admin:7779
  webcache1           | WebCache      |    1545 | Alive   | 1133202829 |   64056  |   0:04:39 | http_
  stat:7780,http_invalidation:7781,https_listen:7782,http_listen:7778
  ohs1                | OHS           |    1543 | Alive   | 1133202828 |   348664 |   0:04:39 | https
  :8889,https:4443,http:8888
  

  The uid information enables you to stop or restart an individual Oracle Fusion Middleware process.

  For example, the following command stops the OHS process-type:

  opmnctl stopproc uniqueid=1792746301
  

• -fsep <string>: Use this option to assign a field separator value for your opmnctl status output. The default value is |.

• -rsep <string>: Use this option to assign a record separator value for your opmnctl status output. The default value is \n.

• -noheaders: Use this option if you do not want a header displayed after you run the opmnctl status command.

• -fmt <fmtlist>: This is a single string containing one or more statistic identifiers connected together where each identifier has the following format: <statname>[<width>{<justification>]. The default value is: %cmp18%prt18%pid5R%sta8.

  Table 4-3 lists the format string syntax for the <fmtlist> option:

Table 4-3 Format String Syntax

Format String Syntax	Description
<statname>	This must be one of the following: clu: system farm name ins: Oracle instance name cmp: system component ID prt: process-type ID prs: process-set ID idx: index of process in process-set pid: operating system process ID uid: OPMN uniqueid typ: name for this kind of process sta: process status stm: start time (ms) utm: up time (ms) cpu: cpu time (ms) mem: memory used (in KB) por: port list fpr: full detail port list
<width>	Specifies the size for the field. Output shorter than this value receives padding according to the specified <justification>. Output longer than this value is truncated, and terminated with '~'. Default: width of each datum.
<justification>	Specifies the justification for the field. This enables you to justify output when it is less than the width. It is L, R, or C (left, right, or center justification). Default: L

For example, the following command displays the output shown in Example 4-5:

prompt> opmnctl status -noheaders -fsep @ -fmt %cmp%prt%pid%sta

Example 4-5 opmnctl status -noheaders output

webcache1@WebCache-admin@1544@Alive
webcache1@WebCache@1545@Alive
ohs1@OHS@1543@Alive

See Also:

Section 4.3.1 for command definitions

Enter the following command for additional detailed information:

opmnctl usage status

4.3.5.1.2 opmnctl status -port

The opmnctl status -port command enables you to display the request connect string used to connect to the OPMN daemon. For example, the command:

opmnctl status -port

displays:

123.your_company.com:6200

This opmnctl status -port command is a convenient shortcut that replaces the need to look inside of the opmn.xml file to determine the request access port.

4.3.5.2 opmnctl metric

The opmnctl metric command enables you to print the DMS statistics for a system component process. The opmnctl metric has the following command and argument structure:

opmnctl metric op=<op> [<identifier>=<value>] dmsarg=<dmsargs>]

The opmnctl metric command uses the following command arguments:

• op=<op>: Specifies the operation, where <op> can be either list or query.

  A list operation does not use additional arguments. The target OPMN returns a list of managed system processes for which DMS metrics are available through the metric request.

  A query operation returns the metric tree for the managed process or processes qualified by the <identifier>=<value> arguments (all available processes are assumed if no identifier arguments are specified).

• local=<bool>: When set to true, this option limits the command to operate within the local Oracle instance. This is useful when OPMN has been configured to discover other Oracle instances.

• <identifer>=<value>: Specifies which managed process or processes to query for DMS metrics. Multiple identifiers can be specified, and each is used to match the managed process with address properties (the list is inclusive).

  The four standard properties are:

  • PROCESS_UID=<uid>:Where <uid> is the unique id for the target process. This value is obtained by the metric list operation, the opmnctl status command, or any similar method that is used to display OPMN DMS metrics.

  • PROCESS_UID=0: This property always specifies OPMN itself.

  • INSTANCE_UID=<instance>@<uid>: Where <instance> is the Oracle instance name for the target Oracle instance and <uid> is the unique id for the target process on the Oracle instance. This identifier is only valid if <instance> is the local Oracle instance name, or all OPMN servers in the farm are configured to connect to one another.

  • COMPONENT_NAME=<component-name>: Where <component-name> is the id value for the <ias-component> in the opmn.xml file. COMPONENT_NAME=opmn always specifies OPMN itself.

  • COMPONENT_TYPE=<component-type>: Where <component-type> is the type value for the <ias-component> in the opmn.xml file, or if that is not defined, the id value for the <process-type> element. COMPONENT_TYPE=OPMN always specifies OPMN itself.

• dmsarg=<dmsargs>: Specifies the DMS specific options for the metric query. <dmsargs> is a single argument that may include multiple options for the DMS layer, each following the <attr>=<value> format, and each option seperated by an &.

  For example: format=raw, format=xml&name=/ProcessInfo

  Refer to the Oracle Fusion Middleware Performance Guide for additional metric options.

4.3.5.3 opmnctl dmsdump

Syntax: opmnctl dmsdump [<attr>=<value>[&<attr>=<val>...]]

The opmnctl dmsdump command enables you to print the Oracle Dynamic Monitoring Service (DMS) statistics for OPMN. You can obtain a printout of process control operations for specific system components. If no attributes are specified, performance data for all system component processes for your system components are printed out.

DMS enables you to monitor a specific performance metric, a set of performance metrics, or all performance metrics. Options allow you to specify a reporting interval to report the requested metrics.

Multiple <attr>=<value> pairs must be separated by an &. For example, the following opmnctl command:

opmnctl dmsdump "table=opmn_ons&format=xml"

outputs the set of statistics that are gathered for ONS. The output includes the ports that ONS listens on and the number of notifications that ONS has processed. The output is in.xml format rather than text. If you want to review the output in text format do not include &format=xml on the command line.

For more information about DMS performance metric attributes and values refer to the Oracle Fusion Middleware Performance Guide.

4.3.5.4 opmnctl ping

Syntax: opmnctl ping [<max_retry>]

The opmnctl ping command enables you to contact the local OPMN server to verify operation. <max_retry> specifies the maximum number of retry times. If <max_retry> is specified, the local OPMN is pinged every one second, until the command execution succeeds or <max_retry> is reached.

For example, the following command,

opmnctl ping 10

designates pinging of OPMN 10 times until the ping command succeeds

4.3.5.5 opmnctl set

Syntax: opmnctl set [<attr>=<value> ...]

The opmnctl set command sets the logging configuration for OPMN.

An attribute name must be specified along with an attribute value. The following attribute names are required by OPMN for this command:

• target: the value for target can be either log or debug, which refer to the standard.log or the debug.log. The standard log is configured to include all possible log messages by default and it is recommended that users not change its settings. Refer to Appendix B for more information about OPMN troubleshooting.

  Note:

  Enable usage of the debug.log file only after conferring with Oracle Support. The debug.log file is used by Oracle Support to debug and diagnose OPMN issues. Messages that are contained in the debug.log file are typically not readily comprehensible to the user.

• comp: specifies the OPMN internal components and subcomponents

4.3.5.5.1 The comp Attribute

The value for the comp attribute can be either ons or pm. Additionally, the attribute value can be a specific set of sub-components for either the ons or pm attributes.

The following values for comp specify the OPMN internal components and subcomponents:

• internal:specifies the common internal information for OPMN

• ons:specifies the ONS component information for OPMN

• pm: specifies the PM component information for OPMN

Both the ons and pm components consist of subcomponents which may be specified using the component[subcomponents] syntax where component can be either ons or pm. If both ons and pm are specified together they must be separated by a semicolon in the opmn.xml file. If subcomponents are listed, the listed items must be separated by a comma.

Table 4-4 ONS Component Codes

ONS element	Definition
all	all subcomponents
local	local information
listener	listener information
discover	discover (server or multicast) information
servers	remote servers currently up and connected to the farm
topology	current farm wide server connection topology
server	remote server connection information
client	client connection information
connect	generic connection information
subscribe	client subscription information
message	notification receiving and processing information
deliver	notification delivery information
special	special notification processing
internal	internal resource information
secure	SSL operation information
workers	worker threads

Table 4-5 PM Component Codes

PM element	Definition
all	all subcomponents
requests	HTTP (user) requests
remote	remote HTTP requests
scheduler	scheduler thread and resource information
monitor	monitor thread information
workers	worker threads
process	managed processes
depend	dependency processing
rmd	RMD directives
fos	service failover information
internal	internal resources
schedjobs	periodic scheduled jobs
procjobs	for each process scheduled jobs
fos	service failover processing
dms	DMS processing
modules	process module information. Only modules which call the modLog() (or modDebug for the debug log) function yields output. A specific module or list of modules may be specified with modules(module-ids). module-ids can be specified with a colon seperated list of module-ids to be displayed: modules (module1-id:module2-id). module-ids that do not match a configured and enabled module are not processed.

Each subcomponent for ons and pm may be prefaced with the negation character,!, which deselects the subcomponent. By using all with negated sub-components, specific subcomponents can be easily eliminated from the display.

Components and subcomponents are set or negated in the order in which they are encountered. Therefore:

ons[all,!topology]

yields all ons subcomponents excluding topology, while the following:

ons[!topology,all]

yields all ons subcomponents including topology.

4.3.5.6 opmnctl query

Syntax: opmnctl query [<attr>=<value> ...]

The opmnctl query command enables you to query the logging configuration for OPMN.

The attribute name of target must be specified along with an attribute value. The value for target can be either log or debug, which refer to the opmn.log file or the opmn.dbg file, respectively. Refer to Section B.2.1, "OPMN log Files" for more information.

4.3.6 Help Commands

The opmnctl help commands enable you to obtain additional information regarding OPMN.

This section describes the help command options available with the opmnctl command. It includes the following sections:

• Section 4.3.6.1, "opmnctl help"

• Section 4.3.6.2, "opmnctl usage"

• Section 4.3.6.3, "opmnctl validate"

4.3.6.1 opmnctl help

Syntax: opmnctl help

Use this command to print a short syntax description of opmnctl commands.

Example 4-6 shows the output from the opmnctl help command.

Example 4-6 opmnctl help Output

opmnctl help

usage: opmnctl [verbose] [<scope>] <command> [<options>]

verbose: print detailed execution message if available

Permitted <scope>/<command>/<options> combinations are:

  scope      command      options
_________   __________   __________
            start                         - Start opmn
            startall                      - Start opmn & all managed processes
            stopall                       - Stop opmn & all managed processes
            shutdown                      - Shutdown opmn & all managed processes
[<scope>]   startproc   [<attr>=<val>..]  - Start system managed processes
[<scope>]   restartproc [<attr>=<val>..]  - Restart managed processes
[<scope>]   stopproc    [<attr>=<val>..]  - Stop managed processes
[<scope>]   reload                        - Trigger opmn to reread opmn.xml
[<scope>]   status      [<options>]       - Get managed process status
[<scope>]   dmsdump     [<attr>=<val>&..] - Get DMS stats
[<scope>}   set         [<attr>=<val> ..] - Set opmn log parameters
[<scope>]   query       [<attr>=<val> ..] - Query opmn log parameters
            launch      [<attr>=<val> ..] - Launch a configured target process
            phantom     [<attr>=<val> ..] - Register phantom processes
            ping        [<max_retry>]     - Ping local opmn
            validate    [<filename>]      - Validate the given xml file
            config      [<options>]       - Modify the opmn xml file
            help                          - Print brief usage description
            usage       [<command>]       - Print detailed usage description
            createinstance                - Create an Oracle Instance
            createcomponent               - Create a specified component
            deleteinstance                - Delete an instance and components
            deletecomponent               - Delete a specified component
            registerinstance              - Register with admin server
            unregisterinstance            - Unregister with admin server
            updateinstanceregistration    - Update instance registration
            updatecomponentregistration   - Update component registration

4.3.6.2 opmnctl usage

Syntax: opmnctl usage [<command>]

The usage command displays help for any one specified opmnctl command. With no argument the opmnctl usage command displays the same information as opmnctl help.

The command can be one or more of the following:

• start

• startall

• startproc

• stopall

• stopproc

• restartproc

• reload

• shutdown

• ping

• status

• metric

• dmsdump

• debug

• set

• query

• launch

• phantom

• ping

• validate

• help

• usage

• createinstance

• createcomponent

• deleteinstance

• deletecomponent

• registerinstance

• unregisterinstance

• updateinstanceregistration

• updatecomponentregistration

• help

For example, enter the following command to receive the output shown in Example 4-7:

opmnctl usage stopall

Example 4-7 opmnctl usage stopall output

opmnctl stopall [sequential=true] [report=true]

Stop opmn daemon and managed processes for local Oracle instance.

This request first tries to stop all managed processes gracefully.
Processes which will not stop gracefully will be forcefully shutdown.  After
stopping all managed processes, the opmn daemon will shutdown itself.

This request should only be performed when it is necessary to stop the opmn
daemon.  Once started, the opmn daemon should remain up until it is necessary to
restart the computer or some other rare administrative event occurs.

To stop all managed processes without stopping the opmn daemon, consider
using the stopproc command without any target arguments.

If the value of the sequential attribute is "true", each process will be stopped
upon sequentially (one at a time).

If the value of the report attribute is "true", opmn will report the results of
the attempt to stop each processes as it completes.
The default behavior is for opmn to wait until the entire request has completed
before sending all of the results at once.

To restart the opmn daemon without restarting any managed processes, consider
using the reload command.  The reload command is the appropriate command to
use when the only goal is to restart the opmn daemon with a new configuration.

This request operates synchronously and will wait for the operation to complete
before returning.

4.3.6.3 opmnctl validate

Syntax: opmnctl validate [<filename>]

The opmnctl validate command validates the XML syntax of the opmn.xml file. The default ORACLE_INSTANCE/config/OPMN/opmn/opmn.xml is validated when ORACLE_INSTANCE/bin/opmnctl is used. The <filename> can be specified by either the relative or absolute path.