The Oracle Listener


What is the Oracle8i Listener ?

The listener process executes on the database server and manages client connection requests to that database server. There can be one or multiple listener processes listening for a database server. Each listener can listen with one or multiple protocol addresses for a single database service. Note that service information does not have to be configured in the listener.ora file. However, if Oracle Enterprise Manager or pre-Oracle8i is used then service information must be configured in the listener.ora file.

The listener process configuration resides on the database server. The listener listens for connection requests and then routes those connections appropriately. Multiple protocol addresses can be configured within the listener. This allows the listener to be called with multiple protocols. When a request is made to a database listener the listener will pass the request to a dedicated server process or dispatcher process (MTS) by sending a redirection message back to the client process with an address of a server process. The client process then proceeds to communicate with the database using the server process whilst the listener continues to listen for further connection requests from other client processes. Any spawning of server processes or dispatcher processes is executed by the listener as a result of a client connection request exceeding currently unused process availability on the server.

In the listener.ora file the listener has a default name of LISTENER which will default to listen on TCP/IP at port 1521 and the IPC as shown below. If the default port 1521 is not used for the TCP/IP connection then the LOCAL_LISTENER value must be set in the parameter file. Configuration of clients to the addresses shown below will connect to these addresses. Note that the IPC protocol address is used to allow calling of external functions from PL/SQL code.

(address=(protocol=tcp)(host=<hostname>)(port=1521))
(address=(protocol=ipc)(key=PNPKEY))

In the listener file configuration shown below LISTENER defines the listening protocol address for LISTENER. SID_LIST_LISTENER describes the database service.

LISTENER =
  (DESCRIPTION_LIST =
    (DESCRIPTION =
      (ADDRESS = (PROTOCOL = TCP) (HOST = <hostname>) (PORT = 1521))
      (ADDRESS = (PROTOCOL = IPC) (KEY=EXTPROC))
    )
  )

SID_LIST_LISTENER =
  (SID_LIST =
    (SID_DESC = 
      (GLOBAL_DBNAME = <SID>.<xyz.com>)
      (SID_NAME = <SID>)
      (ORACLE_HOME = /oracle/ora81)
    )
    (SID_DESC = 
      (SID_NAME = <SID>)
      (ORACLE_HOME = /oracle/ora81)
      (PROGRAM=EXTPROC)
    )
  )

Static Service Information

