1 OPMN: Overview

1.1 What is OPMN?

OPMN is installed and configured with every Oracle Application Server installation type and is essential for running Oracle Application Server.

OPMN features the following functionality:

• Provides a command-line interface for process control and monitoring for single or multiple Oracle Application Server components and instances.

• Provides an integrated way to manage Oracle Application Server components.

• Enables management of Oracle Application Server subcomponents and sub-subcomponents.

• Channels all events from different Oracle Application Server component instances to all Oracle Application Server components that can utilize them.

• Solves interdependency issues between Oracle Application Server components by enabling you to start and stop components in order.

• Enables customizing of enterprise functionality by using event scripts.

• Enables gathering of host and Oracle Application Server process statistics and tasks.

• Provides automatic restart of Oracle Application Server processes when they become unresponsive, terminate unexpectedly, or become unreachable as determined by ping and notification operations.

• Provides automatic death detection of Oracle Application Server processes.

• Does not depend on any other Oracle Application Server component being up and running before it can be started and used.

The OPMN server should be started as soon as possible after turning on the host. OPMN must be running whenever OPMN-managed components are turned on or off.

Oracle Application Server components managed by OPMN should never be started or stopped manually. Do not use command line scripts or utilities from previous versions of Oracle Application Server for starting and stopping Oracle Application Server components. OPMN must be the last service turned off whenever you restart or turn off your computer.

Use the Application Server Control Console and the opmnctl command line utility to start or stop Oracle Application Server components.

1.2 How OPMN Works

OPMN consists of a core grouping of three components that interpret and convey notification information sent between Oracle Application Server processes within the same or different OPMN servers.

The core of OPMN consists of the following three components:

• Oracle Notification Server

• Oracle Process Manager

• PM Modules

Figure 1-1 shows the architecture of the core of OPMN.

Figure 1-1 OPMN Architecture

Description of "Figure 1-1 OPMN Architecture"

1.3 What Oracle Application Server Components Does OPMN Manage?

OPMN manages all Oracle Application Server components except the OracleAS Metadata Repository or the Application Server Control Console.

OPMN enables you to explicitly manage the following list of Oracle Application Server 10g Release 2 (10.1.2) components:

• Oracle HTTP Server

• Oracle Application Server Containers for J2EE (OC4J)

• Distributed Configuration Management (DCM) daemon (server)

• OracleAS Log Loader

• Oracle Internet Directory

• OracleAS Port Tunnel

• OracleAS Web Cache

• OracleBI Discoverer

• OracleAS Wireless

OPMN also manages other Oracle Application Server components implicitly; the constituent parts of the implicit Oracle Application Server components are managed by OPMN as part of one or more other Oracle Application Server components. For example, OracleAS Portal while not explicitly managed by OPMN is implicitly managed because it is operational using OC4J and Oracle HTTP Server.

The following components are implicitly managed by OPMN:

• OracleAS Single Sign-On

• Oracle HTTP Server Adapter of OracleAS Integration InterConnect

• Oracle Distributed Authoring and Versioning (OraDAV)

• OracleAS Portal

• OracleAS SOAP

• OracleAS UDDI Registry Server

• Oracle Ultra Search

• OracleAS TopLink

You can also configure OPMN to manage other processes using the Custom PM Module. See Chapter 15, "Configuring Custom Process" for more information.

Because of the extensible design of OPMN, add-on components are managed by OPMN without having to update OPMN itself.

1.4 OPMN Configuration Files

The opmn.xml file does not contain component-specific element names. Component specific management code is located in the PM modules which get loaded by OPMN at startup according to what has been specified in the modules section of the opmn.xml file.

Each level has a specific set of configurations. In addition, there are several configuration elements that are accepted at more than one level to provide the flexibility of applying a configuration across an entire Oracle Application Server component or just part of a component.

OPMN reads the following configuration files when started or reloaded:

