8
Listener Parameters (listener.ora)

This chapter provides a complete listing of the listener.ora file configuration parameters.

This chapter contains these topics:

• Overview of Listener Configuration File

• Listener Parameters

Overview of Listener Configuration File

Listener configuration, stored in the listener.ora file, consists of the following elements:

• Listener's name

• Protocol addresses that it is accepting connection requests on

• Services it is listening for

  Dynamic service registration, a feature of Oracle9i and Oracle8i, eliminates the need for static configuration of supported services. However, static service configuration is required if you plan to use Oracle Enterprise Manager.

• Control parameters

By default, the listener.ora file is located in the $ORACLE_HOME/network/admin directory on UNIX, and the ORACLE_HOME\network\admin directory on Windows NT. listener.ora can also be stored in the directory specified by the TNS_ADMIN environment variable or its registry value.

It is possible to configure multiple listeners, each with unique name, in one listener.ora file. Multiple listener configuration is possible because each of the top-level configuration parameters has a suffix of the listener name or is the listener name itself.

Note: It is often useful to configure multiple listeners in one listener.ora file. However, Oracle Corporation recommends running only one listener for each node in most customer environments.

Figure 8-1 shows a listener.ora file for a listener named LISTENER, which is the default name of the listener.

Figure 8-1 Example listener.ora File

LISTENER=
  (DESCRIPTION=
    (ADDRESS_LIST=
      (ADDRESS=(PROTOCOL=tcp)(HOST=sale-server)(PORT=1521))
      (ADDRESS=(PROTOCOL=ipc)(KEY=extproc))))
SID_LIST_LISTENER=
  (SID_LIST=
    (SID_DESC=
      (GLOBAL_DBNAME=sales.us.acme.com)
      (ORACLE_HOME=/usr/oracle)
      (SID_NAME=sales)))

Listener Parameters

This section lists and describes the listener.ora file parameters. Listener configuration parameters fall into the following categories:

• Protocol Address Section

• Static Service Registration (SID_LIST) Section

• Control Parameters

Protocol Address Section

The protocol address section of the listener.ora file defines the protocol addresses that the listener is accepting connection requests on. Discussed next are the most common parameters used in protocol addresses. Note that ADDRESS_LIST is also supported.

See Also: Chapter 5, "Protocol Address Configuration" for information about the ADDRESS_LIST parameter

DESCRIPTION

Purpose

The DESCRIPTION parameter contains individual listener protocol addresses.

Example

listener_name=
 (DESCRIPTION=
  (ADDRESS=(PROTOCOL=ipc)(KEY=extproc0))
  (ADDRESS=(PROTOCOL=tcp)(HOST=sales-pc)(PORT=1521)))

ADDRESS

Purpose

The ADDRESS parameter defines a single listener protocol address.

Embed this parameter under the DESCRIPTION parameter.

See Also: Chapter 5, "Protocol Address Configuration" for descriptions of the correct parameters to use for each type of support protocol

Example

listener_name=
 (DESCRIPTION=
  (ADDRESS=(PROTOCOL=ipc)(KEY=extproc0))
  (ADDRESS=(PROTOCOL=tcp)(HOST=sales-pc)(PORT=1521)))

Static Service Registration (SID_LIST) Section

You can use the SID_LIST section of the listener.ora to statically configure service information for the listener.

The SID_LIST is required for backward compatibility with Oracle8 databases, as well as external procedures and Heterogeneous Services, and some management tools, including Oracle Enterprise Manager.

Oracle9i or Oracle8i database information is dynamically registered with the listener during instance startup. Therefore, the SID_LIST is not required, unless Oracle Enterprise Manager is used to monitor an Oracle9i or Oracle8i database.

SID_LIST_listener_name=
  (SID_LIST= 
   (SID_DESC=
    (GLOBAL_DBNAME=global_database_name)
    (SID_NAME=sid)
    (ORACLE_HOME=oracle_home))
   (SID_DESC=...))

SID_LIST

Purpose

The SID_LIST parameter identifies a list of SID descriptions.

Example

SID_LIST_listener_name=
  (SID_LIST= 
   (SID_DESC=...)
   (SID_DESC=...))

