Skip Headers

Oracle® Process Manager and Notification Server Administrator's Guide 10g Release 3 (10.1.3) B15976-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 6 opmn.xml Common Configuration

This chapter provides common configuration examples, and descriptions of elements and attributes for the OPMN `opmn.xml` file.

It contains the following topics:

- Section 6.1, "Example of opmn.xml Elements and Attributes"

- Section 6.2, "opmn.xml Element and Attribute Descriptions"

## 6.1 Example of opmn.xml Elements and Attributes

Example 6-1 shows all possible elements and attributes that may appear in an `opmn.xml` file that are not specific to any Oracle Application Server component.

Note: OPMN will convert slashes in the path value string to be those of the directory path separator character for the system on which OPMN is running (for Linux each \ character is converted to /; for Microsoft Windows each / is converted to \). OPMN uses the ^ character as an escape character to disable slash conversion. ^/ on a Microsoft Windows system will yield a / in the string. Specify two ^ characters if you need to specify the ^ character in the resultant string. For example, ^^ yields ^.

Example 6-1 Common Configuration Elements and Attributes

    <opmn>
    <logpath="path" comp="comp-codes" rotation-size="kBytes" rotation-hour="HOD"/>
    <debugpath="path" comp="comp-codes" rotation-size="kBytes" rotation-hour="HOD"/>
       <notification-serverinterface="type">
          <ipaddrremote="ip" request="ip"/>
          <portlocal="port" remote="port" request="port"/>
          <sslenabled="boolean" wallet-file="path" wallet-password="password" openssl-certfile="path"
           openssl-keyfile="path" openssl-password="password" openssl-lib="path"/>
          <tuneio-timeout="timeout" io-idle="interval" timeout="timeout"/>
          <topology>
             <nodes list="nodes"/>
             <discover list="nodes"/>
             <gateway list="nodes"/>
          </topology>
       </notification-server>
       <process-managerinsecure-remote-requests="boolean">
          <process-modules>
             <modulepath="path" tag="tag-id" status="state" cron="interval">
                <module-data>
                   <categoryid="id">
                      <dataid="id" value="value" process-conversion="boolean"/>
                   </category>
                </module-data>
             <module-idid="module-id"/>
       </module>
    </process-modules>
    <ias-instanceid="ias-instance-id" name="ias-instance-name" ORACLE_HOME="path">
       <environment>
          <variableid="id" value="value" append="boolean" process-conversion="boolean"/>
       </environment>
    <!-- module-data-->
       <rmd-definitions>
          <rmdname="name" description="description" interval="interval">
             <conditional>
                <![CDATA[condition]]>
             </conditional>
          <actionvalue="action"/>
          <exceptionvalue="exception">
       </rmd>
    </rmd-definitions>
    <ias-componentid="component-id" id-matching="boolean" status="state">
       <!-- environment-->
       <!-- module-data-->
       <dependencies>
          <databasedb-connect-info="connect" infrastructure-key="key" timeout="depend-timeout"
           cache-timeout="cache-timeout"/>
          <OIDaddress="address" infrastructure="boolean" timeout="depend-timeout"
           cache-timeout="cache-timeout">
             <sslenabled="boolean" wallet-file="path" wallet-password="password">
          </OID>
          <OSSOhost="hostname" port="port" URI="uri" timeout="depend-timeout"
           cache-timeout="cache-timeout">
             <sslenabled="boolean" wallet-file="path" wallet-password="password">
          </OSSO>
          <managed-processias-instance="ias-instance-id" ias-component="ias-component-id"
           process-type="process-type-id" process-set="process-set-id" autostart="boolean"
           autostop="boolean" timeout="depend-timeout"cache-timeout="cache-timeout"/>
       </dependencies>
    <!-- rmd-definitions-->
       <process-typeid="process-type-id" module-id="module-id" status="state" working-dir="path"
        service-failover="num" service-weight="value">
          <!-- environment-->
          <!-- module-data-->
          <!-- dependencies-->
          <event-scripts>
             <pre-startpath="path">
             <pre-stoppath="path">
             <post-crashpath="path">
          </event-scripts>
             <!-- rmd-definitions-->
          <starttimeout="timeout" retry="num"/>
          <stoptimeout="timeout"/>
          <restarttimeout="timeout" retry="num"/>
          <pingtimeout="timeout" retry="num" interval="interval"/>
          <portid="id" range="range"/>
          <process-setid="process-set-id" restart-on-death="boolean" numprocs="num" minprocs="min"
           maxprocs="max" status="state" working-dir="path" parallel-requests="boolean">
             <!-- environment-->
             <!-- module-data-->
             <!-- dependencies-->
             <!-- event-scripts-->
             <!-- rmd-definitions-->
             <!-- start:-->
             <!-- stop-->
             <!-- restart-->
             <!-- ping-->
             <!-- port-->
          </process-set>
          </process-type>
          </ias-component>
          </ias-instance>
          <!-- rmd-definitions(global) -->
       </process-manager>
    </opmn>

## 6.2 opmn.xml Element and Attribute Descriptions

This section describes the elements and attributes in the `opmn.xml` file that are not specific to any Oracle Application Server component. This section also provides attribute descriptions of the elements.

<opmn>

Required: true
Default: none
Parents: none
Attributes: none

`<opmn>` is the top-level element in the `opmn.xml` file.

<log>

Required: false
Default: see attributes
Parents: <opmn>
Attributes: `path`, `comp`, `rotation-size`, `rotation-hour`

The configuration definitions for the OPMN log mechanism.

path="path"

Required: true
Default: `$ORACLE_HOME``/opmn/logs/opmn.log`
Valid Values: The path name for the OPMN log file.

All directories specified in the path attribute must exist. OPMN must have read and write permissions for the directory containing the log file. The`$ORACLE_HOME` directory may be used.

comp="comp-codes"

Required: true
Default: `internal`, `ons`, `pm`
Valid Values: A list of `comp-codes`. A semi-colon must be used to separate the items on the `comp-codes` list.

The `comp` attribute specifies the component codes for logged events. These codes can be viewed and changed dynamically at OPMN run-time using the following commands:

    > opmnctl query target=log
    > opmnctl set target=log comp=<comp-codes>

The values revert back to the configured values in the `opmn.xml` file when OPMN is reloaded.

The following comp-codes are displayed in the log and debug elements of the `opmn.xml` file:

- `internal`: a log for the common internal information for OPMN

- `ons`: a log for the ONS component information for OPMN

- `pm`: a log for the PM component information for OPMN

Both the `ons` and `pm` components consist of subcomponents which may be specified using the `component[subcomponents]` syntax. The component can be either `ons` or `pm` (separated by a semicolon if both are specified). The list of valid subcomponents for the given component are each separated by a comma. For example, `comp="ons[local,listener];pm"`.

The following Table 6-1 lists the ONS component codes.

Table 6-1 ONS Component Codes

ONS Attribute | 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 cluster
topology | current cluster 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

The following Table 6-2 lists the PM component codes.

Table 6-2 PM Component Codes

PM Attribute | 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 will yield 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` or `pm`) may be prefaced with the negation character ! which deselects the subcomponent. By using the term "all" with negated sub-components, specific subcomponents are eliminated from the display.

Components and subcomponents are set or negated in the order in which they are encountered. The `ons[all,!topology]` will yield all `ons` subcomponents excluding `topology`, while `ons[!topology,all]` will yield all `ons` subcomponents including `topology`.

rotation-size="kBytes"

Required: false
Default: none
Valid Values: An integer.

The `rotation-size` is the maximum size in kilobytes of the log file. When the log file reaches the configured size, the OPMN logging mechanism will close the log, rename it with a time stamp suffix, and then create a new log file. This attribute may be used with `rotation-hour`.

rotation-hour="HOD"

Required: false
Default: none
Valid Values: An integer value between 0 to 23.

At the given hour of the day, the OPMN logging mechanism will close the log, rename it with a time stamp suffix, and then create a new log file. This attribute may be used with `rotation-size`.

<debug>

Required: false
Default: see attributes
Parents: <opmn>
Attributes: `path`, `comp`, `rotation-size`, `rotation-hour`

The `debug` element contains the configuration definitions for the OPMN debug log mechanism.

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

path="path"

Required: true
Default: `$ORACLE_HOME``/opmn/logs/opmn.dbg`
Valid Values: The path name for the OPMN debug log file.

All directories specified in the path name must already exist, and OPMN must have read and write permissions for the directory in which the debug log file resides. The`$ORACLE_HOME` directory may be used.

comp="comp-codes"

Required: true
Default: `internal`, `ons`, `pm`
Valid Values: A list of `comp-codes`. A semi-colon must be used to separate the items on the `comp-codes` list.

The `comp` attribute specifies the component codes for logged events. These codes can be viewed and changed dynamically at OPMN run-time using the following commands:

    > opmnctl query target=log
    > opmnctl set target=log comp=<comp-codes>

The values revert back to the configured values in the `opmn.xml` file when OPMN is reloaded.

The following comp-codes are displayed in the log and debug elements of the `opmn.xml` file:

- `internal`: a log for the common internal information for OPMN

- `ons`: a log for the ONS component information for OPMN

- `pm`: a log for the PM component information for OPMN

Both the `ons` and `pm` components consist of subcomponents which may be specified using the `component[subcomponents]` syntax. The component can be either `ons` or `pm` (separated by a semicolon if both are specified). The list of valid subcomponents for the given component are each separated by a comma. For example, `comp="ons[local,listener];pm"`.

The following Table 6-3 lists the ONS component codes.

Table 6-3 ONS Component Codes

ONS Attribute | 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 cluster
topology | current cluster 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

The following Table 6-4 lists the PM component codes.

Table 6-4 PM Component Codes

PM Attribute | 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 will yield output. A specific module or list of modules may be specified with modules(`module-ids`). `module-ids` can be specified with a colon separated 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` or `pm`) may be prefaced with the negation character ! which deselects the subcomponent. By using the term "all" with negated sub-components, specific subcomponents are eliminated from the display.

