Understanding SQL*Net

Configuring the Network Listener: LISTENER.ORA

Before a database server can receive connections from SQL*Net version 2 (and later) clients, a listener must be active on the server platform. On most platforms, a network listener is used. The configuration file for the network listener is LISTENER.ORA. It contains four parts:

listener names

listener addresses

description of the databases that use the listener

parameters that influence the listener's behavior

Note: This file should be generated and modified through the Oracle Network Manager. It should not be edited manually.

Listener Names

The listener name can be any easy-to-use name. The default listener name is LISTENER, which is the recommended name in a standard installation that requires only one listener on a machine. The listener name must be unique on the network. However, this uniqueness is assured by the fact that Network Manager appends the name of the node and its domain to the listener name you supply. For example, if there is a listener on a node named RACER and a listener on a node named RABBIT, Network Manager will append the node names and the domain to their names so that they will be identified as LISTENER_RACER.WORLD and LISTENER_RABBIT.WORLD.

The listener name must be unique to the machine. If you have more than one listener on a machine, each must have a unique name. The TURTLE node, for example, might have three listeners with the names LSNR1_TURTLE.WORLD, LSNR2_TURTLE.WORLD, and LSNR3_TURTLE.WORLD.

Listener Addresses

The listener usually listens both for internal connection requests and for connection requests from across the network.

IPC Addresses

The listener listens for interprocess calls (IPC) as well as calls from other nodes. For example, on a UNIX machine, an IPC adapter is the adapter for the UNIX domain socket communication mechanism; on VMS, it is the adapter for the mailbox communication mechanism. IPC addresses must be included in the LISTENER.ORA file. Oracle Network Manager generates the IPC entries automatically, without input from you.

The IPC address format, which is the same across platforms, is as follows:

		(ADDRESS=
			(PROTOCOL=IPC) 
			(KEY=string))

Network Manager creates two IPC addresses for each database for which a listener listens. In one, the key value is equal to the service name. This IPC address is used for connections from other applications on the same node. Service names are described later in this chapter, in the section "TNSNAMES.ORA." In the other IPC address, the key value is equal to the database system identifier (SID), which is described in the next section. This IPC address is used by the database dispatcher to identify the listener.

Note: If the service name is the same as the SID, only one IPC address is needed, and only one is generated by Network Manager.

If the network includes Oracle Names, and if you create an alias (a second service name) for the address using Network Manager, an IPC address using the alias as a key is included in LISTENER.ORA.

Network Addresses

The network address of a listener includes the community in which the destination resides, the protocol it uses, and protocol-specific parameters. If the listener is on a node that is on more than one community, it has more than one address.

The Network Manager automatically provides the correct protocol specific parameters for any protocol you use, but you must provide the appropriate values. For information about the values for the parameters for a given protocol, see the Oracle operating system specific documentation for your platform.

Sample Addresses

Here is an example of an address for a listener on in a TCP/IP community:

 LISTENER_mike.world=(ADDRESS_LIST=
			(ADDRESS=
				(PROTOCOL=IPC)
				(KEY=prod.world)
			)
			(ADDRESS=
				(PROTOCOL=IPC)
				(KEY=db1)
			)
			(ADDRESS=
				(PROTOCOL=tcp)
				(HOST=mike.world)
				(PORT=1521)
			)
		)

Describing the Databases on the Listener

The next section of the LISTENER.ORA file describes the system identifiers (SIDs) of the databases for whom the listener listens. It is made up of keyword-value pairs.

SID_LIST_listener_name=[(SID_LIST=]
				(SID_DESC
				   (GLOBAL_DBNAME=global_dbname)
				   (SID_NAME=SID)
				   (OS_Oracle_
					environment=db_location)
				)
				[(SID_DESC=
				   (GLOBAL_DBNAME=global_dbname)
				   (SID_NAME=SID)
				   (OS_Oracle_environment=db_location)
				)]
			    [)]

The GLOBAL_DBNAME is the name and domain of the database as given in the database initialization parameter file. The SID is the Oracle system ID of the database server. In the next keyword-value pair, the keyword is operating system specific: it is indicated here as the variable OS Oracle environment. Its value, indicated here as db_location, is the specific location of the database executables.

An example typical of the UNIX operating system follows:

(ORACLE_HOME=/usr/oracle)

An example from a VMS environment follows:

(PROGRAM='disk$:[oracle.rdbms]orasrv.com')

An example for OS/2 might be:

(PROGRAM=ORACLE7)

An example of a complete SID_LIST_listener_name section on a UNIX operating system follows:

SID_LIST_LISTENER=(SID_LIST=
				(SID_DESC=
					(SID_NAME=db1)
					(ORACLE_HOME=/usr/oracle)
				)
				(SID_DESC=
					(SID_NAME=db3)
					(ORACLE_HOME=/usr/oracle)
				)
			)

