B
Oracle Parallel Server Management on UNIX Reference

This appendix describes Oracle Parallel Server Management on UNIX.

Specific topics covered in this appendix are:

• OPSCTL Utility

• Creating the db_name.conf File

• Oracle Intelligent Agent Configuration

OPSCTL Utility

The OPSCTL utility on UNIX uses a file named db_name.conf to define Oracle Parallel Server instances and related services. The Oracle Database Configuration Assistant create this file during database creation.

Consider the following points when configuring your db_name.conf:

• The Oracle home location can be set up to be shared or non-shared. If the location is non-shared, you must manually create and remote copy (rcp) the db_name.conf file to each node of the cluster.

• The managed system maps the names of the nodes to correspond with non-negative numbers (positive numbers) called "node numbers" based on the thread ID.

Creating the db_name.conf File

This section covers the following topics:

• Parameter Syntax

• Parameter Expansion

• Parameter Descriptions

• Parameter Node Overrides

• Oracle Parallel Server Instances

Parameter Syntax

The parameter values are specified in the configuration file using the following syntax:

parameter_name = value
parameter_name = (value1, value2, ...)

Consider these points when configuring parameter values:

• Enter each parameter on a separate line in the db_name.conf file.

• Separate lists of values with commas and enclose them in parentheses.

• You must surround parameter values containing commas or spaces with double quotation marks ("xxx").

Parameter Expansion

Parameter values with the percent sign (%) in the configuration file have different meanings depending on the character that follows the % sign:

Value	Description
%p	Expands to the name of the Oracle Parallel Server that is set by the value of ORACLE_PSRV parameter or the environment variable ORACLE_PSRV
%h	Expands to the value of the ORACLE_HOME parameter or expands to the value of the ORACLE_HOME environment variable
%n	Expands to the node number for the appropriate node. The %n is replaced by a different value on each node
%m	Expands to the node name for the appropriate node. The %m is replaced by a different value on each node

Parameter expansion examples are shown in the following table:

inst_init_ora=/ora/dbs/initop.ora

inst_init_ora=/ora/dbs/initop_ \ 
%m.ora

initop_spdev01.ora
initop_spdev02.ora
initop_spdev03.ora

Parameter Descriptions

The following table lists the configuration parameters that you can set in the db_name.conf file. Each parameter is listed in the order that it would typically appear in the configuration file. You must enter parameters in lowercase.

Parameter	Description
node_list	The list of node numbers for all nodes on which Oracle Parallel Server instances are run. This parameter is required on some operating systems, such as IBM RS/6000 SP2, and Sequent. On some operating systems, such as Sun Solaris, the entire cluster is used by default. For these operating systems, this parameter does not need to be explicitly set. Example: node_list = "1-8"
inst_oracle_sid	(optional) The instance identifier. Each Oracle Parallel Server requires a unique Oracle System Identifier (SID). The default is %p%n.
inst_init_ora	(optional) A parameter file that is shared by all the instances of the Oracle Parallel Server. If the parameter contains %n or %m, a different initsid.ora on each node is used.
node#:inst_init_ora	(optional) A parameter file for the Oracle Parallel Server instance on a specific node, as denoted by the node#. This overrides any value specified in the inst_init_ora parameter.
oracle_home	(optional) Specifies either the single, shared Oracle home or each non-shared Oracle home location for each node. Defaults to the Oracle home specified in oratab (platform-specific location).
lsnr_listener_name	(optional) The names of the listeners for each specific node.
tns_admin	(optional) The value of the TNS_ADMIN environment variable that is used to start or stop all listeners.
node#:tns_admin	(optional) The value of TNS_ADMIN environment variable that is used to start or stop the listener on the specific node, as denoted by node#.
environ	(optional) The double-quoted list of semi-colon separated "name = value" pairs of environment variables that are required for the startup or shutdown operations. For example: environ="ENV1=value1;ENV2=value2" The environment variables included in this parameter are in addition to ORACLE_PSRV, ORACLE_HOME, and TNS_ADMIN, each of which are represented either by a separate environment variable or a separate configuration parameter.