Components and subcomponents are set or negated in the order in which they are encountered. The `ons[all,!topology]` will yield all `ons` subcomponents excluding `topology`, while `ons[!topology,all]` will yield all `ons` subcomponents including `topology`.

rotation-size="kBytes"

Required: false
Default: none
Valid Values: An integer.

The`rotation-size` is the maximum size in kilobytes of the log file. When the log file reaches the configured size, the OPMN logging mechanism will close the log, rename the log with a time stamp suffix, and then create a new log file.

The rotation-size attribute may be used with the `rotation-hour` attribute.

rotation-hour="HOD"

Required: false
Default: none
Valid Values: An integer value between 0 to 23.

The `rotation-hour` attribute for use with the log file at the specified time of day, the OPMN logging mechanism will close the log file, rename it with a time stamp suffix, and then create a new log file. This attribute may be used with the `rotation-size` attribute.

<notification-server>

Required: true
Default: none
Parents: <opmn>
Attributes: interface

The `notification-server` element configures or, contains the elements to configure the ONS portion of OPMN.

interface="type"

Required: false
Default: any
Valid Values: any, IPv6, or IPv4

By default, OPMN will support both the IPv6 and IPv4 network interfaces (see Section 3.10, "IPv6 Support"). OPMN binds to both interfaces for its listener ports and attempts connections using either interface. OPMN always attempts to use the IPv6 interface first, if such an address is available. This behavior is the same as the default behavior for the Sun Java Virtual Machine (JVM).

Both IPv4 and IPv6, require that you use the same network for connection to other OPMN servers. For example, IPv6 forces OPMN to only use the IPv6 network interface even if the IPv4 interface is available. This means that OPMN is only be able to connect to (and be connected from) other OPMN servers that can use the same network interface. If you configure IPv6 or IPv4 on a system that does not provide the same network interface support, OPMN will not start.

<ipaddr>

Required: true
Default: none
Parents: <notification-server>
Attributes: `remote, request`

The `iapddr` element specifies host information for ONS listener threads and host port bindings.

remote="ip; ip"