Static service information is not required in the listener.ora listener configuration file for Oracle8i. However, these parameters are required for pre-Oracle8i versions of Oracle and to allow Oracle Enterprise Manager to discover databases. Static service information parameters are SID_NAME, GLOBAL_DBNAME and ORACLE_HOME. Also with Parallel Server and multiple instances a single service name can identify multiple Oracle instances (SID's). Thus a listener servicing multiple instances simultaneously cannot function without using a service name as opposed to a SID.

Static Service IdentifierDescription
SID_NAMEThe Oracle System Identifier or SID identifies a database instance as in the INSTANCE_NAME parameter in the parameter file.
GLOBAL_DBNAMEThe global database name is a concatentation of a domain and a database name. The GLOBAL_DBNAME is the same as SERVICE_NAMES parameter in the parameter file or a concatentation of the DB_DOMAIN and the DB_NAME parameters in the parameter file. For example, <SID>.xyz.com. Do not set the GLOBAL_DBNAME parameter in the listener.ora file when using failover / TAF or when using multiple listeners or Oracle Parallel Server. Setting the GLOBAL_DBNAME parameter under these circumstances will disable failover and TAF.
ORACLE_HOMEThis value is the Oracle installation directory, such as /oracle/product/8.1.7.

The listener can also listen from a single machine on multiple IP-Addresses as shown below and the IPC protocol address is used to allow calling of external functions from PL/SQL code.

(address=(protocol=tcp)(host=<ip-address-1>)(port=1521))
(address=(protocol=tcp)(host=<ip-address-2>)(port=1522))
(address=(protocol=ipc)(key=PNPKEY))

Service Registration to the Listener

Service registration involves PMON and the registering of instance information plus instance and dispatchers' state and load with a listener process. The registered information is then used by the listener to forward client connection requests to appropriate service handlers. Thus the listener can always detect the usability of an instance (is the instance up), for example in an Oracle Parallel Server environment. Basically everything required for the listener to operate effectively is provided using service registration, even down to dispatcher load rates when using MTS, thus allowing the listener to decide which dispatcher process to pass a request to when load balancing between dispatchers.

Note that the parameters service_names (database service name) and instance_name (database instance name) must be set in the parameter file for service registration to function.

service_names = <database SID>.<hostname>
instance_name = <database SID>

The parameter local_listener is used to specifiy a network name. This network name will resolve to an address list of local listeners. Local listeners are listener processes running on the same machine as the database instance. The address list must be specified in the file specified by the naming method in use, ie. the tnsnames.ora file.

Non-Default Address Listener Configuration

PMON registers with the local listener on default TCP/IP address on port 1521. The LOCAL_LISTENER parameter must be set to register PMON with another listener. The LOCAL_LISTENER value must be resolved using a net service name in the tnsnames.ora file or in an Oracle Names Server. Set the LOCAL_LISTENER parameter in the parameter file to the local listener alias, the name of the listener in the listener.ora file. Thus setting the LOCAL_LISTENER parameter to LISTENERx requires a reciprocal tnsnames.ora entry as shown below.

LISTENERx=(address=(protocol=tcp)(host=<hostname>)(port=1422))

The Parameter File

local_listener=<listener>

The Local Naming Method File (tnsnames.ora)

<listener> =
  (DESCRIPTION =
    (ADDRESS_LIST =
      (ADDRESS = (PROTOCOL = TCP) (HOST = <hostname>) (PORT = 1521) )
      (ADDRESS = (PROTOCOL = TCP) (HOST = <hostname>) (PORT = 1522) )
    )
  )

Service Registration with Remote Listeners

Service registration can be performed with remote listeners and can be configured using the listener atttribute of the mts_dispatchers parameter in the parameter file.

MTS_DISPATCHERS = "(PROTOCOL = TCP) (LISTENER = <listener>)"

Once again the listener alias (<listener>) must be resolved using a naming method such as tnsnames.ora as in the previous example.

Multiple Listeners

Multiple listener processes can be created. Whenever a database connection request is made it is the listener process which will pass the connection request to either a dispatcher or dedicated server process. Many connection requests can cause a connection requests backlog, each connection requiring processes and memory. Even creation of a connection takes processing time; processing time is a valuable resource. Thus the fewer connections created the more resources available for other processing. Creation of multiple listener processes can effectively, share handling of and passing-off to dedicated server and dispatcher processes of, connection requests; effectively allowing the enabling of connection pooling and/or load balancing. Multiple listeners could also be used to allow for multiple databases, versions of Oracle or even to split different client connection requests with differing listener configurations depending on the type of processing the client is performing. Note that different port numbers for each listener in the example below. This of course assumes that these two listeners are running on the same host machine.

LISTENER =
  (DESCRIPTION_LIST =
    (DESCRIPTION =
      (ADDRESS = (PROTOCOL = TCP) (HOST = <hostname>) (PORT = 1521))
      (PROTOCOL_STACK = (PRESENTATION = TTC) (SESSION = NS))
    )
  )

LISTENER2 =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP) (HOST = <hostname>) (PORT = 1522))
    (PROTOCOL_STACK = (PRESENTATION = TTC) (SESSION = NS))
  )

SID_LIST_LISTENER =
  (SID_LIST =
    (SID_DESC = (ORACLE_HOME = /oracle/ora81) (SID_NAME = <SID>))
  )

SID_LIST_LISTENER2 =
  (SID_LIST =
    (SID_DESC = (ORACLE_HOME = /oracle/ora81) (SID_NAME = <SID>))
  )

LOGGING_LISTENER = OFF
LOGGING_LISTENER2 = OFF

Connection Load Balancing and Failover

Connection load balancing can only be enabled when multiple listeners are configured by setting the attribute load_balance = ON within the tnsnames.ora file. Note the failover = on attribute will cause a client connection request to failover the client connection request to another listener if the connection to the first listener process fails. There is a runtime active failover concept configuration implementation called Transparent Application Failover (TAF). TAF is intended for use with Oracle Parallel Server or Oracle Fail Safe where connection failure can result in automatic reconnection and resumption of partially completed SELECT statement processing. Generally failover is between two separate database instances in an Oracle Parallel Server environment (Net8 Transparent Application Failover (TAF)).

