ONS Configuration File

ONS configuration is controlled by the ONS configuration file, ORACLE_HOME/opmn/conf/ons.config. This file tells the ONS daemon details about how it should behave and who it should talk to. Configuration information within ons.config is defined in simple name and value pairs. There are three values that should always be configured within ons.config. The first is localport, the port that ONS binds to on the localhost interface to talk to local clients. An example of thelocalport configuration is the following:

localport=4100

The second value is remoteport, the port that ONS binds to on all interfaces for talking to other ONS daemons. An example of the remoteport configuration is the following:

remoteport=4200

The third value specifies nodes, a list of other ONS daemons to talk to. Node values are given as a comma-delimited list of either host names or IP addresses plus ports. Note that the port value that is given is the remote port that each ONS instance is listening on. In order to maintain an identical file on all nodes, thehost:port of the current ONS node can also be listed in the nodes list. It will be ignored when reading the list.

The nodes listed in the nodes line correspond to the individual nodes in the RAC instance. Listing the nodes ensures that the middle-tier node can communicate with the RAC nodes. At least one middle-tier node and one node in the RAC instance must be configured to see one another. As long as one node on each side is aware of the other, all nodes are visible. You need not list every single cluster and middle-tier node in the ONS config file of each Oracle RAC node. In particular, if one ONS config file cluster node is aware of the middle tier, then all nodes in the cluster are aware of it.

An example of the nodes configuration is the following:

nodes=myhost.example.com:4200,123.123.123.123:4200

There are also several optional values that can be provided in ons.config.The first optional value is a loglevel. This specifies the level of messages that should be logged by ONS. This value is an integer that ranges from 1, which indicates least messages logged, to 9, which indicates most messages logged. The default value is 3. The following is an example:

loglevel=3

The second optional value is a logfile name. This specifies a log file that ONS should use for logging messages. The default value for logfile is$ORACLE_HOME/opmn/logs/ons.log. The following is an example:

logfile=/private/oraclehome/opmn/logs/myons.log

The third optional value is a walletfile name. A wallet file is used by the Oracle Secure Sockets Layer (SSL) to store SSL certificates. If a wallet file is specified to ONS, it will use SSL when communicating with other ONS instances and require SSL certificate authentication from all ONS instances that try to connect to it. This means that if you want to turn on SSL for one ONS instance, then you must turn it on for all instances that are connected. This value should point to the directory where your ewallet.p12 file is located. The following is an example:

walletfile=/private/oraclehome/opmn/conf/ssl.wlt/default

One optional value is reserved for use on the server-side. useocr=on is used to tell ONS to store all Oracle RAC nodes and port numbers in Oracle Cluster Registry (OCR) instead of in the ONS configuration file. Do not use this option on the client-side.

The ons.config file allows blank lines and comments on lines that begin with the number sign (#).

Client-Side ONS Configuration

You can access the client-side ONS through ORACLE_HOME/opmn. On the client-side, there are two ways to set up ONS:

• Remote ONS configuration

  See Also:

  "Remote ONS Subscription"

• ONS daemon on the client-side

Example 26-1 illustrates how a sample configuration file may look.

# This is an example ons.config file
#
# The first three values are required
localport=4100
remoteport=4200
nodes=racnode1.example.com:4200,racnode2.example.com:4200

After configuring ONS, you start the ONS daemon with the onsctl command. It is the user‘s responsibility to make sure that an ONS daemon is running at all times.

Using the onsctl Command

After configuring, use ORACLE_HOME/opmn/bin/onsctl to start, stop, reconfigure, and monitor the ONS daemon. Table 26-1 is a summary of the commands thatonsctl supports.

Server-Side ONS Configuration Using racgons

You can access the server-side ONS through ORA_CRS_HOME/opmn. You configure the server-side by using racgons to add the middle-tier node information to OCR. This command is found in ORA_CRS_HOME/bin/racgons. Before using racgons, you must edit ons.config to set useocr=on.

The middle-tier nodes should be configured in OCR, so that all nodes share the configuration, and no matter which Oracle RAC nodes are up they can communicate to the middle-tier. When running on a cluster, always configure the ONS hosts and ports not by using the ONS configuration files but usingracgons. The racgons command stores the ONS hosts and ports in OCR, where every node can see it. That way, you do not need to edit a file on every node to change the configuration, just run a single command on one of the cluster nodes.

The racogns command enables you to specify hosts and ports on one node, then propagate your changes among all nodes in a cluster. The command takes two forms:

racgons add_config hostname:port [hostname:port] [hostname:port] ...
racgons remove_config hostname[:port] [hostname:port] [hostname:port] ...

The add_config version adds the listed host name(s), the remove_config version removes them. Both commands propagate the changes among all instances in a cluster.

If multiple port numbers are configured for a host, the specified port number is removed from hostname. If only hostname is specified, all port numbers for that host are removed.

Other Uses of racgons

You should run racgons whenever you add a new node to the cluster.

Remote ONS Subscription

The advantages of remote ONS subscription are the following:

• Support for an All Java middle-tier stack

• No ONS daemon needed on the client computer and, therefore, no need to manage this process

• Simple configuration using the DataSource property

When using remote ONS subscription for Fast Connection Failover, the application invokes the following method on an OracleDataSource instance:

setONSConfiguration(String remoteONSConfig)

The remoteONSConfig parameter is a list of name and value pairs of the form name=value that are separated by a new line character (\n). name can be one ofnodes, walletfile, or walletpassword. This parameter should specify at least the nodes ONS configuration attribute, which is a list of host:port pairs, each pair separated by comma (,). The hosts and ports denote the remote ONS daemons available on the Oracle RAC nodes.

SSL could be used in communicating with the ONS daemons when the walletfile attribute is specified as an Oracle wallet file. In such cases, if thewalletpassword attribute is not specified, single sign-on (SSO) would be assumed.

Following are a few examples, assuming ods is an OracleDataSource instance:

ods.setONSConfiguration("nodes=racnode1.example.com:4200,racnode2.example.com:4200");

ods.setONSConfiguration("nodes=racnode1:4200,racnode2:4200\nwalletfile=/mydir/Wallet\nwalletpassword=mypasswd");

ods.setONSConfiguration("nodes=racnode1:4200,racnode2:4200\nwalletfile=/mydir/conf/Wallet");