The following examples show how the configuration parameters are applied. The parameter settings for different services are illustrated with reference to an example Oracle Parallel Server system named, mypsrv, that consists of an eight-node system. The following table shows how node numbers, node names, and instance identifiers are mapped to each other for mypsrv.

Parameter Node Overrides

You can set the parameters to apply to a specified set of nodes by prefixing the parameter definition with a node number as follows:

node_number:parameter_name =value

Oracle Parallel Server Instances

Instances are defined by the following parameters:

• inst_oracle_sid

• inst_init_ora

inst_oracle_sid

If the inst_oracle_sid parameter is not specified, then OPSCTL generates a default list of Oracle System Identifiers (SID) in which each SID is set to the following format:

db_name node# 

where db_name corresponds to the name of the Oracle Parallel Server and where node# corresponds to the node number of the corresponding node in the node_list. This is as if %p%n were specified.

For example, if the parameters are set as follows:

oracle_psrv = mypsrv
node_list = "1-3,6"

and you do not specify the inst_oracle_sid parameter, then the SIDs generated for the instances will be mypsrv1, mypsrv2, mypsrv3, and mypsrv6 for the spdev01, spdev02, spdev03, and spdev06 nodes, respectively.

The inst_oracle_sid parameter is used to specify the ORACLE_SIDs (instance identifiers) for the instances. It may be a comma-separated list of SID names where each SID maps to the corresponding node mentioned in the same order in the node_list parameter. Or, it may be that %n or %m is used to generate a distinct SID on each node.

For example, if the parameters are set as follows:

node_list = "1-3,6"
inst_oracle_sid = (sid_a, sid_b, sid_c, sid_d)

then the sid_a value will be used for the instance on node spdev01 and the sid_d value will be used for the instance on the spdev06 node.

The parameter substitution facility can be used to customize ORACLE_SID values. For example, if you set the parameters as follows:

node_list = "1-3,6"
inst_oracle_sid = "%p_SID_%n"

then the mypsrv_sid_1, mypsrv_sid_2, mypsrv_sid_3, and mypsrv_sid_6 values are used for SIDs of instances on nodes spdev01, spdev02, spdev03, and spdev06, respectively.

inst_init_ora

The absolute path names for the parameter files are specified by the inst_init_ora and/or node#:inst_init_ora parameters. If this parameter is not specified, then $ORACLE_HOME/dbs/initsid.ora is used.

For each instance, OPSCTL first searches for the node#:inst_init_ora parameter, where node# is the number of the node on which the instance runs. If this parameter is set, OPSCTL uses its value as the instance's parameter file. If it is not specified, then OPSCTL uses the inst_init_ora parameter.

Listeners

Listeners are defined by the following parameters:

• tns_admin

• lsnr_listener_name

tns_admin

The value for tns_admin for all listeners to be started or stopped can be set with the tns_admin parameter.

If the tns_admin parameter is not set and the TNS_ADMIN environment variable is set, the listeners are given the value of the TNS_ADMIN environment variable.

If neither the tns_admin parameter nor the TNS_ADMIN environment variable are set, the listeners are not given any value, and will use the default search order to locate the listener.ora file.

The listener.ora file contains the listening addresses of the listener on the system as well as the name and Oracle home of any database the listener serves.

To use a different TNS_ADMIN variable for a specific node, specify the node using the node#:tns_admin parameter, where node# refers to the number of the corresponding node.

For example, if the TNS_ADMIN environment variable is set to /home/myname/misc and the tns_admin and none of the node#:tns_admin parameters are specified in the configuration file, then OPSCTL uses the value /home/myname/misc for all nodes.

In another example, if the following parameters are set as follows:

node_list = "1-3,6"
tns_admin = /dve/myname/815/ops
3:tns_admin = /dve/myname/others

then for the listener on spdev03 (node number 3), tns_admin is set to /dve/myname/others, whereas nodes spdev01, spdev02 and spdev06, tns_admin is set to /dve/myname/816/ops.