<name> =
  (DESCRIPTION =
    (ADDRESS_LIST =
      (FAILOVER = ON)
      (LOAD_BALANCE = ON)
      (ADDRESS = (PROTOCOL = TCP) (HOST = <hostname>) (PORT = 1521))
      (ADDRESS = (PROTOCOL = TCP) (HOST = <hostname>) (PORT = 1522))
    )
    (CONNECT_DATA = (SID = <SID>) (ORACLE_HOME = /oracle/ora81))
  )

Connection Pooling Parameters

Connection pooling can only be enabled when using MTS. The sharing of a dispatcher process' set of connections must be enabled to connect to many shared client processes. With dispatcher connection pooling physical connections are maximised to multi-threaded server processes. A timeout mechanism can also be utilised to release idle connections for use by other client processes. Enable connection pooling by setting the POOL = ON attribute in the MTS_DISPATCHERS parameter in the parameters file.

MTS_DISPATCHERS = "(PROTOCOL = TCP) (DISPATCHERS = 1) (POOL = ON) (TICK = 1) (CONNECTIONS = 1000) (SESSIONS = 500)"
MTS_DISPATCHERS = "(PROTOCOL = TCP) (DISPATCHERS = 1) (POOL = ON) (TICK = 1) (CONNECTIONS = 750)"

Listener Queue Size

With large volumes of traffic a connection queue to handle listener processing can be specified to handle high volumes of requests. An increased listener connection queue size can handle larger numbers of connection requests concurrently. Change the listener connection requests queue size for each listener in the listener.ora file by setting the queuesize=[n] parameter. Note that listener queue sizes can only be altered using TCP/IP or DECnet. Default queue size on Solaris is 5 and is 50 for NT.

LISTENER =
  (DESCRIPTION_LIST =
    (DESCRIPTION =
      (ADDRESS = (PROTOCOL = TCP)(HOST = <hostname>)(PORT = 1521)(QUEUESIZE = 50))
      (PROTOCOL_STACK = (PRESENTATION = TTC) (SESSION = NS))
    )
  )

SID_LIST_LISTENER =
  (SID_LIST =
    (SID_DESC = (ORACLE_HOME = /oracle/ora81) (SID_NAME = <SID>))
  )

LOGGING_LISTENER = OFF

Connection Timeouts

Connection timeouts can be controlled by setting the TNS Timeout value (CONNECT_TIMEOUT_LISTENER = [n]) value in the listener.ora file as shown below or by setting the SQLNET.EXPIRE_TIME =[n] parameter in the sqlnet.ora file as shown below.

LISTENER =
  (DESCRIPTION_LIST =
    (DESCRIPTION =
      (ADDRESS = (PROTOCOL = TCP)(HOST = <hostname>)(PORT = 1521))
      (PROTOCOL_STACK = (PRESENTATION = TTC) (SESSION = NS))
    )
  )

SID_LIST_LISTENER =
  (SID_LIST =
    (SID_DESC = (ORACLE_HOME = /oracle/ora81) (SID_NAME = <SID>))
  )

CONNECT_TIMEOUT_LISTENER = 30
LOGGING_LISTENER = OFF

Pre-Spawned Dedicated Servers

In the case of a non-MTS configuration a connection request is received by the listener. The listener will then pass the client process an address for an available dedicated server process which is spawned if not available. In the case of an MTS configuration the listener will pass the client process the address of an available dispatcher process (spawned if non available) which in turn communicates with the database server using a shared server process. In a non-MTS configuration there are a number of pre-spawned dedicated server processes. If a user connection request is serviced and all dedicated server processes are actively servicing other client connections then the listener will spawn another dedicated server process. This process will occur if two attributes in the listener.ora file are adhered to. PRESPAWN_MAX must always exceed the number of all active and idle pre-spawned dedicated server processes and the attribute POOL_SIZE is not exceeded. The POOL_SIZE attribute places a limitation on the number of idle pre-spawned dedicated server processes.

LISTENER =
  (DESCRIPTION_LIST =
    (DESCRIPTION =
      (ADDRESS = (PROTOCOL = TCP) (HOST = <hostname>) (PORT = 1521))
      (PROTOCOL_STACK = (PRESENTATION = TTC) (SESSION = NS))
    )
  )

SID_LIST_LISTENER =
  (SID_LIST =
    (SID_DESC = 
      (GLOBAL_DBNAME = <SID>.<hostname>)
      (SID_NAME = <SID>)
      (ORACLE_HOME = /oracle/ora81)
      (PRESPAWN_MAX = 20)
      (PRESPAWN_LIST =
        (PRESPAWN_DESC =
          (PROTOCOL = TCP)
          (POOL_SIZE = 5)
          (TIMEOUT = 10)
        )
      )
    )
  )

