Oracle® Process Manager and Notification Server Administrator's Guide 10g Release 3 (10.1.3.1.0) Part Number B28944-01 |
|
|
View PDF |
This chapter provides common configuration examples, and descriptions of elements and attributes for the OPMN opmn.xml
file.
It contains the following topics:
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>
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>
is the top-level element in the opmn.xml
file.
path
, comp
, rotation-size
, rotation-hour
The configuration definitions for the OPMN log mechanism.
$ORACLE_HOME
/opmn/logs/opmn.log
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.
internal
, ons
, pm
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 |
|
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
.
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
.
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
.
path
, comp
, rotation-size
, rotation-hour
The debug
element contains the configuration definitions for the OPMN debug log mechanism.
Note: Enable usage of theopmn.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. |
$ORACLE_HOME
/opmn/logs/opmn.dbg
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"
internal
, ons
, pm
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 |
|
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"
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"
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.
The notification-server
element configures or, contains the elements to configure the ONS portion of OPMN.
By default, OPMN will support both the IPv6 and IPv4 network interfaces (see Section 3.11, "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.
remote, request
The iapddr
element specifies host information for ONS listener threads and host port bindings.
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.
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.
local, remote, request
The port
element contains configuration information for ONS listener threads host and port bindings.
local="port"
The local
attribute is for the ONS local port value.
remote="port"
The remote
attribute is for the ONS remote port value.
request="port"
The request
attribute is for the ONS request port
value.
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:
true
or false
If the enabled
value is set to true, it enables SSL connections for ONS.
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.
The wallet-password
attribute is the password string for the specified Oracle wallet.
The openssl-certfile
attribute specifies the Open SSL certificate file to use for authentication on ONS connections. The $ORACLE_HOME
directory may be used.
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-keyfile
password.The openssl-password
attribute is the password string for the specified openssl-keyfile
.
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.
io-timeout
, io-idle
, timeout
The tune
element contains the information for the Tuneable Notification Server ONS parameters.
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-timeout
- ( io-timeout
/ 3 )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"
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.
The topology
element contains the configuration information for the ONS topology within a cluster.
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.
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.11, "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"/>
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"
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"/>
The gateway
element is used to connect isolated discovery topologies. You can configure multiple gateway elements.
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.
insecure-remote-requests
The process-manager
contains the configuration definitions for the PM portion of OPMN.
insecure-remote-requests="boolean"
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 theinsecure-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 |
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
.
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"
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.
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"
enabled
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.
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.
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 |
---|---|
|
<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> |
id
The category
element is an organizational level within a module-data
block.
id="id"
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.
id, value, process-conversion
A data name value definition within a module-data
category.
id="id"
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"
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.
true
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 ^.
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"
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.
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"
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"
The string specifies the ias-instance
id.
name="ias-instance-name"
ias-instance
-id
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"
This ORACLE+_HOME
path attribute must be the ORACLE_HOME
equivalent for the Oracle Application Server instance.
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 theias-instance level, with the values extracted either from the ias-instance configuration or from the OPMN run time environment:
Linux: Microsoft Windows: |
id, value, append, process-conversion
The variable element defines the environment variable name and value.
id="id"
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"
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"
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"
true
true
or false
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.
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"
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"
A description of the RMD.
interval="interval"
"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.
rmd
attribute interval="joinons
group
")The conditional
element contains the conditional statement to be evaluated by OPMN.
<![CDATA[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 relative
application
: may be specified as either relative or absolute.
The following component specifications are allowed for global RMD conditionals
:
[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)}
The action
element indicates an action to be taken if the conditional
evaluates true.
value=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:
restart
: perform a restart 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
A timeout value can be configured for each action
. The default timeout for start, 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.
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.
id, id-matching, status
An ias-component
is a logical grouping of process-type
for administrative purposes.
Note: For more information about OC4J groups using theias-component element refer to Section 3.2, "OC4J Groups". |
The id
attribute uniquely identifies the ias-component
within the ias-instance
.
id-matching="boolean"
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"
enabled
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.
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.
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.
infrastructure-key
is not specified.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
.
db-connect
is not specified.The infrastructure key
attribute is required to identify the database.
timeout="depend-timeout"
1200
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"
600
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.
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"
The address
element is the address string required to connect to Oracle Internet Directory.
address
is not set.true
or false
Use the default infrastructure Oracle Internet Directory for the Oracle Application Server instance.
enabled, wallet-file, wallet-password
The SSL information for the Oracle Internet Directory connection.
enabled="boolean"
true
or false
To enable SSL on the Oracle Internet Directory connection, set the enabled
attribute to true
.
The path name to the wallet file for authentication of the Oracle Internet Directory connection. The $ORACLE_HOME
directory location may be used.
The wallet-password
attribute is the password for the specified wallet-file.
timeout="depend-timeout"
1200
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"
600
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.
host, port, URI, timeout, cache-timeout
The OSSO
element specifies the OracleAS Single Sign-On service to check.
host="hostname"
The host
attribute is the hostname for the OracleAS Single Sign-On connection.
port="port"
The port
attribute is the port for the OracleAS Single Sign-On connection.
URI="uri"
The URI
attribute is the URI for the OracleAS Single Sign-On connection.
enabled, wallet-file, wallet-password
The ssl
element is the SSL information for the OracleAS Single Sign-On connection.
enabled="boolean"
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"
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"
The wallet-password
is the password for the specified wallet-file.
timeout="depend-timeout"
1200
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"
600
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.
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"
ias-instance
of the current process-type
or process-set
.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"
The ias-component
for the managed process dependency.
process-type="process-type-id"
The process-type-id
for the managed process dependency.
The process-set-id
for the managed process dependency.
autostart="boolean"
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"
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"
1200
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.
600
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: Thecache-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>
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"
The id
attribute uniquely identifies the process-type
within the ias-component
.
module-id="module-id"
The module-id
attribute must map directly map to the module-id
attribute that supports the process-type
.
status="state"
enabled
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"
ORACLE_HOME
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"
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
.
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 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 Event Script Arguments
Option Name | Option Argument | Description |
---|---|---|
|
|
An integer value for the current |
|
|
The |
|
|
The |
|
|
The |
|
|
The |
|
|
The |
- |
|
The path name for the |
- |
|
The path name for the |
|
|
A string indicating the reason script was executed. The |
- |
|
The operating system integer value given for the |
- |
|
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.
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"
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.
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"
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.
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"
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.
timeout, retry
The start
attribute contains the start parameters for a managed processes.
timeout="timeout"
60
The timeout
attribute specifies the timeout value in seconds for the start of a managed process.
retry="num"
0
The retry
attribute specifies the number of consecutive attempts that will be made to start the process for a single request.
timeout
The stop
attribute specifies the stop parameters for managed processes.
timeout="timeout"
30
The timeout
value in seconds for the stopping a managed process.
timeout, retry
The restart
parameters for managed processes.
timeout="timeout"
90
The timeout
value in seconds for the restart of a managed process.
retry="num"
0
The retry
attribute is the number of consecutive attempts that will be made to restart the process for a single request.
,
<process-set>timeout, retry, interval
The ping
element is the ping parameters for managed processes.
timeout="timeout"
20
The timeout
value in seconds for the ping of a managed process. Each module specifies a ping timeout.
retry="num"
0
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"
20
The interval
attribute is the interval, in seconds, between each ping of a managed process.
id, range
The port
element provides a port management mechanism for modules to use. Each module uses the ports configured with id
.
id="id"
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"
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"
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.
The id
attribute uniquely identifies the process-set
within the process-type
.
restart-on-death="boolean"
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
.
minprocs
is configured; otherwise falseSpecifies the number of processes for OPMN to start for the process-set
.
numprocs
is configured; otherwise falseSpecifies 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.
The maxprocs
attribute must be specified if minprocs has been configured, but cannot be specified if numprocs has been configured.
status="state"
enabled
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
.
$ORACLE_HOME
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"
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
.