Required: false
Default: none
Valid Values: an IP address (in the ###.###.###.### format) or host name to which ONS will bind its remote port. A list of IP values may be configured to force ONS to bind to a specific set of IP addresses. Each IP value must be separated by a semi-colon on the list.

The `remote` attribute is the IP address or host name to which ONS will bind its remote port. The remote port is used for ONS to ONS communication. Notifications pass from ONS to ONS through the remote port, and OPMN uses ONS to route remote requests to other OPMN servers through the remote port.

request="ip; ip"

Required: false
Default: IP address for default system host name
Valid Values: an IP address (in ###.###.###.### format) or host name to which ONS will bind its request port. A list of IP values may be configured to force ONS to bind to a set of specific IP addresses. The values on the list must be separated by a semi-colon.

The `request` attribute is for the IP address or host name to which ONS will bind its remote port. This port can only be used for obtaining status information.

<port>

Required: true
Default: none
Parents: <notification-server>
Attributes: `local, remote, request`

The `port` element contains configuration information for ONS listener threads host and port bindings.

local="port"

Required: true
Default: none
Valid Values: A valid port number.

The `local` attribute is for the ONS local port value.

remote="port"

Required: false
Default: none
Valid Values: A port number.

The `remote` attribute is for the ONS remote port value.

request="port"

Required: false
Default: none
Valid Values: A port number.

The `request` attribute is for the ONS request `port` value.

<ssl>

Required: false
Default: none
Parents: <notification-server>
Attributes: `enabled, wallet-file, wallet-password`, `openssl-certfile`, `openssl-keyfile`, `openssl-password`, and `openssl-lib`

The `ssl` element is used for ONS to ONS security and authentication configuration. You may configure either the Oracle SSL layer (`wallet-file` and `wallet-password`) or the Open SSL layer (`openssl-certfile`, `openssl-keyfile`, `openssl-password`, and `openssl-lib`). You cannot use both. If you configure both Oracle and Open SSL layers within the same `opmn.xml` file, the server will not start.

The Oracle SSL layer uses the libraries shipped with either the Oracle Application Server or Oracle Database products. The Oracle SSL layer uses the standard Oracle wallet.The Open SSL layer provides better performance, documentation, and support for encryption hardware. It also has uses less hardware space within OPMN. Open SSL is an open source tool kit to develop security protocols. You can find more information at:

`http://www.openssl.org`

enabled="boolean"

Required: true
Default: none
Valid Values: `true` or `false`

If the `enabled` value is set to true, it enables SSL connections for ONS.

wallet-file="path"

Required: false (for Oracle SSL only)
Default: none
Valid Values: The path name to the Oracle wallet.

The `wallet-file` attribute specifies the path name to the Oracle wallet to use for authentication on ONS connections. The`$ORACLE_HOME` directory may be used.

wallet-password="password"

Required: false (for Oracle SSL only)
Default: none
Valid Values: A string for the wallet password.

The `wallet-password` attribute is the password string for the specified Oracle wallet.

openssl-certfile="path

Required: true (for Open SSL only)
Default: none
Valid Values: The path name to the Open SSL cert file.

The `openssl-certfile` attribute specifies the Open SSL certificate file to use for authentication on ONS connections. The`$ORACLE_HOME` directory may be used.

openssl-keyfile="path

Required: true (for Open SSL only)
Default: none
Valid Values: The path name to the Open SSL key file.

The `openssl-keyfile` attribute specifies the Open SSL key file to use for authentication on ONS connections. The`$ORACLE_HOME` directory may be used.

openssl-password="password"

Required: true (for Open SSL only)
Default: none
Valid Values: A string for the `openssl-keyfile` password.

The `openssl-password` attribute is the password string for the specified `openssl-keyfile`.

openssl-lib="path"

Required: false (for Open SSL only)
Default: none
Valid Values: The path name to the Open SSL library.

The `openssl-lib` attribute specifies the path name to the Open SSL library where the shared library files (for example, `libssl` and `libcrypto`) reside. If the `openssl-lib` path name is not provided, then the environment from which OPMN is launched must include the path name in the proper system variable. The`$ORACLE_HOME` directory may be used.

<tune>

Required: false
Default: See attributes
Parents: notification-server
Attributes: `io-timeout`, `io-idle`, `timeout`

The `tune` element contains the information for the Tuneable Notification Server ONS parameters.

io-timeout="timeout"

Required: false
Default: 30
Valid Values: 0 or an integer value >= 4 and <= 3600

The `io-timeout` is the socket read timeout value in seconds used by each remote OPMN (or ONS) server directly connected to the local server. If the remote server does not receive any data across the connection with the local server in the configured `io-timeout` period, the remote server will time-out the connection and close the socket. The `io-timeout` value is the timeout period remote OPMN (or ONS) servers will use for the local server.

The `io-timeout` value is also used as a timeout for resource cleanup after an ONS connection has disconnected. If the connection is reestablished before the timeout period, the resources are transferred to the new connection. Otherwise the resources are released after the timeout period has expired.

Service failover participant state, duplicate ONS notification detection state, and notifications routed to the downed connection all use the `io-timeout` value. Notifications are queued to the down connection until the timeout occurs or the connection is reestablished.

The `io-timeout` parameter should be increased for servers running on very busy or overloaded systems.

A value of 0 disables `io-timeout` checking on remote servers for the local server. The `io-timeout` disables cleaning up of failover participant state, duplicate notification detection state, and notifications queued for the down connection. Notifications will continue to be queued until the connection is reestablished, which can consume an ever expanding amount of memory on the remote OPMN or ONS servers if the timeout check is disabled and the connection never comes back. The `io-timeout` parameter should only be set to 0 for debug purposes.

A configured non- zero value that is less than the minimum value is set to the minimum, and a value greater than the maximum is set to the maximum.

io-idle="interval"

Required: false
Default: `io-timeout` - ( `io-timeout` / 3 )
Valid Values: an integer value >= 2 and <= ( `io-timeout` - 2 )

The interval in seconds between sending a message to each remote server to which the local server is directly connected. If no normal network traffic is sent from the local server to any remote server in the configured interval, a message is sent to the remote server.

The `io-idle` parameter ensures that an idle but responsive OPMN server does not have its connection timed out when with a remote server. On busy systems, this value should be far enough below the `io-timeout` value such that there is enough time for the local server to queue and send the idle message to the remote server before the remote server detects the timeout.

If the `io-timeout` is 0, the `io-idle` attribute is ignored. A configured value that is less than the minimum value is set to the minimum, and a value greater than the maximum is set to the maximum.

timeout="timeout"

Required: false
Default: 20
Valid Values: an integer value >= 1 and <= 3600

The `timeout` parameter is the socket timeout value in seconds used for the local OPMN server for connection attempts and client connection writes. If the connection handshake to the local OPMN server takes longer than the configured timeout value, then the socket is closed and the connection resources are available. If a write on a client connection socket takes longer than the configured timeout value, then the socket is closed and the connection resources are available.

<topology>

Required: false
Default: none
Parents: notification-server
Attributes: none

The `topology` element contains the configuration information for the ONS topology within a cluster.

<nodes>

Required: false
Default: none
Parents: topology
Attributes: list

The `nodes` element provides a list of specific addresses for OPMN servers in the same cluster as the local OPMN server. The local OPMN server is included in the list. Multiple nodes elements may be configured.

list="list-of-nodes"

Required: true
Default: none
Valid Values: a list of nodes, with a comma separating each listed node. Each node represents an OPMN server in the cluster.

Each `node` entry represents an instance in the cluster to which the local OPMN server will attempt to connect to remote OPMN servers. The connection is needed to transfer information such as notifications, status, and user requests. If OPMN is unable to connect to a configured remote node, it will try again every 120 seconds. Duplicate entries are ignored.

Each `node` entry must be specified in the address:port format. The address must be a valid Transmission Control Protocol (TCP) IP address. Refer to Section 3.10, "IPv6 Support" for more information about supported IP connections for OPMN.

Each `node` value should correspond to an OPMN server running on the system. The OPMN server must be specified by address and configured to listen on the remote port specified by the `port` element.

The value of address should be the same as the one configured for the corresponding OPMN. If the system has multiple IP addresses or multiple host names, then the value of address must match the value configured for the remote attribute of the `ipaddr` element of the `notification server`.

The address portion of each node may consist of a list of host names or IP addresses for the same system. The lists are available only if the remote node `ipaddr` remote attribute is configured with the same set of information. The listed host names and IP addresses must be separated by a semi-colon.

The value of the `port` element must match the value configured for the remote attribute of the port element of the `notification-server` element.

For example:

- Configure host1 through host5:

      <nodes list="host1.com:6200,host2.com:6200,host3.com:6200"/>
      <nodes list="host4.com:6200,host5.com:6200"/>

- Configure a host that has two names:

      <nodes list="hostnameA.com;hostnameB.com:6200"/>

<discover>

Required: false
Default: none
Parents: topology
Attributes: list

The `discover` element provides a list of discovery service addresses. The local OPMN server will use the discover element to find and connect with remote OPMN servers in the same cluster. You can configure multiple discover elements.

list="list-of-services"

Required: true
Default: none
Valid Values: a list of discovery multi-cast addresses or a discovery OPMN host addresses. A comma must be used to separate the list of services.

Each service entry represents a discovery resource through which the local OPMN server will locate remote OPMN servers in the same cluster. Each OPMN server in a discovered topology will automatically manage its connections to other OPMN servers in the same topology. A service may be one of two types: a multicast node or a host node.

The syntax for the multicast node is `*node`. `*node` is a multi-cast IP address (or host name) and port pair (refer to nodes). OPMN will treat each unique *node entry as a separate topology of instances to join, although typically any given OPMN server will participate in only a single discover topology.

For example:

    <discover list="*225.0.0.37:8205"/>

The multicast address must be within the valid address range, which is 224.0.0.1 to 239.255.255.255. The asterisk (`*`) preceding the IP address is critical, because it informs OPMN that the value specified is a multicast address.

The syntax for the discover server node is node. node is an IP address (or host name) and OPMN remote port pair for an OPMN instance in the cluster that will serve as a discovery host in a topology. Each topology may have multiple discovery servers configured.

For example:

    <discover list="host1.com:6200"/>

Within each discover topology, OPMN will maintain a circular connection of servers. For clusters with groups of instances in locations remote from one another, instances should be grouped in separate topologies based upon location, in which case, the separate topologies must be joined through the gateway mechanism.

For discovery topology loops with large numbers of instances, OPMN will automatically break the circular connection loop into smaller sub loops in order to minimize latency from passing a notification from server to server. By default, OPMN will auto-break a circular loop when the number of nodes exceeds 16. You can configure this auto-break threshold by prefacing the discovery list with a `[number]` prefix, where `number` is the maximum number of instances OPMN should allow in a topology loop before breaking it into multiple loops. The minimum value for number is eight.

For example:

- Set the auto-break number to 8 for a discovery multi-cast topology:

      <discover list="*[8]225.0.0.37:8205"/>

- Set the auto-break number to 8 for a discovery host topology:

      <discover list="[8]host1.com:6200,host2.com:6200"/>

<gateway>

Required: false
Default: none
Parents: topology
Attributes: list

The `gateway` element is used to connect isolated discovery topologies. You can configure multiple gateway elements.

list="list-of-gateways"

Required: true
Default: none
Valid Values: a list of gateways. Each gateway represents a link or set of links between two OPMN discovery topologies. Each listed gateway must be separated by a comma.

The gateway syntax is `source/target`.

The `source/target` are lists of node entries. Each node entry on the list is separated by an ampersand (&). For more information refer to nodes. Each OPMN server listed in the source will connect to each OPMN server listed in the target. If the target is omitted, then it is assumed to be the same as the source. OPMN servers that are not listed in the source ignore the gateway specification.

For example:

The OPMN server on host1a is part of a discovery topology that is isolated to subnet subA, and has been selected to be the gateway instance between that topology and the discovery topology isolated on subnet subB. The OPMN server on host1b is part of a discovery topology that is isolated to subnet subB, and has been selected to be the gateway instance between that topology and the discovery topology isolated on subnet subA.

    <gateway list="host1a.subA.com:6200&host1b.subB.com:6200/"/>

With this configuration, OPMN server `host1a.subA.com:6200` will connect to OPMN server `host1b.subB.com:6200`, and OPMN server `host1b.subB.com:6200` will connect to OPMN server `host1a.subA.com:6200`.

For maximum redundancy you may wish to configure more than one host as the gateway for each discovery topology.

For example:

The OPMN server on host1a is part of a discovery topology that is isolated to subnet subA, and has been selected to be the gateway instance between that topology and the discovery topology isolated on subnet subB. The OPMN server on host1b is part of a discovery topology that is isolated to subnet subB, and has been selected to be the gateway instance between that topology and the discovery topology isolated on subnet subA.

This is the same as the previous example, but with two hosts configured from each subnet.

    <gateway list="host1a.subA.com:6200&host2a.subA.com:6200&host1b.subB.com:6200&host2b.subB.com:6200/"/>

However with this configuration the two instances on subnet A will always connect to one another and the two nodes on subnet B will always connect to one another, which may result in uneccessary connection overhead.

A more precise configuration requires two separate gateway elements:

    <gateway list="host1a.subA.com:6200&host2a.subA.com:6200/host1b.subB.com:6200&host2b.subB.com:6200"/>
    <gateway list="host1b.subB.com:6200&host2b.subB.com:6200/host1a.subA.com:6200&host2a.subA.com:6200"/>

Now the instances on the same subnet will only connect to one another if needed.

<process-manager>

Required: true
Default: none
Parents: <opmn>
Attributes: `insecure-remote-requests`

The `process-manager` contains the configuration definitions for the PM portion of OPMN.

insecure-remote-requests="boolean"

Required: false
Default: false
Valid Values: `true` or `false`

The `insecure-remote-request` attribute is a security check which disables requests until security features are configured. By default OPMN will only allow start, stop, restart, shutdown and reload requests rerouted from remote OPMN servers if ONS SSL is `enabled` and a wallet file is configured for authentication.

Note: Setting the `insecure-remote-request` attribute to `true` overrides that security check and enables these requests to be issued remotely with no security features configured. Setting the insecure-remote-request attribute to `true` is a major security risk and should only be done for testing purposes with all connected OPMN servers behind a well secured fire wall or completely disconnected from any external network.

<process-modules>

Required: true
Default: none
Parents: <process-manager>
Attributes: none

Each `process module` is designed to support a specific set of `process-type` elements; it is only required if the `process-type` elements are configured. The PM dynamically loads in a library for each specified `process module`.

<module>

Required: true
Default: none
Parents: <process-modules>
Attributes:`path, tag, status, cron`

The `module` element is used to provide `process-type` specific support for the PM. Each module is implemented as a shared library. The module exports a set of standard functions and uses the PM `process module` API. A module must provide a list of the `process-types` it supports. Only one configured `process module` may list a specific `process-type`. No two modules can list the same `process-type`.

path="path"

Required: true
Default: none
Valid Values: The path name for the module shared library.

The `path` attribute must specify the path name of the shared library file. The library file has the system suffix of `.so` for Linux and .`dll` for Microsoft Windows. The suffix may be omitted and OPMN will automatically append it. `ORACLE_HOME` may be used when specifying the path name.

tag="tag-id"

Required: false
Default: The value specified by the path element.
Valid Values: A string uniquely identifying the module.

The tag attribute identifies the module. A module may report its tag value when logging errors to the PM log file or as part of the response to a request. While optional, it is a good idea to set this attribute to a meaningful value to help track any issues with process management.

status="state"

Required: false
Default: `enabled`
Valid Values: `critical, enabled, or disabled`

A module may be `enabled`, in which case PM loads in its shared library when it starts and calls the module's initialization functions, or `disabled` in which case the module entry is completely ignored. If the module `process-types` are configured in the `opmn.xml` file they must also be `disabled`. The `critical` state is the same as `enabled`, except that OPMN will terminate with a fatal error code if the module initialization fails.

cron="interval"

Required: false
Default: none
Valid Values: An integer.

Specify the interval in seconds between calls to the module's `cron` callback function. Configuring a `cron` interval for a module that does not support the `cron` callback is not allowed. Unless you have designed the module, you should neither add nor alter this attribute.

<module-data>

Required: false
Default: none
Parents: <module>, <ias-instance>, <ias-component>, <dependencies>, <process-set>
Attributes: none

The `module-data` blocks are used to define module specific name-value pairs that are meaningful only to a specific module. Each `module-data` block is organized into categories, which contain the name-value data pairs.

The `module-data` blocks can be defined for multiple elements within `the opmn.xml file`, and OPMN will create an aggregate `module-data` block at the `process-set` level that contains all values defined at or above it. If multiple definitions exist in this hierarchy with the same `category id` and `data id`, the value defined at the lowest level is used.

Table 6-5 illustrates the `module-data` defined at each level in the hierarchy (with the highest level displayed at the top) and the resultant union at the `process-set` level of all of the `module-data` definitions:

Table 6-5 module-data Hierarchy

Module | Definition
--- | ---
`ias-instance` |
    <category id="CatA">
       <data id= "DataAA" value="aaaa"/>
    </category>
    ias-component
    <category id="CatA">
       <data id= "DataAB" value="abab"/>
    </category>
    <category id="CatB">
       <data id= "DataBA" value="baba"/>
    </category>
    module
    <category id="CatA">
       <data id= "DataAC" value="acac"/>
    </category>
    process-type
    <category id="CatA">
       <data id= "DataAA" value="XXXX"/>
    </category>
    process-set
    <category id="CatB">
       <data id= "DataBB" value="bbbb"/>
    </category>
    RESULT
    <category id="CatA">
       <data id= "DataAA" value="XXXX"/>
       <data id= "DataAB" value="abab"/>
       <data id= "DataAC" value="acac"/>
    </category>
    <category id="CatB">
       <data id= "DataBA" value="baba"/>
       <data id= "DataBB" value="bbbb"/>
    </category>

<category>

Required: true
Default: none
Parents: <module-data>
Attributes: `id`

The `category` element is an organizational level within a `module-data` block.

id="id"

Required: true
Default: none
Valid Values: A string.

This `id` string identifies a data category. Each `category id` within a single `module-data` block must be unique, but multiple `module-data` blocks may contain the same `data category ids`, in which case the categories are considered to be related.

<data>

Required: true
Default: none
Parents: <category>
Attributes: `id, value, process-conversion`

A data name value definition within a `module-data` category.

id="id"

Required: true
Default: none
Valid Values: A string.

This string identifies a data attribute. Each `data id` within a single category must be unique, but multiple categories may contain the same data identifications. Data elements with the same identification as other data elements, that are defined in different categories with the same identification, are related.

value="value"

Required: true
Default: none
Valid Values: A string.

The value string associated with the data element `id.` Any environment variable defined anywhere within the scope of the `process-set` (any level at or above the `process-set`) in which the data value is defined (again, any level at or above the `process-set`) referenced within the value string as `$variable` or `%variable%` will be expanded to the variable value.

process-conversion="boolean"

Required: false
Default: `true`
Valid Values: `true` or `false`

The `process-conversion` attribute enables you to set the separator character. By default OPMN will convert slashes in the data value string to be those of the directory path separator character for the system on which OPMN is running (on UNIX each \ character is converted to / and on Windows each / is converted to \). Set this attribute to false to disable this conversion.

Note that if process-conversion is true, OPMN uses the ^ character as an escape character to disable process conversion for the following character, and so ^/ on a Windows system will yield a / in the string. Specify two ^ characters if you need to specify the ^ character in the resultant string: ^^ yields ^.

<data id="routing-id">

Required: false
Default: none
Parents: category
Attributes: value

The `data id` defines the value for the routing-id module.

For more information about the `routing-id` refer to the Oracle HTTP Server Administrator's Guide.

value="routing id"

Required: true
Default: none
Valid Values: Any string.

The Routing ID specifies a routing relationship between OC4J and Oracle HTTP Server. In other words, an Oracle HTTP Server routes to every OC4J that it shares a routing ID with. Out of the box, the routing ID is specified as a module data under the `ias-instance` in the `opmn.xml` file. The value of the default `routing-id` is `g_rt_id`. Because of the hierarchical nature of the opmn.xml file, every component configured in the opmn.xml file inherits the configured routing ID. The user can configure a separate routing ID for any Oracle HTTP Server or OC4J by configuring a routing ID at a lower level in the opmn.xml file. As with most entities in the opmn.xml file, like entities configured at a lower level override those configured at a higher level.

<module-id>

Required: true
Default: none
Parents: <module>
Attributes: `id`

The `module-id` name defines the type of process and associates the configuration with a `process module`.

This identifier is used by each `process-type` to specify which module supports it. A module may be configured with multiple `module-ids`.

id="module-id"

Required: true
Default: none
Valid Values: A string.

<ias-instance>

Required: true
Default: none
Parents:<process-manager>
Attributes: `id`, `ORACLE_HOME`

The configuration definitions for an Oracle Application Server instance. Only one `ias-instance` is supported for each OPMN.

`id` = `ias-instance-id;` `name` =`ias-instance-name`; `ORACLE_HOME` = "path name"

id="ias-instance-name"

Required: true
Default: none
Valid Values: A string.

The string specifies the `ias-instance` id.

name="ias-instance-name"

Required: false
Default: `ias-instance``-id`
Valid Values: A string.

The `name` string specifies the `ias-instance` name, and it is this value that is used to identify the instance for a scoped OPMN request.

ORACLE_HOME="path"

Required: true
Default: none
Valid Values: A path string.

This `ORACLE+_HOME` path attribute must be the `ORACLE_HOME` equivalent for the Oracle Application Server instance.

<environment>

Required: true
Default: Refer to the following paragraph.
Parents: ias-instance, ias-component,process-type, process-set
Attributes: none

Like `module-data` blocks, `environment` blocks can be defined for multiple elements within the `opmn.xml` file, and OPMN will create an aggregate `environment` block at the `process-set` level that contains all values defined at, or above it. If multiple definitions exist in the hierarchy with the same `id`, the value defined at the lowest level is used.

Note: OPMN sets the following default environment variables at the `ias-instance` level, with the values extracted either from the `ias-instance` configuration or from the OPMN run time environment: Linux: `ORACLE_HOME, ORACLE_NLS, OPMN_ENV_LC_ALL, OPMN_ENV_LANG, OPMN_ENV_NLS_LANG, SHELL` Microsoft Windows: `COMSPEC, SYSTEM_DRIVE, and SYSTEM_ROOT`

<variable>

Required: true
Default: none
Parents: <environment>
Attributes:`id, value, append, process-conversion`

The variable element defines the environment variable name and value.

id="id"

Required: true
Default: none
Valid Values: A string.

The `id` is the environment variable name. An `environment id` may be duplicated within an `environment` block, with the last defined value taking priority over earlier definitions. The same `environment id` may be defined within `environment` blocks for different elements, and the value defined at the lowest level will take priority over values defined at higher levels.

value="value"

Required: true
Default: none
Valid Values: A string.

The environment value. Environment variables referenced within the value string as `$variable` or `%variable%` will be expanded to the variable value. The same environment variable may reference itself to use a definition defined at a higher level, or earlier within this same `environment` block.

You may use the Linux shell syntax for referencing an environment variable, $`variable` or `${variable}`, or the Microsoft Windows format `%variable%`. Referenced variables that have not been defined remain in place as referenced, and so `value="_notdefined_"` would remain unchanged.

For example, the following environment block yields a value for `accumulate` of "`foobar`".

    <environment>
       <variable id="accumulate" value="foo">
       <variable id="accumulate" value="${accumulate}bar">
    </environment>

append="boolean"

Required: false
Default: false
Valid Values: `true` or `false`

You can force OPMN to append the new environment variable value to the previously defined value, with the system library delimeter placed in between the two values (':' for Linux and ';' for Microsoft Windows) by specifying a value of `true` for this attribute. This is useful when assembling a value for a variable such as `CLASSPATH`.

For example, the following `environment` block yields a value for `CLASSPATH` of "`/foo:/bar`" on a Linux system.

    <environment>
       <variable id="CLASSPATH" value="/foo">
       <variable id="CLASSPATH" value="/bar" append="true">
    </environment>

process-conversion="boolean"

Required: false
Default: `true`
Valid Values: `true` or `false`

<rmd-definitions>

Default: none
Parents: ias-instance, ias-component,process-type, process-set, process-manager
Attributes: none

The RMD definitions provide the ability to have process management commands issued based on system conditions according to a set of user-configured directives. The system conditions that can be taken into account include any DMS metrics that are available within the Oracle Application Server instance. This includes preset metrics that are always present as well as metrics that are defined and implemented by other applications.

RMD definitions are either:

- Hierarchical: if defined at the `ias-instance` level or lower. Hierarchical RMDs assume an association within the OPMN configuration components in which they are defined.

- Global: if defined at the process-manager level. Global RMDs require explicit OPMN component specifications.

<rmd>

Required: true
Default: none
Parents: rmd-definitions
Attributes: name, description, interval

A directive specifying a condition and a set of actions to take when the condition evaluates true and an optional set of `exceptions` to enact should any action fail.

name="name"

Required: true
Default: none
Valid Values: An identifier for the RMD.

For hierarchical RMDs the name must be unique within the hierarchical component in which it was defined. For global RMDs the name must be unique within the `global rmd-definitions` block.

description="description"

Required: false
Default: none
Valid Values: A string.

A description of the RMD.

interval="interval"

Required: false
Default: 30
Valid Values: An integer greater than or equal to five or the string `"joinons` `group`".

The `interval` attribute specifies the period between conditional checks for the RMD. The actual time elapsed between checks may be somewhat greater than the configured `interval` depending upon system load. A smaller value yields more frequent checks of the RMD at the expense of additional system resources.

If `interval` is set to the string "`joinons` `group`", then the RMD is evaluated when the ONS layer detects that the OPMN server has joined a new ONS topology group.

<conditional>

Required: true (false if `rmd` attribute interval="`joinons` `group`")
Default: none
Parents: rmd
Attributes: CDATA

The `conditional` element contains the conditional statement to be evaluated by OPMN.

<![CDATA[statement]]/>

Required: true
Default: none
Valid Values: A string (the conditional statement).

The CDATA conditional statement describes a state of the system that will trigger an `action`. The statement consists of a logical combination of comparisons between values. Like all other aspects of OPMN, conditionals are case sensitive. The values that may be used can be the following types:

- DMS metrics available from the OPMN DMS tree

- Constant values (for example, 500000)

- Temporal values (for example, 5 p.m.)

DMS metrics are described based on their location in the OPMN DMS tree. The description can be a fully qualified path name, a hierarchical relative reference, or a global absolute reference.

A fully qualified path name to the target metric begins with a '/'. The fully qualified path name includes the full path name to the OPMN instance. The OPMN instance prefix is automatically added to fully qualified path names. For example:

    /pm/host_statistics/freePhysicalMem

Metrics with fully qualified path names can be referenced by both hierarchical and global RMD `conditionals`.

If the RMD element is hierarchical, then the metric must use a relative path name form. For example:

    [process-set].numProcs

which specifies the `numProcs` metric for any `process-set` in the hierarchy for which the RMD is evaluated. The exception to this rule is the `application` metric, in which the path name may be specified as either relative or absolute. The following component specifications are allowed for hierarchical RMD `conditionals`:

- `[ias-component]` Refers to the `ias-component` element within the hierarchy of the `opmn.xml` file.

- `[process-type]` Refers to the `process-type` element within the hierarchy of the opmn.xml file.

- `[process-set]` Refers to the `process-set` element within the hierarchy of the opmn.xml file

- `[process]` Refers to the `process` element within the run time hierarchy

- `[application]` Refers to the application element within the run time hierarchy

- `[application=<app>]` Refers to the application <app>.

If the RMD element is global, then the metric must be an absolute description of a starting point followed by a relative path name. For example:

    [ias-component=HTTP_Server][process-set=HTTP_Server].numProcs

specifies the metric `numProcs` for the `process-set` HTTP_Server that belongs to the ias-component=HTTP_Server. The exceptions to this rule are:

- `process:`must always be specified as as relative

- `application`: may be specified as either relative or absolute.

The following component specifications are allowed for global RMD conditional`s`:

- `[ias-component=<comp>]` Refers to the ias-component `<comp>` in the opmn.xml file

- `[process-type=<ptype>]` Refers to the process-type `<ptype>` in the opmn.xml file

- `[process-set=<pset>]` Refers to the `process-set` `<pset>` in the opmn.xml file.

- `[process]` Refers to a process

- `[application]` Refers to an application

- `[application=<app>]` Refers to the application `<app>`.

As with OPMN process requests, components not specified in the directive are assumed to be wildcards; thus a global RMD referencing [`process-set`=home] would be evaluated for every `process-set` with the `id` "`home`" configured in the opmn.xml file.

A conditional cannot reference more than one OPMN logical component. For example, the same conditional cannot reference `[ias-component=HTTP_Server]`. Similarly, references to lower configuration components must not belong to a referenced higher component within the same conditional.

For hierarchical and global RMDs multiple bracketed sections can be specified but each subsequent section must further narrow the tree. That is, the order must progress from the top of the tree toward the leaf. For example, a `process` cannot appear before an `ias-component`.

Constant values must be simple numeric values, including decimal values. When comparing a constant value with a DMS metric, the constant must have the same units as the DMS metric it is being compared to. OPMN will convert the numeric values so that the values are similar.

Temporal values consist of a 24 hour format (hh:mm) time combined with an optional day of the week indicator. The day of the week abbreviations are `sun, mon, tue, wed, thu, fri` and `sat`. The day of the week indicators can be a single value, a comma separated list, or a dashed inclusive list. For example:

- `17:00` Daily at 5 PM

- `[mon,wed,fri].05:00` Monday, Wednesday, Friday at 5 AM

- `[mon-fri].21:45` Week days at 9:45 PM

The current time is represented by the key word `{time}`. A time comparison is evaluated false if the day of the week specified on the left of the operator does not include a day of the week specified on the right.

By default, the day of the week is only evaluated if the values are equal. If the day of the week evaluation is true then the time value is also evaluated.

You can force the comparison to be made against a single day of the week by appending the '@' character after the day, with Sunday (sun) having the value 0 and Saturday (sat) 6. For example:

- `{time} < [wed].12:00` Evaluates true only on Wednesday from 00:00 until noon

- `{time} < [wed@].12:00` Evaluates true from Sunday at 00:00 until Wednesday at noon

Comparisons between values include less than (<), less than, or equal to (<=), greater than (>), greater than or equal to (>=), equals (=), or not equals (!=).

String values may also be specified between quotes (using the single quote character "'"), but the only allowable operators are equals (=) and not equals (!=).

Comparisons may be logically combined using the operators and (&) or (|), and grouping (parentheses). The logical operator (!) can be placed before any logical group of comparisons to negate the result of the outcome.

The key word `{duration(interval)}` may also be used to indicate that a conditional should only trigger if it has evaluated as true over the specified time interval (expressed in seconds). It is important to note that the conditional is only evaluated on a periodic basis, and specifying the duration value will force the conditional to only trigger if the evaluations over the time period meet the conditional value. This is an approximation of ensuring that the condition holds true over the entire time period. The accuracy of this approximation depends on the ratio of the duration interval value to the evaluation configured interval. When a conditional is evaluated as true, all durations for that evaluation are reset. When a conditional evaluates false, any duration that was not encountered during the evaluation is also reset.

If interval is set to the string `joinonsgroup`, then the conditional is only evaluated when the ONS layer detects that the OPMN server has joined a new ONS topology group. If the conditional is omitted, then the RMD evaluation will always be true. If the conditional is defined, then `process` level references are not allowed and the duration key word should not be used. For example:

- If the heap size of a JVM has exceeded 500 Megabytes (global RMD):

  `[process-set=home][process].heapSize > 500000`

- If the time is 5 PM on a weekday:

  `{time} = [Mon-Fri].1700`

If the average request time is greater than 500 milliseconds for at least 60 seconds, and there are less then four processes running for the `process-set` at which the hierarchical RMD was configured:

    [process].avgReqTime > 500 {duration(60)})&([process-set].numProcs < 4)

If there has been less than 50 MBs of free system memory for the last three minutes:

    /pm/host_statistics.freePhysicalMemory < 50000 {duration(180)}

<action>

Required: true
Default: none
Parents: rmd
Attributes: value

The `action` element indicates an action to be taken if the `conditional` evaluates true.

value=request

Required: true
Default: none
Valid Values: A string (the request).

An `action` can be either a process management request, or a specified program to execute, when a RMD conditional evaluates true. An RMD may have multiple `action`s, and they are executed sequentially in the order in which they are defined.

If an `action` request returns a value other than success (200), or the executed program exits with a status other than 0, then the remaining `actions` for the RMD will be skipped, and any configured `exceptions` will be performed.

An RMD will not be evaluated while either its `actions` or `exceptions` are in progress.

The possible `actions` for an RMD are:

- `start:`perform a `start` request with the given argument list

- `restart`: perform a restart request with the given argument list

- `stop`: perform a stop request with the given argument list

- `exec` : execute the given program or script with the listed arguments

The targets for the `start`, `restart,` and `stop` requests are assumed to be relative to the OPMN components referenced in the RMD conditional. Key words representing these components should be used to narrow the scope of the request.

The following set of key words, with expansion, is provided:

- `{ias-component} ias-component=<comp>`

- `{process-type} process-type=<ptype`>

- `{process-set} process-set=<pset>`

- {`process`}`uniqueid=<uid>`

- `{application} application=<app>`

For `start`, `restart,` and `stop` `actions`, the key word {`process`} should not be used with the other key words because OPMN requests do not allow this combination.

In addition the `exec` `action` can use the `{pid}` key word, which expands to `pid=<pid>` if the `conditional` refers to a `process-set` or `process`.

Note that an `action` cannot reference a key word for an OPMN component at a level below the lowest OPMN component referenced in the `conditional` (if the `conditional` only references an ias-component, then the `action` can only use the {ias-component} key word, for example). The exception to this rule is that an `action` may reference {`process`} if the `conditional` references a `process-set`, but this will force the RMD to be evaluated at the `process` level and not the `process-set` level.

The results of the `action` requests are logged in the OPMN process manager log (the beginning and completion of the request with completion status at level 4, and full results at level 5). The `stdout` and `stderr` output of executable programs or scripts are sent to `$ORACLE_HOME``/opmn/logs/rmd.out`. There is no rotation performed on the `rmd.out` file. Other programs and scripts should maintain and use their own log files and not print output using the `stdout` and `stderr` file descriptors.

The following are some `action` examples:

- Start another JVM in the home OC4J instance within a hierarchical RMD defined within the `ORACLE_HOME` instance (note the `process-set` must be configured with `minprocs/maxprocs`):

- `start {ias-component}{process-type}{process-set} numprocs=1`

  Restart a JVM in the "home" instance within a hierarchical RMD defined within the "home" instance:

- `restart {process}`

  Stop the entire`ias-component` referred to by the RMD `conditional`:

- `stop {ias-component}`

  Execute the given program and pass in the referenced `process` UID and pid:

- `exec` `$ORACLE_HOME``/mybin/report.sh "rmd triggered" {process} {pid}`

timeout=timeout

Required: false
Default: the configured (or default) timeout for the OPMN request for affected components (see following paragraph)
Valid Values: An integer > 0 and < 3600

A timeout value can be configured for each `action`. The default timeout for s`tart, restart,` and `stop` `actions` is the configured (or default) timeout for the OPMN request on these components. The default timeout for `exec` is the configured (or default) timeout for the OPMN request on these components. The default timeout for `exec` `action` is 30 seconds.

<exception>

Required: false
Default: none
Parents: rmd
Attributes: value

An action to be taken if the any of the `actions` definitions for the RMD fail.

The configuration is identical to `action`.

If an `exception` request returns a value other than success (200), or the executed program exits with a status other than 0, then the remaining `exceptions` for the RMD will be skipped.

<ias-component>

Required: true
Default: none
Parents:<ias-instance>
Attributes:`id, id-matching, status`

An `ias-component` is a logical grouping of `process-type` for administrative purposes.

id="component-id"

Required: true
Default: none
Valid Values: a string

The `id` attribute uniquely identifies the `ias-component` within the `ias-instance`.

id-matching="boolean"

Required: false
Default: false
Valid Values: `true` or `false`

By default OPMN requests that do not specify `ias-components` match all configured `ias-components`, unless the `id-matching` attribute for a component is set to `true`, in which case the request must explicitly include the `ias-component id` in order to affect the `ias-component` or any `process-type` or `process-set` configured for that `ias-component`.

status="state"

Required: false
Default: `enabled`
Valid Values: `enabled` or `disabled`

An `ias-component` may be `enabled`, in which case OPMN parses all of its configured attributes and elements and enables requests to operate upon it, or `disabled`, in which case the `ias-component` entry is completely ignored.

<dependencies>

Required: false
Default: none
Parents: <ias-component>, <process-type>, <process-set>
Attributes: none

OPMN uses `dependencies` to determine if a process should be started or not. Like `module-data` and `environment` block, dependencies blocks can be defined for multiple elements within the `opmn.xml` file, and OPMN will create an aggregate dependency list at the `process-set` level that contains all dependencies defined at or above it. If duplicate dependencies are defined at different levels, then duplicate checks on that dependency will be made before starting a process. OPMN will create an aggregate dependency list at the `process-set` level that contains all dependencies defined at or above it. If duplicate dependencies are defined at different levels, then duplicate checks on the dependency will be made before starting a process.

There are two primary types of dependencies: external and internal. External dependencies are for those resources not managed by OPMN. For example: Application Server Control Console.

An external program is executed by OPMN to perform the check on the resource. Internal dependencies are for OPMN-managed processes (unit), which may include processes managed on a remote OPMN.

OPMN maintains a cache of dependency states which contains the last known state of each dependency, and the time it was last checked. A `cache-timeout` parameter for each dependency enables users to specify how long to use its state in the cache, or if it should be used at all. Similarly, a general timeout parameter for each dependency will determine how long OPMN will wait for a status update from that dependency before aborting the dependency check and the process start.

OPMN checks dependencies in the order in which they are declared. The traversal of the list of dependencies concludes either with the full sequence of successful checks, the dependency is available, or the first check failure, the dependency is not available, or the dependency check timed out.

<database>

Required: false
Default: none
Parents: <dependencies>
Attributes: `db-connect-info, infrastructure-key, timeout, cache-timeout`

The `database` element specifies the database to check. Either `db-connect-info` or `infrastructure-key` is used to identify the database.

db-connect-info="connect"

Required: true if `infrastructure-key` is not specified.
Default: none
Valid Values: A string

The `db-connect-info` attribute is the string required to connect to the database. The string can be in either of the following formats:

- `<host>:<port>/<service name>`

- `(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=<host>) (PORT=<port>)) (CONNECT_DATA=(SERVICE_NAME=<service name>)))`

For example:

`pdsundev7:1521/asdb.us.oracle.com`

Database connection information can be found in `$``ORACLE_HOME``/network/admin/tnsnames.ora`.

infrastructure-key="key"

Required: true if `db-connect` is not specified.
Default: none
Valid Values: A string

The `infrastructure key` attribute is required to identify the database.

timeout="depend-timeout"

Required: false
Default: `1200`
Valid Values: An integer

The `timeout` attribute specifies in seconds how long OPMN will wait for a dependency check to complete. If the check takes longer than the configured timeout, then OPMN will consider the check to have failed.

cache-timeout="cache-timeout"

Required: false
Default: `600`
Valid Values: An integer

The `cache-timeout` attribute specifies how long in seconds OPMN will use the current "up" status for the dependency entry in the cache. If the last successful dependency check was within the prescribed number of seconds from the current check, then the dependency check is instantly flagged as successful, otherwise another dependency check will be performed. Note that the `cache-timeout` is only for the last successful check of the dependency, and if the previous check failed, another access of the dependency will be performed for this check. A value of 0 indicates OPMN will always perform the check.

<OID>

Required: false
Default: none
Parents:<dependencies>
Attributes: `address, infrastructure, timeout, cache-timeout`

The `<OID>` element specifies the Oracle Internet Directory service to check either an address string for a specific Oracle Internet Directory, or that the OracleAS Infrastructure flag is set to `true` to use the default infrastructure Oracle Internet Directory.

address="address"

Required: true
Default: none
Valid Values: A string

The `address` element is the address string required to connect to Oracle Internet Directory.

infrastructure="boolean"

Required: true if `address` is not set.
Default: none
Valid Values: `true` or `false`

Use the default infrastructure Oracle Internet Directory for the Oracle Application Server instance.

<ssl>

Required: false
Default: none
Parents: <OID>
Attributes: `enabled, wallet-file, wallet-password`

The SSL information for the Oracle Internet Directory connection.

enabled="boolean"

Required: true
Default: none
Valid Values: `true` or `false`

To enable SSL on the Oracle Internet Directory connection, set the `enabled` attribute to `true`.

wallet-file="path"

Required: true
Default: none
Valid Values: A valid path name

The path name to the wallet file for authentication of the Oracle Internet Directory connection. The`$ORACLE_HOME` directory location may be used.

wallet-password="password"

Required: false
Default: none
Valid Values: A string

The `wallet-password` attribute is the password for the specified wallet-file.

timeout="depend-timeout"

Required: false
Default: `1200`
Valid Values: An integer

The`timeout` attribute specifies in seconds how long OPMN will wait for a dependency check to complete. If the check takes longer than the configured timeout, then OPMN considers the check to have failed.

cache-timeout="cache-timeout"

Required: false
Default: `600`
Valid Values: An integer

The `cache-timeout` attribute specifies how long in seconds OPMN will use the current "up" status for the dependency entry in the cache. If the last successful dependency check was within the prescribed number of seconds from the current check, then the dependency check is flagged as successful. Otherwise, OPMN performs another dependency check. The `cache-timeout` is only for the last successful check of the dependency. If the previous check failed, OPMN performs another access of the dependency check. A value of 0 indicates OPMN will always perform the check.

<OSSO>

Required: false
Default: none
Parents: <dependencies>
Attributes: `host, port, URI, timeout, cache-timeout`

The `OSSO` element specifies the OracleAS Single Sign-On service to check.

host="hostname"

Required: true
Default: none
Valid Values: A string

The `host` attribute is the hostname for the OracleAS Single Sign-On connection.

port="port"

Required: true
Default: none
Valid Values: A port number

The `port` attribute is the port for the OracleAS Single Sign-On connection.

URI="uri"

Required: true
Default: none
Valid Values: A string

The `URI` attribute is the URI for the OracleAS Single Sign-On connection.

<ssl>

Required: false
Default: none
Parents: <OSSO>
Attributes: `enabled, wallet-file, wallet-password`

The `ssl` element is the SSL information for the OracleAS Single Sign-On connection.

enabled="boolean"

Required: true
Default: none
Valid Values: `true` or `false`

The `enabled` attribute enables the SSL connection OracleAS Single Sign-On. To enable the connection set this attribute to `true`.

wallet-file="path"

Required: true
Default: none
Valid Values: A path name

The `wallet-file` attribute is the path name to the wallet file for authentication of the OracleAS Single Sign-On connection. The `ORACLE_HOME` value may be used.

wallet-password="password"

Required: false
Default: none
Valid Values: A string

The `wallet-password` is the password for the specified wallet-file.

timeout="depend-timeout"

Required: false
Default: `1200`
Valid Values: An integer

The`timeout` attribute specifies in seconds how long OPMN will wait for a dependency check to complete. If the check takes longer than the configured timeout, then OPMN considers the check to have failed.

cache-timeout="cache-timeout"

Required: false
Default: `600`
Valid Values: An integer

The `cache-timeout` attribute specifies how long in seconds OPMN will use the current "up" status for the dependency entry in the cache. If the last successful dependency check was within the prescribed number of seconds from the current check, then the dependency check is flagged as successful. Otherwise, OPMN performs another dependency check. The `cache-timeout` is only for the last successful check of the dependency. If the previous check failed, OPMN performs another dependency check. A value of 0 indicates OPMN will always perform the check.

<managed-process>

Required: false
Default: none
Parents: <dependencies>
Attributes: `ias-instance, ias-component, process-type, process-set, autostart, autostop, timeout, cache-timeout`

The `managed-process` attribute specifies the managed process to check. A process for `process-type` or `process-set` does not start unless the specified dependency managed process is active. Circular dependencies are detected and rejected for local managed processes, but not for remote managed processes; this may result in a dependency check deadlock, which times out.

ias-instance="ias-instance-id"

Required: false
Default: The `ias-instance` of the current `process-type` or `process-set`.
Valid Values: A string

The `ias-instance` for the managed process dependency. If the specified `ias-instance` is not managed by the current OPMN, it is assumed to be a remote managed process dependency.

ias-component="ias-component-id"

Required: true
Default: none
Valid Values: A string

The `ias-component` for the managed process dependency.

process-type="process-type-id"

Required: true
Default: none
Valid Values: A string

The `process-type-id` for the managed process dependency.

process-set="process-set-id"

Required: true
Default: none
Valid Values: A string

The `process-set-id` for the managed process dependency.

autostart="boolean"

Required: false
Default: false
Valid Values: `true` or `false`

The `autostart` attribute is used for the managed process dependency. If the process is not running when the check is performed, the `autostart` element will OPMN to attempt to start it.

autostop="boolean"

Required: false
Default: false
Valid Values: `true` or `false`

When the managed process dependency is stopped, then stop the managed process. The attribute is always `false` for remote managed process dependencies.

timeout="depend-timeout"

Required: false
Default: `1200`
Valid Values: An integer

The `timeout` attribute specifies, in seconds, how long OPMN will wait for a dependency check to complete. If the check takes longer than the configured timeout, then OPMN considers the check to have failed.

cache-timeout="cache-timeout"

Required: false
Default: `600`
Valid Values: An integer

The `cache-timeout` attribute is only used for a process managed by a remote OPMN. The `cache-timeout` attribute specifies how long in seconds OPMN will use the current "up" status for the dependency entry in the cache. If the last timeout dependency check was within the prescribed number of seconds from the current check, then the dependency check is instantly flagged as successful, otherwise OPMN performs another dependency check. Note that the `cache-timeout` is only for the last successful check of the dependency, and if the previous check failed, OPMN another access of the dependency will be performed for this check. A value of 0 indicates OPMN will always perform the check.

Note: The `cache-timeout` is only for the last successful check of the dependency, and if the previous check failed, OPMN will perform another dependency check.

<process-type>

Required: true
Default: none
Parents: <ias-component>
Attributes: `id, module-id, status, working-dir`

A `process-type` is a grouping of `process-sets` that are supported by the same module.

id="process-type-id"

Required: true
Default: none
Valid Values: a string

The `id` attribute uniquely identifies the `process-type` within the `ias-component`.

module-id="module-id"

Required: true
Default: none
Valid Values: a string

The `module-id` attribute must map directly map to the `module-id` attribute that supports the `process-type`.

status="state"

Required: false
Default: `enabled`
Valid Values: `enabled` or `disabled`

A `process-type` may be `enabled`, in which case OPMN parses all of its configured attributes and elements and enables requests to operate upon it, or `disabled`, in which case the `process-type` entry is completely ignored and treated as if it were not listed in `the opmn.xml file`.

working-dir="path"

Required: false
Default: `ORACLE_HOME`
Valid Values: A path name

The `working-dir` path name specifies the working location that is set for managed processes created by the `process-type` element. If a `process-set` also defines a `working-dir` attribute, then the process-set path name takes precedence over the `process-type` path name. The`$ORACLE_HOME` directory may be used.

service-failover="num"

Required: false
Default: 0
Valid Values: An integer value > 0.

A `process-type` may be configured as a `service-failover` (if `num` is not zero), which represents a process that exists num times somewhere in the Oracle Application Server cluster when it is up. The implementation is limited such that only one process of this type will run on a single instance, and so the maximum number of processes for a specific `service-failover` in the cluster can never be more than the number of participating instances in the cluster. If the value of num is greater than the number of instances participating in this `service-failover` in the cluster and the `service-failover` is active (it has been started), then each participant added to the cluster will automatically start its `service-failover` process until the total number cluster wide is num.

A `service-failover` process can run on any instance participating in the service, which means each instance must have the service configured with the same `ias-component id`, `process-type id` and `process-set` `id`. To target the service itself, a request must specify both the `ias-component` and the `process-type` (it can also include the `process-set`).

A `service-failover` `process-type` can have only one `process-set`. Because the number of processes for a failover service is always 1, this `process-set` cannot specify `numprocs, minprocs`, or `maxprocs`.

A `service-failover` can be specified as a dependency (like any managed-process) or can specify dependencies. If specified as a dependency, the dependency check for a `service-failover` will evaluate true as soon as one process of this type is active anywhere in the cluster, regardless of the configured value for `num`.

service-weight="value"

Required: false
Default: 100
Valid Values: An integer value > 0.

The instances that run the actual `service-failover` processes are selected based upon the configured (or default) service-weight value. Instances with higher weights are selected over instances with lower weights. If a set of instances have the same weight for a service, then the configured number of instances are selected from the set to run the processes.

The `service-weight` attribute can only be specified if the `service-failover` attribute is set to a nonzero value.

<event-scripts>

Required: false
Default: none
Parents: <process-type>, <process-set>
Attributes: none
A configured `event script` is executed when a specific process related event has occurred. OPMN waits until the script completes or times out before proceeding with the next `action` for the process.
Table 6-6 shows event script arguments.

Table 6-6 Event Script Arguments

Option Name | Option Argument | Description
--- | --- | ---
`-timeStamp` | `<time>` | An integer value for the current `time` on the system (in seconds).
`-instanceName` | `<instance-name>` | The `instance-name` of the managed process.
`-componentId` | `<component-id>` | The `component-id` of the managed process.
`-processType` | `<process-type-id>` | The `process-type` of the managed process.
`-processSet` | `<process-set-id>` | The `process-set` of the managed process.
`-processIndex` | `<index>` | The `process-index` of the managed process.
-`stderr` Foot 1 | `<path>` | The path name for the `stderr` file pointer of the process.
-`stdout` Footref 1 | `<path>` | The path name for the `stdout` file pointer of the process. Note: this argument will only be given for a pre-start script if the start is part of a process restart request.
`-reason` | `<reason>` | A string indicating the reason script was executed. The `http_request` indicates the process `action` is the result of the user HTTP request to OPMN. The `non_http_request` indicates the process `action` was initiated by OPMN itself.
-`pid` Foot 2 | `<process-id>` | The operating system integer value given for the `process-id`.
-`startTime` Footref 2 | `<time>` | An integer value for the system start time of the process (in seconds).

Footnote 1 This argument will only be given for a pre-start script if the start is part of a process restart request. The pre-start event is triggered only prior to performing a start. A restart operation may be composed of a stop operation followed by a start operation. A start operation can occur as an operation all by itself or as a sub-operation of a restart.
Footnote 2 This argument is only available with pre-stop or post-crash event scripts.

<pre-start>

Required: false
Default: none
Parents: <event-scripts>
Attributes: `path`

OPMN runs the `pre-start` script after any configured dependency checks have been performed (and passed) and before the process is actually started. The timeout for the `pre-start` script is the timeout value configured for starting the process itself, and any time consumed by the execution of this script counts toward the process start timeout. If the script times out, the process will not be started and any associated HTTP request will fail.

Be cautious when you execute any OPMN process requests such as `start`, stop or restart within an event script. These requests are serialized at the `process-set` level. If the script invokes a request on a `process-set` on which the current request (or another already queued request) is operating, then the script will hang until it times out.

path="path"

Required: true
Default: none
Valid Values: The path name to the executable script.

The path name must specify either an executable program for which OPMN has execute permission, or a script file for which OPMN has both read and executable permission. The `ORACLE_HOME` value may be used.

<pre-stop>

Required: false
Default: none
Parents: <event-scripts>
Attributes: `path`

OPMN runs the specified script before stopping the associated process. The timeout for the script is the value configured for stopping the process itself. Any time consumed by the execution of the script counts toward the process stop timeout. If the script times out, any associated HTTP request will fail. However, OPMN will proceed with stopping the process.

Be cautious when you execute any OPMN process requests such as `start, stop,` or `restart`. These requests are serialized at the `process-set` level. If the script invokes a request on a `process-set` on which the current request (or another already queued request) is operating, then the script will hang until it times out.

path="path"

Required: true
Default: none
Valid Values: The path name to the executable script.

The `path` attribute must specify either an executable program for which OPMN has execute permission, or a script file for which OPMN has both read and executable permission. The`$ORACLE_HOME` directory may be used.

<post-crash>

Required: false
Default: none
Parents:<event-scripts>
Attributes: `path`

OPMN runs the specified script after the associated process has terminated unexpectedly. The timeout for the script is the timeout value configured for stopping the process itself. After the script has terminated OPMN schedules a replacement of the terminated process.

Be cautious when you execute any OPMN process requests such as `start`, stop or restart. These requests are serialized at the `process-set` level. If the script invokes a request on a `process-set` on which the current request (or another already queued request) is operating, then the script will hang until it times out.

path="path"

Required: true
Default: none
Valid Values: The path name to the executable script.

The `path` attribute must specify either an executable program for which OPMN has execute permission, or a script file for which OPMN has both read and executable permission. The`$ORACLE_HOME` directory may be used.

<start>

Required: false
Default: Refer to the values in the following paragraphs.
Parents: <process-type>, <process-set>
Attributes: `timeout, retry`

The `start` attribute contains the start parameters for a managed processes.

timeout="timeout"

Required: false
Default: `60`
Valid Values: An integer

The `timeout` attribute specifies the timeout value in seconds for the start of a managed process.

retry="num"

Required: false
Default: `0`
Valid Values: An integer

The `retry` attribute specifies the number of consecutive attempts that will be made to start the process for a single request.

<stop>

Required: false
Default: Refer to the values in the following paragraphs.
Parents: <process-type>, <process-set>
Attributes: `timeout`

The `stop` attribute specifies the stop parameters for managed processes.

timeout="timeout"

Required: false
Default: `30`
Valid Values: An integer

The `timeout` value in seconds for the stopping a managed process.

<restart>

Required: false
Default: Refer to the values in the following paragraphs.
Parents: <process-type>, ``<process-set>
Attributes:`timeout, retry`

The `restart` parameters for managed processes.

timeout="timeout"

Required: false
Default: `90`
Valid Values: An integer

The`timeout` value in seconds for the restart of a managed process.

retry="num"

Required: false
Default: `0`
Valid Values: An integer

The `retry` attribute is the number of consecutive attempts that will be made to restart the process for a single request.

<ping>

Required: false
Default: Refer to the values in the following paragraphs.
Parents: <process-type>`,` <process-set>
Attributes: `timeout, retry, interval`

The `ping` element is the ping parameters for managed processes.

timeout="timeout"

Required: false
Default: `20`
Valid Values: An integer

The `timeout` value in seconds for the ping of a managed process. Each module specifies a ping timeout.

retry="num"

Required: false
Default: `0`
Valid Values: An integer

The `retry` attribute is the number of consecutive ping failures that will be tolerated before the module declares the process unreachable and restarts it. Each module specifies ping retries.

interval="interval"

Required: false
Default: `20`
Valid Values: An integer

The `interval` attribute is the interval, in seconds, between each ping of a managed process.

<port>

Required: false
Default: none
Parents: <process-type>
Attributes: `id, range`

The `port` element provides a port management mechanism for modules to use. Each module uses the ports configured with `id`.

id="id"

Required: true
Default: none
Valid Values: A string

The `id` attribute identifies the range of ports for the `process-type`. Each module has its own list of required or optional `port` ids.

range="range"

Required: true
Default: none
Valid Values: A port range

The `port range` specifies which ports to use for the `id`.

Upon request from a module for a port number from the `id`, OPMN checks if a port in the range has been bound on the local system, and if it has not, it returns that port number back to the module. Syntax of the `port range` is a comma separated list of individual port numbers or a low-high range specification.

Examples:

Specify ports 5555, 6666, 7777, 8888, and 9999:

    range="5555,6666,7777,8888,9999"

Specify ports 4000 through 4250 (inclusive):

    range="4000-4250"

Specify ports 7000 through 7049, 7775, 7785, and 8050 through 8099:

    range="7000-7049,7775,7785,8050-8099"

<process-set>

Required: true
Default: none
Parents: <process-type>
Attributes:`id, restart-on-death, numprocs, minprocs, maxprocs, status, working-dir, parallel-requests`

A `process-set` is the abstraction of a process within OPMN. All `module-data`, environment variables, and other configuration parameters are resolved into their final values at the `process-set` level.

id="process-set-id"

Required: true
Default: none
Valid Values: A string

The `id` attribute uniquely identifies the `process-set` within the `process-type`.

restart-on-death="boolean"

Required: false
Default: false
Valid Values: `true` or `false`

If a managed process terminates unexpectedly, that is, not stopped by a request, then OPMN will not automatically restart it. To enable automatic restarting of terminated managed processes set the attribute to `true`.

numprocs="num"

Required: true unless `minprocs` is configured; otherwise false
Default: none
Valid Values: An integer

Specifies the number of processes for OPMN to start for the `process-set`.

minprocs="min"

Required: true unless `numprocs` is configured; otherwise false
Default: none
Valid Values: An integer

Specifies the default number of processes for OPMN to start for this process set. If `minprocs` is configured, then `maxprocs` must be set with a value greater than or equal to the value for minprocs. If minprocs and `maxprocs` are configured, a specific number of processes may be given in an OPMN request for this process set. This attribute may not be specified if `numprocs` has been configured.

maxprocs="max"

Required: true if minprocs is configured; otherwise false
Default: none
Valid Values: An integer

The `maxprocs` attribute must be specified if minprocs has been configured, but cannot be specified if numprocs has been configured.

status="state"

Required: false.
Default: `enabled`
Valid Values: `enabled` or `disabled`

A `process-set` may be `enabled`, in which case OPMN parses all of its configured attributes and elements and enables requests to operate upon it, or `disabled`, in which case the `process-set` entry is complete ignored and treated as if it were not even listed in `the opmn.xml file`.

working-dir="path"

Required: false.
Default: `$ORACLE_HOME`
Valid Values: A path name

The `working-dir` path name specifies the working directory set for the managed processes created that belong to the `process-set`. The`$ORACLE_HOME` directory may be used.

parallel-requests="boolean"

Required: false
Default: false
Valid Values: `true` or `false`

OPMN serializes requests at the `process-set` level, such that only one request can execute on a given `process-set` at a time: each subsequent request must wait until the previous request completes before it can execute. This default behavior is disabled for a `process-set` when `parallel-requests` is set to `true`.

Note: When the `parallel-requests` attribute is enabled OPMN performs no serialization on requests for the `process-set` at all, which means conflicting requests may be issued and execute at virtually the same time, thus leaving processes in the `process-set` in unpredictable states; therefore when `parallel-requests` is set to `true` you must verify that conflicting requests are not issued at the same time for the `process-set` (this includes requests with implicit wild-cards for matching `process-set`s).