SID_DESC

Purpose

The SID_DESC parameter provides service information for a specific database instance or a non-database service.

Embed this parameter under the SID_LIST parameter.

Example

SID_LIST_listener_name=  
(SID_LIST= 
   (SID_DESC=...)
   (SID_DESC=...)) 

SID_DESC permits the following parameters:

• ENVS

• GLOBAL_DBNAME

• ORACLE_HOME

• PROGRAM

• SID_NAME

ENVS

Purpose

The ENVS parameter enables you to specify environment variables for the listener to set prior to executing (as a child process) a dedicated server program or an executable specified with the PROGRAM parameter.

Embed this parameter under the SID_DESC parameter.

Note: This parameter in not supported on Windows NT. Any process spawned by the listener will simply inherit the listener's environment.

Usage Notes

Enclose an environment variable and its value within double quotes ("):

(ENVS="variable=value")

A list of environment variables and their values can be specified. Enclose the list within double quotes, from end to end, and separate environment variable definitions with commas and no space.

(ENVS="variable=value,variable=value")

Note: Single quotes (') are supported for backward compatibility.

The use of the following characters within the environment variable and/or its 
value definition (ENVS="variable=value") are not supported:

• Comma (,)

• Single quotes (')

• Double quotes (")

• Equal sign (=)

Example

SID_LIST_listener_name=
 (SID_LIST=
  (SID_DESC=
   (SID_NAME=plsextproc)
   (ORACLE_HOME=/oracle/9.0)
   (PROGRAM=extproc)
   (ENVS="LD_LIBRARY_PATH=/oracle/9.0/lib:/oracle/9.0.1/ctx/lib"))
 (SID_DESC=
  (SID_NAME=test)
  (PROGRAM=/tmp/myexec)
  (ENVS="LD_LIBRARY_
PATH=/private/xpm/lib:/private/mylibs,MYPATH=/usr/ucb:/usr/local/packages,APL_
ENV_FILE=/apl/conf/env.txt")))

GLOBAL_DBNAME

Purpose

The GLOBAL_DBNAME parameter identifies the global database name of the database, a name comprised of the database name and database domain. You can obtain the GLOBAL_DBNAME value from the SERVICE_NAMES parameter in the initialization parameter file.

Embed this parameter under the SID_DESC parameter, and ensure it matches the value of the SERVICE_NAMES parameter in the initialization parameter file.

Example

SID_LIST_listener_name=
  (SID_LIST= 
   (SID_DESC=
    (GLOBAL_DBNAME=sales.us.acme.com)
    (SID_NAME=sales)
    (ORACLE_HOME=/usr/oracle)))

ORACLE_HOME

Purpose

The ORACLE_HOME parameter identifies the Oracle home location of the service.

Embed this parameter under the SID_DESC parameter.

Example

SID_LIST_listener_name=
  (SID_LIST= 
   (SID_DESC=
     (SID_NAME=extproc)
     (ORACLE_HOME=/usr/oracle)
     (PROGRAM=extproc)))

PROGRAM

Purpose

The PROGRAM parameter identifies the service's executable program name.

Embed this parameter under the SID_DESC parameter.

Example

SID_LIST_listener_name=
  (SID_LIST= 
   (SID_DESC=
     (SID_NAME=extproc)
     (ORACLE_HOME=/usr/oracle)
     (PROGRAM=extproc)))

SID_NAME

Purpose

The SID_NAME parameter identifies the Oracle System Identifier (SID) of the instance. You can obtain the SID value from the INSTANCE_NAME parameter in the initialization parameter file.

Embed this parameter under the SID_DESC parameter.

Example

SID_LIST_listener_name=
  (SID_LIST= 
   (SID_DESC=
    (GLOBAL_DBNAME=sales.us.acme.com)
    (SID_NAME=sales)
    (ORACLE_HOME=/usr/oracle)))

Control Parameters

The sections describes the parameters that control the behavior of the listener.

ADMIN_RESTRICTIONS_listener_name

Purpose

The ADMIN_RESTRICTIONS_listener_name parameter is a security feature that enables you to restrict runtime administration of the listener. The feature can be useful if you are not using a password-protected listener.

Setting ADMIN_RESTRICTIONS_listener_name=on disables the runtime modification of parameters in listener.ora. That is, the listener will refuse to accept SET commands that alter its parameters. To change any of the parameters in listener.ora, including ADMIN_RESTRICTIONS_listener_name itself, modify the listener.ora file manually and reload its parameters (with the RELOAD command) for the new changes to take effect without explicitly stopping and restarting the listener.

Oracle Corporation recommends establishing a password to secure the listener. To establish an encrypted password, use either the Listener Control utility CHANGE_PASSWORD command or Oracle Net Manager.

See Also: Oracle9i Net Services Administrator's Guide for further information about password security of the listener

Default

off

Example

ADMIN_RESTRICTIONS_listener=on

LOG_DIRECTORY_listener_name

Purpose

The LOG_DIRECTORY_listener_name parameter specifies the destination directory for the listener log file.

Default

The $ORACLE_HOME/network/log directory on UNIX, and the ORACLE_HOME\network\log directory on Windows NT

Example

LOG_DIRECTORY_listener=/oracle/network/admin/log

LOG_FILE_listener_name

Purpose

The LOG_FILE_listener_name parameter specifies the name of the log file for the listener.

Default

listener.log

Example

LOG_FILE_listener=list.log

LOGGING_listener_name

Purpose

The LOGGING_listener_name parameter turns logging on or off.

Default

on

Values

on | off

Example

LOGGING_listener=on

PASSWORDS_listener_name

Purpose

The PASSWORDS_listener_name parameter stores an encrypted password for a listener, so that certain privileges operations, such as SAVE_CONFIG and STOP, used from the Listener Control utility are secure. An encrypted password can be set using either the Listener Control utility CHANGE_PASSWORD command or Oracle Net Manager.

See Also: Oracle9i Net Services Administrator's Guide for further information about password security of the listener

Example

PASSWORDS_LISTENER=(2D6C48144CF753AC)

SAVE_CONFIG_ON_STOP_listener_name

Purpose

If this parameter is set to true, any parameters which were modified while the listener was running using the Listener Control utility SET command are saved to the listener.ora file when the STOP command is issued.

Default

false

Values

true | false

Example

SAVE_CONFIG_ON_STOP_listener=true

SSL_CLIENT_AUTHENTICATION

Purpose

The SSL_CLIENT_AUTHENTICATION parameter specifies whether or not a client is authenticated using the Secure Sockets Layer (SSL).

Default

true

Values

true | false

Usage Notes

The database server authenticates the client. Therefore, this value should be set to false. If this parameter is set to true, the listener attempts to authenticate the client, which can result in a failure.

See Also: Oracle Advanced Security Administrator's Guide

Example

SSL_CLIENT_AUTHENTICATION=true

STARTUP_WAIT_TIME_listener_name

Note: This parameter is deprecated in Oracle9i and will be desupported in a future release. If you require this parameter to run the listener, please notify Oracle Support Services.

Purpose

The parameter STARTUP_WAIT_TIME_listener_name sets the number of seconds that the listener waits before responding to a Listener Control utility START command.

Default

0 seconds

Example

STARTUP_WAIT_TIME_listener=5

TRACE_DIRECTORY_listener_name

Purpose

The TRACE_DIRECTORY_listener_name parameter specifies the destination directory for the listener trace files.

Default

The $ORACLE_HOME/network/trace directory on UNIX, and the ORACLE_HOME\network\trace directory on Windows NT

Example

TRACE_DIRECTORY_listener=/oracle/network/admin/trace

TRACE_FILE_listener_name

Purpose

The TRACE_FILE_listener_name parameter specifies the name of the trace file for the listener.

Default

listener.trc

Example

TRACE_FILE_listener=list.trc

TRACE_FILELEN_listener_name

Purpose

The TRACE_FILELEN_listener_name parameter specifies the size of the listener trace files in kilobytes (KB). When the size is met, the trace information is written to the next file. The number of files is specified with the TRACE_FILENO_listener_name parameter.

Default

Unlimited

Example

TRACE_FILELEN_listener=100

TRACE_FILENO_listener_name

Purpose

The TRACE_FILENO_listener_name parameter specifies the number of trace files for listener tracing. When this parameter is set along with the TRACE_FILELEN_listener_name parameter, trace files are used in a cyclical fashion. The first file is filled first, then the second file, and so on. When the last file has been filled, the first file is re-used, and so on.

The trace file names are distinguished from one another by their sequence number. For example, if the default trace file of listener.trc is used, and this parameter is set to 3, the trace files would be named listener1.trc, listener2.trc and listener3.trc.

In addition, trace events in the trace files are preceded by the sequence number of the file.

Default

1

Example

TRACE_FILENO_listener=3

TRACE_LEVEL_listener_name

Purpose

The TRACE_LEVEL_listener_name parameter turns tracing on or off to a certain specified level.

Default

off

Values

off--No trace output

user--User trace information

admin--Administration trace information

support--Oracle Support Services trace information

Example

TRACE_LEVEL_listener=admin

TRACE_TIMESTAMP_listener_name

Purpose

The TRACE_TIMESTAMP_listener_name parameter adds a time stamp in the form of dd-month-yyyy hh:mm:ss to every trace event in the listener trace file.

Default

off

Values

on or true | off or false

Example

TRACE_TIMESTAMP_listener=true

WALLET_LOCATION

Purpose

The WALLET_LOCATION parameter specifies the location of wallets. Wallets are certificates, keys, and trustpoints processed by SSL that allow for secure connections.

See Also: Oracle Advanced Security Administrator's Guide

Syntax

Oracle wallets on file system:

WALLET_LOCATION=
  (SOURCE=
    (METHOD=file)
    (METHOD_DATA=
       (DIRECTORY=directory)))

Microsoft certificate store:

WALLET_LOCATION=
  (SOURCE=
     (METHOD=mcs))

Oracle wallets in the Windows NT registry:

WALLET_LOCATION=
   (SOURCE=
      (METHOD=reg)
      (METHOD_DATA=
         (KEY=registry_key)))

Entrust wallets:

WALLET_LOCATION=
   (SOURCE=
      (METHOD=entr)
      (METHOD_DATA=
         (PROFILE=file.epf)
         (INIFILE=file.ini)))

Sub-Parameters

SOURCE--Type of storage for wallets and storage location

METHOD--Type of storage

METHOD_DATA--Storage location

DIRECTORY--Location of Oracle wallets on file system

KEY--Wallet type and location in the Windows NT registry

PROFILE--Entrust profile file (.epf)

INIFILE--Entrust initialization file (.ini)

Default

None

Usage Notes

• The key/value pair for Microsoft's certificate store (MCS) omits the METHOD_DATA parameter because MCS does not use wallets. Instead, Oracle PKI (public key infrastructure) applications obtain certificates, trustpoints and private keys directly from the user's profile.

• If an Oracle wallet is stored in the Windows NT registry and the wallet's key (KEY) is SALESAPP, the storage location of the encrypted wallet is HKEY_CURRENT_USER\SOFTWARE\ORACLE\WALLETS\SALESAPP\EWALLET.P12. The storage location of the decrypted wallet is HKEY_CURRENT_USER\SOFTWARE\ORACLE\WALLETS\SALESAPP\CWALLET.SSO.

Examples

Oracle wallets on file system:

WALLET_LOCATION=  
  (SOURCE=
      (METHOD=file)
      (METHOD_DATA=  
         (DIRECTORY=/etc/oracle/wallets/databases)))

Microsoft certificate store:

WALLET_LOCATION=
   (SOURCE=
     (METHOD=mcs))
   

Oracle Wallets in the Windows NT registry:

WALLET_LOCATION=
   (SOURCE=
     (METHOD=REG)
     (METHOD_DATA=
        (KEY=SALESAPP)))

Entrust Wallets:

WALLET_LOCATION=
   (SOURCE=
     (METHOD=entr)
     (METHOD_DATA=
       (PROFILE=/etc/oracle/wallets/test.epf)
       (INIFILE=/etc/oracle/wallets/test.ini)))