Note that a listener can listen for more than one database on a machine. However, you may create different listeners for the databases if you wish. All the listeners on a single machine share one LISTENER.ORA file.

Prespawned Dedicated Server Processes

If you want the listener to create prespawned dedicated server processes when it is started, use Network Manager to include the following parameters in each SID_DESC in LISTENER.ORA.

PRESPAWN_ MAX The maximum number of prespawned dedicated server processes the listener will create. This number must be at least as many as the sum of the pool size for each protocol. For greatest efficiency, Oracle Corporation recommends a large value, so that prespawned dedicated server processes are always available for new connection requests.
PROTOCOL The protocol on which the listener creates prespawned dedicated server processes. If a listener listens on more than one community, you can choose whether to have pre-spawned servers on any or all of them.
POOL_SIZE The number of unused prespawned dedicated server processes for the listener to maintain on the selected protocol. Choose a number that is greater than 0 but no greater than the PRESPAWN_MAXIMUM value. The value should be about what you expect the average number of connections to be at any given time.
TIME OUT Time in minutes that an inactive prespawned dedicated server process waits for the next connection. The value should be greater than 0. (A value of 0 will allow an inactive shadow process to continue indefinitely, thus wasting machine resources.) For greatest efficiency, Oracle Corporation recommends a short Time Out value. The time out is activated only after a prespawned dedicated server process has carried a connection and been disconnected. In other words, prespawned dedicated server processes that are waiting for their first connection do not time out.

Here is an example of a SID_DESC section of LISTENER.ORA that includes information about prespawned dedicated server processes:

(SID_LIST =
	(SID_DESC =
		(GLOBAL_DBNAME = sales.acme.com
		(SID_NAME = DB1)
		(ORACLE_HOME = /usr/bin/oracle)
		(PRESPAWN_MAX = 99)
 		(PRESPAWN_LIST=
	 		(PRESPAWN_DESC=
				(PROTOCOL=TCP) 
				(POOL_SIZE=10)
				(TIMEOUT = 2)
			)
		)
	)
)

LISTENER.ORA Control Parameters

The third section of the LISTENER.ORA file contains a list of parameters that control the behavior of the listener. The parameters and their defaults (if any) follow:

PASSWORDS_listener_name=(password[,...password])

This optional parameter allows one or more passwords. If this parameter is specified with one or more passwords, then the use of one of these passwords is required to perform certain DBA tasks against the listener using the Listener Control Utility. See "Using the Listener Control Utility" If this parameter is not included in the file, then anyone can access the Listener Control Utility to stop or alter the listener.
You may choose to have Network Manager encrypt the password in this file. If you choose to have the password encrypted, unauthorized people cannot see it in the LISTENER.ORA file and use it to manipulate the listener. However, if you want the password to be encrypted, you can enter only one password. The default is to encrypt the password.
If you do not care about password encryption, you can enter more than one password. If more than one password is entered, all of them must be surrounded by parentheses. For example:
PASSWORDS_LISTENER=(super32, sly51)
Network Manager creates the parentheses automatically.

STARTUP_WAIT_TIME_listener_name=number

This parameter sets the number of seconds that the listener sleeps before responding to the first listener control status command. This feature assures that a listener with a slow protocol will have had time to start up before responding to a status request. Default is 0.
For example, in the case of SPX, if you use the Listener Control Utility to request a STATUS immediately after the START command, and if this parameter is set to 0, you will get an error stack indicating that the listener is not available. If this parameter is set to 2, however, the Listener Control Utility will wait briefly, and the STATUS command will return a message showing that the listener is available and listening. (For information about using the Listener Control Utility, see Chapter 5.)

CONNECT_TIMEOUT_listener_name=number

This parameter sets the number of seconds that the listener waits to get a valid SQL*Net version 2 connection request after a connection has been started. The listener drops the connection if the timeout is reached. Default is 10; if set to 0, it will wait forever.

TRACE_LEVEL_listener_name=OFF|USER|ADMIN

This parameter indicates the level of detail the trace facility records for listener events. Choices are OFF, USER,or ADMIN. Default is OFF. USER provides a limited level of tracing; ADMIN provides a more detailed trace.

TRACE_DIRECTORY_listener_name=path_to_trace_directory

This parameter sets the directory where the trace file is placed. Default is operating system specific. On UNIX, for example, it is $ORACLE_HOME/network/trace.

TRACE_FILE_listener_name=trace_filename

This parameter establishes the name of the file to which trace information is written. Default is listener_name.trc on most platforms.

LOG_DIRECTORY_listener_name=path_to_log_directory

This parameter indicates the directory in which to find the log file that is automatically generated for listener events. Default is operating system specific. On UNIX, for example, it is $ORACLE_HOME/network/log.

LOG_FILE_listener_name=log_filename

This parameter sets the name of the log file for the listener. Default is listener_name.log on most platforms.

Sample LISTENER.ORA File

In this example, each element is laid out on a separate line, so that it is easy to see the file's structure. This is the recommended format, and this is how the files created by Network Manager look. If you must edit a LISTENER.ORA file by hand, you do not have to put each element on a separate line. Be careful, though, to include all the appropriate parentheses, and to indent if you must continue an element onto the next line. Again, we strongly recommend that you use Network Manager. This example assumes the UNIX operating system.

LISTENER_mike.world=(ADDRESS_LIST=
			(ADDRESS=
				(PROTOCOL=IPC)
				(KEY=prod.world)
			)
			(ADDRESS=
				(PROTOCOL=IPC)
				(KEY=db1)
			)
			(ADDRESS=
				(PROTOCOL=tcp)
				(HOST=mike.world)
				(PORT=1521)
			)
		)
SID_LIST_LISTENER=
			(SID_DESC=
				GLOBAL_DBNAME=sales.acme.com)
				(SID_NAME=db1)
				(ORACLE_HOME=/usr/oracle7)
			)