• ORACLE_HOME/opmn/conf/opmn.xml

  The opmn.xml file is the main configuration file for OPMN. The opmn.xml file contains information for the ONS, the PM, and Oracle Application Server component specific configuration.The opmn.xml file shows you which Oracle Application Server components OPMN is managing on your system.

  The opmn.xml file contains Oracle Application Server component entries arranged in the following hierarchical structure:

  <ias-component>
     <process-type>
        <process-set>
  
  

  <ias-component>: This entry represents the Oracle Application Server component. It enables management of the component for processes such as starting and stopping.

  <process-type>: This subcomponent of the <ias-component> entry declares the type of process to run by association with a specific PM module.

  <process-set>: This sub-subcomponent of the <ias-component> entry enables you to declare different sets of optional runtime arguments and environments for the Oracle Application Server component.

  Example 1-1 shows an example of the <ias-component>, <process-type>, <process-set> entries in an opmn.xml file.

  Example 1-1 opmn.xml file

  <ias-component id="OC4J">
     <process-type id="home">
        <process-set id="default_island">....
  
  

  You can edit opmn.xml using Application Server Control Console. Click the Process Management link at the bottom of the Oracle Application Server instance home page. Do not stop the OPMN server after you edit the opmn.xml file. Application Server Control Console automatically reloads the updated opmn.xml file after you edit the file.

  If you manually edit the opmn.xml file run the dcmctl updateConfig command on the command line. dcmctl updateConfig reloads the updated file and updates the configuration repository with the manual changes.

• ORACLE_HOME/opmn/conf/ons.conf

  OPMN uses the ons.conf file to find all the different Oracle Application Server instances in the farm. The ons.conf file is automatically generated and maintained by DCM. Do not edit the ons.conf file; edits to this file are overwritten by DCM.

• ORACLE_HOME/dcm/config/dcm.conf

  The dcm.conf file specifies the instance name and cluster name of the local Oracle Application Server installation.The dcm.conf file is automatically generated and maintained by DCM. The dcm.conf file should not be edited manually.

1.5 Automatic Restart

OPMN gives the user control over automatic death detection and restart of components; you can configure the parameters by which OPMN determines a process has died and disable automatic restart for individual components.

OPMN monitors the operation of its managed processes by the following methods:

• Operating system level detection of Oracle Application Server process death

• Periodic ping requests to Oracle Application Server processes

• Periodic status notification from Oracle Application Server processes ("reverse-ping")

The ping and notification functionality is only used where appropriate according to the functionality of the Oracle Application Server component.

OPMN automatically restarts Oracle Application Server components that terminate unexpectedly. OPMN will also restart processes that are unresponsive according to the result of notification and ping operations.

1.6 opmnctl

opmnctl is the supported tool for starting and stopping all components in an Oracle Application Server instance, with the exception of the Oracle Application Server Metadata Repository and the Oracle Enterprise Manager 10g Application Server Control Console (Application Server Control Console). opmnctl provides a centralized way to control and monitor Oracle Application Server components from the command line. You can use opmnctl to execute control and monitoring commands across multiple Oracle Application Server instances simultaneously.

opmnctl also enables you to perform operations on a specified Oracle Application Server instance on the application server farm, all instances in the farm, and all instances in a cluster using an optional parameter called scope. You can also use the scope option to control an individual Oracle Application Server process.

The opmnctl command is located in the following directory locations:

(UNIX) ORACLE_HOME/opmn/bin/opmnctl

(Windows) ORACLE_HOME\opmn\bin\opmnctl

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

1.7 opmnctl Command Quick Reference

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

prompt > opmnctl help

  scope      command      options
_________   __________   __________
            start                         - Start opmn
            startall                      - Start opmn and all managed processes
            stopall                       - Stop opmn and all managed processes
            shutdown                      - Shutdown opmn and 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>]   dmsdump     [<attr>=<val>&..] - Get DMS stats
            ping        [<max_retry>]     - Ping local opmn
            validate    [<filename>]      - Validate the given xml file
            help                          - Print brief usage description
            usage       [<command>]       - Print detailed usage description

1.8 opmnctl Detailed Command Description

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

• Section 1.8.1, "Server Control Commands"

• Section 1.8.2, "Process Control Commands"

• Section 1.8.3, "Command Definitions"

• Section 1.8.4, "Status Commands"

• Section 1.8.5, "Help Commands"

prompt > opmnctl usage startall
stopall
start startall startproc

prompt > opmnctl usage stopall

prompt > opmnctl usage shutdown

prompt > opmnctl usage stopall

prompt > opmnctl usage shutdown

prompt > opmnctl usage reload

prompt > opmnctl startproc ias-component=wireless process-type=alert_server process-set=alert_instance_1

prompt > opmnctl restartproc ias-component=OC4J process-type=home

prompt > opmnctl stopproc ias-component=HTTP_Server

prompt > opmnctl usage startproc

prompt > opmnctl usage restartproc

prompt > opmnctl usage stopproc