lsnr_listener_name

The lsnr_listener_name parameter is used to specify the listener names. It is a comma-separated list of listener names, where each listener name maps to the corresponding node mentioned in the same order listed for the node_list parameter.

If you do not specify the lsnr_listener_name parameter, then OPSCTL generates a default list of listener names in which each listener name follows the format node_name_listener, where node_name corresponds to the name of the node. This is as if %m_listener was specified.

For example, if the node_list parameter is set as follows:

node_list = "1-3,6"

and you do not specify the lsnr_listener_name parameter, the names generated for the listeners would be spdev01_listener, spdev02_listener, spdev03_listener, and spdev06_listener for the spdev01, spdev02, spdev03, and spdev06 nodes respectively.

For example, if the parameters are set as follows:

node_list = "1-3,6"
lsnr_listener_name = (listener_A, listener_B, listener_C, listener_D)

then the listener_A name would be used for the listener on node spdev01 and the listener_D name would be used for the listener on node spdev06.

If only one entry is specified for the lsnr_listener_name parameter, then the same name is used for listeners on all nodes specified in the node_list. Also, you can use parameter expansion to specify different listener names for all nodes.

For example, if the parameters are set as follows:

node_list = "1-3,6"
lsnr_listener_name = "listener_mypsrv"

then the listener_mypsrv name would be used for all the listeners on all nodes.

In another example, if you set the following parameters as follows:

node_list = "1-3,6"
lsnr_listener_name = "lsnr_%n"

then the names lsnr_1, lsnr_2, lsnr_3, and lsnr_6 will be used for the listeners on the nodes spdev01, spdev02, spdev03, and spdev06, respectively.

Sample of db_name.conf File

The following is an example db_name.conf file:

node_list = "1-4" 
inst_init_ora = /ora/dbs/init_%m.ora 
inst_oracle_sid = (SID_A, SID_B, SID_C, SID_D)
lsnr_listener_name = listener_myhost%n 

Oracle Intelligent Agent Configuration

Oracle Intelligent Agents are shipped with the database and must be installed on each remote, managed Oracle Parallel Server node. The Oracle Intelligent Agents are responsible for discovering the available services (databases, listeners, parallel servers) on each node.

The configuration is different for shared and non-shared Oracle home locations. In a typical setup, Oracle Intelligent Agents are installed in non-shared Oracle home locations.

The following directories should not be shared because they contain files that are specific to each Oracle Intelligent Agent's node:

• $ORACLE_HOME/network/admin

• $ORACLE_HOME/network/log

• $ORACLE_HOME/network/trace

• $ORACLE_HOME/network/agent

  Caution: An Oracle Intelligent Agent cannot be installed in a shared Oracle home location. You must ensure that each node's Oracle Intelligent Agent is installed in a separate Oracle home location, distinct from other Oracle home locations. Also ensure that your server files, tnsnames.ora and listener.ora, contain the correct entries for all instances to perform service discovery, as described in "Oracle Parallel Server Management Requirements".

Non-shared Oracle Home

You must ensure that you configure and start Oracle Intelligent Agent on every node running an instance.

To start the agent, at an operating system prompt, enter the command:

lsnrctl dbsnmp_start

Shared Oracle Home

If the Oracle home location is shared (through NFS or any other equivalent facility) by all nodes, you must set up Oracle Intelligent Agent as follows:

1. Install Oracle Intelligent Agent for each node in its own Oracle home location, distinct from the shared Oracle home location.

   Note: You cannot install the Intelligent Agent in the same shared Oracle home location where your Oracle database is located.

2. Copy or link tnsnames.ora and listener.ora to each Oracle Intelligent Agent's Oracle home location from the shared Oracle home.

3. Before starting Oracle Intelligent Agent on each node, set the Oracle home location to Oracle Intelligent Agent's Oracle home.

4. Issue the lsnrctl dbsnmp_start command.

5. Ensure that the DBSNMP utility is set up to run at system startup time.