#The following parameters have default values

PASSWORDS_LISTENER=
STARTUP_WAIT_TIME_LISTENER=0
CONNECT_TIMEOUT_LISTENER=10
TRACE_LEVEL_LISTENER=OFF
TRACE_DIRECTORY_LISTENER=/usr/prod/oracle7/network/trace
TRACE FILE_LISTENER=listener.trc
LOG_DIRECTORY_LISTENER=/usr/prod/oracle7/network/log
LOG_FILE_LISTENER=listener.log

Note that if the listener were on a different operating system, the default file and path names for tracing and logging might be different. See your Oracle operating system-specific documentation for further information.

Controlling the Network Listener

The listener is controlled by the Listener Control Utility, LSNRCTL. For information on how to use LSNRCTL to start and control the listener, refer to Chapter 5, "Using SQL*Net".

The Server as a Client

When the server does more than its traditional role of receiving connections and responding to queries, it requires the client configuration. Server initiated connections are technically identical to client connections. Specifically, when using database links to initiate connections to other servers, the server needs all of the same configuration information as a client. It must have access to the TNSNAMES.ORA file and a SQLNET.ORA file. If it might use an Interchange, it must have its own TNSNAV.ORA file. The server has the following requirements:

The Oracle Server needs access to the connect descriptors for any other servers it will be contacting.

The Oracle Server needs to define the communities of which it is a member.

The server requires one or more preferred Connection Managers if it will be performing database links through an Interchange and if there is more than one Interchange in the network. A Connection Manager is part of an Interchange. The Connection Manager and the TNSNAV.ORA file are described in the Oracle MultiProtocol Interchange Administrator's Guide.

The following sections, which describe TNSNAMES.ORA and SQLNET.ORA for clients, are therefore applicable to servers as well. Oracle Network Manager automatically generates these files for every server.

PRESPAWN_ MAX	The maximum number of prespawned dedicated server processes the listener will create. This number must be at least as many as the sum of the pool size for each protocol. For greatest efficiency, Oracle Corporation recommends a large value, so that prespawned dedicated server processes are always available for new connection requests.
PROTOCOL	The protocol on which the listener creates prespawned dedicated server processes. If a listener listens on more than one community, you can choose whether to have pre-spawned servers on any or all of them.
POOL_SIZE	The number of unused prespawned dedicated server processes for the listener to maintain on the selected protocol. Choose a number that is greater than 0 but no greater than the PRESPAWN_MAXIMUM value. The value should be about what you expect the average number of connections to be at any given time.
TIME OUT	Time in minutes that an inactive prespawned dedicated server process waits for the next connection. The value should be greater than 0. (A value of 0 will allow an inactive shadow process to continue indefinitely, thus wasting machine resources.) For greatest efficiency, Oracle Corporation recommends a short Time Out value. The time out is activated only after a prespawned dedicated server process has carried a connection and been disconnected. In other words, prespawned dedicated server processes that are waiting for their first connection do not time out.

	This optional parameter allows one or more passwords. If this parameter is specified with one or more passwords, then the use of one of these passwords is required to perform certain DBA tasks against the listener using the Listener Control Utility. See "Using the Listener Control Utility" If this parameter is not included in the file, then anyone can access the Listener Control Utility to stop or alter the listener.
	You may choose to have Network Manager encrypt the password in this file. If you choose to have the password encrypted, unauthorized people cannot see it in the LISTENER.ORA file and use it to manipulate the listener. However, if you want the password to be encrypted, you can enter only one password. The default is to encrypt the password.
	If you do not care about password encryption, you can enter more than one password. If more than one password is entered, all of them must be surrounded by parentheses. For example:
	PASSWORDS_LISTENER=(super32, sly51)
	Network Manager creates the parentheses automatically.