prompt > opmnctl @instance:myInst2.foo.com startproc ias-component=HTTP_Server

prompt > opmnctl startproc ias-component=wireless

prompt> opmnctl verbose startproc ias-component=HTTP_Server

HTTP/1.1 200 OK
Content-Length: 0
Content-Type: text/html
Response: Ping succeeded.

opmnctl: starting opmn managed processes...
HTTP/1.1 200 OK
Content-Length: 571
Content-Type: text/html
Response: 1 of 1 processes started.

<response>
<opmn id="jerichar-sun.us.oracle.com:6200" http-status="200" http-response="1 of 1 processes started.">
   <ias-instance id="M140801.jerichar-sun.us.oracle.com">
      <ias-component id="HTTP_Server">
         <process-type id="HTTP_Server">
            <process-set id="HTTP_Server">
               <process id="1954086921" pid="9355" status="Alive" index="1"
                log="/home/demoas/M140801/opmn/logs/HTTP_Server~1"
                operation="request" result="success">
               </process>
            </process-set>
         </process-type>
      </ias-component>
   </ias-instance>
</opmn>
</response>

prompt > opmnctl status

Processes in Instance: AppSrv1.comp1.yourcompany.com
--------------------+----------------------+--------+---------
ias-component       | process-type         |    pid | status
--------------------+----------------------+--------+---------
WebCache            | WebCacheAdmin        |  29121 | Alive
WebCache            | WebCache             |  29120 | Alive
OC4J                | OC4J_Demos           |    N/A | Down
OC4J                | home                 |  29268 | Init
dcm-daemon          | dcm-daemon           |  29113 | Alive
LogLoader           | logloader            |    N/A | Down
HTTP_Server         | HTTP_Server          |  29099 | Alive

prompt > opmnctl @farm status

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

OC4J@home@N/A@Down
dcm-daemon@dcm-daemon@13875@Alive
LogLoader@logloaderd@9800@Alive 
HTTP_Server@HTTP_Server@13926@Alive

prompt > opmnctl usage status

prompt > opmnctl dmsdump "table=opmn_ons&format=xml"

prompt > opmnctl ping 10

prompt > opmnctl help

usage: /ORACLE_HOME/bin/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>]   dmsdump     [<attr>=<val>&..] - Get DMS stats
            ping        [<max_retry>]     - Ping local opmn
            validate    [<filename>]      - Validate the given xml file
            help                          - Print brief usage description
            usage       [<command>]       - Print detailed usage description

prompt > opmnctl usage stopall

opmnctl stopall

Stop opmn daemon and opmn managed processes for local ias instance.

This request first tries to stop all opmn 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 opmn managed processes without stopping the opmn daemon, consider
using the stopproc command without any arguments.

To restart the opmn daemon without restarting any managed processes, consider
using the 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.

1.9 Event Scripts

You can configure OPMN to execute your own custom event scripts whenever a particular component starts, stops, or crashes. You can select from one or more of the following event types:

• pre-start: OPMN runs the pre-start script after any configured dependency checks have been performed and passed, and before the Oracle Application Server component starts. For example, the pre-start script can be used for site-specific initialization of external components.

• pre-stop: OPMN runs the pre-stop script before stopping a designated Oracle Application Server component. For example, the pre-stop script can be used for collecting Java Virtual Machine stack traces prior to stopping OC4J processes.

• post-crash: OPMN runs the post-crash script after the Oracle Application Server component has terminated unexpectedly. For example, a user could learn of component crashes by supplying a script or program to be executed at post-crash events which sends a notification to the administrator's pager.

1.10 Start Order Dependencies

Some Oracle Application Server components and services require that other components and services are up and running before starting. OPMN is configured at installation with default start order dependencies, which enables you to start all of the components in an instance in the proper order with a single command. Refer to the Oracle Application Server Administrator's Guide for more information on Oracle Application Server dependencies.

OPMN is configured with a set of dependencies but you can configure additional dependencies according to the environment

1.11 OPMN Log Files

The log files generated by OPMN provide important information that can help you identify and diagnose performance and configuration issues. The Application Server Control Console makes reviewing these log files easier by helping you locate and view Oracle Application Server component log files.

1.12 Security

The OPMN local listener port used by ONS clients and PM administrative processes do not use Secure Socket Layer (SSL) encryption for security, but rely on two other mechanisms to ensure authorized access to the OPMN server:

• OPMN binds the local listener port to the local host. Users on the local system can connect to this port and issue OPMN process control requests. Information requests are allowed on the OPMN request port, which is bound to the system IP. The request port does not have SSL encryption.

• When the OPMN server process first starts up and successfully binds to the local port, it creates a string of printable ASCII characters which it uses as a key for local connections. All connection attempts on the local port must include this key or the connection is closed by the OPMN server. The ASCII character string is written into the ORACLE_HOME/opmn/conf/.formfactor file. Processes that cannot access the .formfactor file are not permitted to interact with the OPMN server.

For security reasons, the OPMN server logs any attempts to connect to its local port with an invalid form factor key (a key that does not match the value written by this OPMN process into the .formfactor file).

In addition to attempted security violations, there are four common user errors that can cause this error to occur:

• The user attempts to run the OPMN client manually with the wrong user identification. Only the application server user can read the value from the .formfactor file, and so requests or processes run as the wrong user will not be able to provide the correct key to the OPMN server.

• The user is attempting to run an OPMN client from the wrong ORACLE_HOME. It is possible to have multiple ORACLE_HOME instances set up on the same system. If the other ORACLE_HOME instances have OPMN configured to use the same local port then the Oracle Application Server process request from the wrong ORACLE_HOME will read the wrong .formfactor file.

• The user has manually changed the local port configuration in the opmn.xml file and started a new OPMN server without first stopping the previous OPMN server. The new OPMN server will run, bind to the new port, and overwrite the .formfactor file. The previous OPMN server is now unreachable through the local port, and can only be shutdown through remote OPMN requests (if SSL and authentication are configured) or by manually stopping the previous OPMN server.

• The Oracle Application Server and the Oracle Database both use ONS. When these two products are installed onto the same host, an ONS port conflict arises since the default port values (local="6100" remote="6200") for ONS are the same for both the Oracle Database and Oracle Application Server.

  ONS with the Oracle Database is only used for special configurations and therefore is typically never started. However, the database listener will attempt to connect to the Database ONS server but will end up connecting to the ONS server that was installed with Oracle Application Server. ONS (as part of OPMN) is always started whenever Oracle Application Server is started.

  Because the Oracle Database is installed in a different ORACLE_HOME than that of Oracle Application Server, the Database ONS does not have access to the .formfactor file that was created when OPMN started up with the Oracle Application Server. As a result, the database listener attempts to connect to OPMN; the DB listener interprets it as a its standalone ONS) without a form factor string. Oracle Application Server OPMN logs an error similar to the following in the ons.log file:

  04/11/15 18:43:32 [4] Local connection 0,127.0.0.1,6100 invalid form factor
  
  

  This is expected OPMN behavior Oracle Application Server; preventing client access to the ONS server unless they possess the correct formfactor string.

  To avoid having the Oracle Database listener contact the Oracle Application Server OPMN server, change the default local and remote port values for the ONS server that was installed with the Oracle Database. Alternatively, you can apply the latest Oracle Database patchset available on OTN:

  http://www.oracle.com/technology/products/
  
  

1.13 DCM

DCM manages the configuration of opmn.xml and manages configurations among application server instances that are associated with a common Infrastructure (members of an Oracle Application Server farm). It enables Oracle Application Server cluster-wide deployment so you can deploy an application to an entire cluster, or make a single host or instance configuration change applicable across all instances in a cluster. The Application Server Control Console uses DCM to make configuration changes and to propagate configuration changes and deployed applications across the cluster.

All command line process control should be through the OPMN opmnctl command. The DCM dcmctl command should be used only for configuration related operations and application deployment.

1.14 iHAT

The Oracle Application Server Hi-Av Tool (iHAT) provides a real time, graphical interface view of your enterprise. iHAT displays all Oracle Application Server processes managed by one or more OPMN servers including useful performance metrics about each process. The snapshot of the system is updated continuously at a configurable interval.

iHAT shows your Oracle Application Server instance with Oracle Application Server components. The ias-component, process-set, and process-type levels are displayed for each Oracle Application Server component. The child process display of the process-type shows the status, process-type, process identification (pid), memory usage, uptime, and CPU usage.

Figure 1-2 shows an example of the iHAT display for an enterprise with two Oracle Application Server instances.

To download iHAT, visit the OTN:

http://www.oracle.com/technology/membership

Figure 1-2 Example iHAT Display

Description of "Figure 1-2 Example iHAT Display"