It is possible to set different clients to different types of connections. Thus some clients could use pre-spawned dedicated servers and others could use service handlers. Service handlers involve non-pre-spawned dedicated servers and dispatcher plus shared server process combinations with MTS.

Configuring the Listener for Oracle8i JServer Connections

Set the port to 2481 for Oracle8i JServer using TCP/IP and to 2482 for TCP/IP with SSL.

(DESCRIPTION =
  (ADDRESS = (PROTOCOL = TCP)(HOST = <hostname>)(PORT = 2481 | 2482))
  (PROTOCOL_STACK =
    (PRESENTATION = GIOP)
    (SESSION = RAW)
  )
)

The Listener Control Utility (LSNRCTL)

Start the listener control utility in a shell by typing lsnrctl. Then type help to see all the possible commands as shown below.

LSNRCTL> help
The following operations are available
An asterisk (*) denotes a modifier or extended command:

start               stop                status
services            version             reload
save_config         trace               dbsnmp_start
dbsnmp_stop         dbsnmp_status       change_password
debug               test                quit
exit                set*                show*

All commands can be executed from within the LSNRCTL program as command or from a shell prompt as LSNRCTL <command> [name of listener].

Also a file can be passed into the listener control utility (LSNRCTL @<filename>) and behave as a batch script. Comments can be placed into scripts by placing a # character in front of the text to be commented, in-line or otherwise. Setting the PASSWORDS_listener parameter will force the requirement of a SET PASSWORD command for certain listener control operations such as stopping or starting the listener.

General Listener Configuration Parameters

The listener.ora configuration file resides in the $ORACLE_HOME/network/admin directory.

Address Section

DESCRIPTION, ADDRESS_LIST and ADDRESS are all used for defining protocol addresses.

LISTENER =
  (DESCRIPTION_LIST =
    (DESCRIPTION =
      (ADDRESS_LIST=
        (ADDRESS = (PROTOCOL = TCP) (HOST = <hostname>) (PORT = 1521))
        (ADDRESS = (PROTOCOL = TCP) (HOST = <hostname>) (PORT = 1522))
    )
  )

SID_LIST_listener Section

The SID_LIST_listener section is required for Oracle Enterprise Manager, pre-Oracle8i versions and external procedures. Listener startup will dynamically generate service information for Oracle8i.

SID_LIST_LISTENER =
  (SID_LIST =
    (SID_DESC = 
      (GLOBAL_DBNAME = <SID>.<hostname>)
      (SID_NAME = <SID>)
      (ORACLE_HOME = /oracle/ora81)
    )
  )
ParameterDescription
GLOBAL_DBNAMEDomain and database name.
ORACLE_HOMEOracle installation directory.
PROGRAMExternal executable library program.
SID_NAMEOracle System Identifier (SID).
SID_[ LIST | DESC ]A list of SIDs or a single SID.
PRESPAWN_MAXMaximum pre-spawned dedicated servers created at database startup by the listener.
PRESPAWN_ [ LIST | DESC ]List of pre-spawned dedicated server protocol descriptions and protocol descriptions.
CONNECT_TIMEOUT_listenerValid connection request wait-time after a connection made.
LOG_[ DIRECTORY | FILE ]_listenerDefault to $ORACLE_HOME/network/log/listener.log.
LOGGING_listener [ ON | OFF ] 
OSS.SOURCE_MY_WALLETWallet locations containing certificates, keys and trustpoints using SSL secure connections. Part of Oracle Advanced Security.
PASSWORDS_listenerUnencrypted password for the listener.
SAVE_CONFIG_ON_STOP_listener [ TRUE | FALSE ]Saves current configuration to the listener.ora file.
SSL_CLIENT_AUTHENTICATION [ TRUE | FALSE ]Client authentication using SSL.
START_WAIT_TIME_listener = nNetwork listener sleeps for n seconds prior to LSNRCTL status command response.
TRACE_[ DIRECTORY | FILE | FILELEN | FILENO | TIMESTAMP ]_listenerDefault trace file is $ORACLE_HOME/network/trace/listener.trc. Can also limit file length and create multiple files, ie. listener1.trc, listener2.trc, etc. Can also add a timestamp to each trace file listener event.
USE_PLUG_AND_PLAY_listenerForces listener to register database information with Oracle Names servers present and accessible on the network.