This chapter provides a complete listing of the listener.ora file configuration parameters.
This chapter contains these topics:
Listener configuration, stored in the listener.ora file, consists of the following elements:
Name of the listener
Protocol addresses that the listener is accepting connection requests on
Database services
Dynamic service registration, a feature of Oracle9i and Oracle8, 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 operating systems and the ORACLE_HOME\network\admin directory on Windows. listener.ora can also be stored the following locations:
The directory specified by the TNS_ADMIN environment variable or registry value
On UNIX operating systems, the global configuration directory. For example, on the Solaris Operating System, this directory is /var/opt/oracle.
|
See Also: Oracle operating system-specific documentation |
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 onelistener.ora file. However, Oracle Corporation recommends running only one listener for each node in most customer environments. |
Example 7-1 shows a listener.ora file for a listener named LISTENER, which is the default name of the listener.
Example 7-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=/oracle10g) (SID_NAME=sales)) (SID_DESC= (SID_NAME=plsextproc) (ORACLE_HOME=/oracle10g) (PROGRAM=extproc)))
This section lists and describes the listener.ora file parameters. Listener configuration parameters fall into the following categories:
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 4, "Protocol Address Configuration" for information about theADDRESS_LIST parameter |
Purpose
Use the parameter DESCRIPTION as a container for listener protocol addresses.
Example
listener_name= (DESCRIPTION= (ADDRESS=(PROTOCOL=tcp)(HOST=hr-server)(PORT=1521)) (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521)))
Purpose
Use the parameter ADDRESS to specify a single listener protocol address.
Embed this parameter under the DESCRIPTION parameter.
|
See Also: Chapter 4, "Protocol Address Configuration" for descriptions of the correct parameters to use for each type of support protocol |
Example
listener_name= (DESCRIPTION= (ADDRESS=(PROTOCOL=tcp)(HOST=hr-server)(PORT=1521)) (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521)))
Purpose
Use the parameter QUEUESIZE to specify the number of concurrent connection requests that the listener can accept on a TCP/IP or IPC listening endpoint (protocol address).
Embed this parameter at the end of the protocol address with its value set to the expected number of concurrent connection requests.
Default
The default number of concurrent connection requests is operating system specific. Following are the defaults for the Solaris Operating System and Windows:
Solaris Operating System: 5
Windows NT 4.0 Workstation: 5
Windows NT 4.0 Server: 50
|
See Also: Oracle Net Services Administrator's Guide for information about configuring this parameter |
Example
listener_name= (DESCRIPTION= (ADDRESS=(PROTOCOL=tcp)(HOST=hr-server)(PORT=1521)(QUEUESIZE=20)))
Purpose
Use the parameter RECV_BUF_SIZE to specify, in bytes, the buffer space for receive operations of sessions. This parameter is supported by the TCP/IP, TCP/IP with SSL, and SDP protocols.
|
Note: Additional protocols might support this parameter on certain operating systems. Refer to operating-system specific documentation for information about additional protocols that support thi parameter. |
Embed this parameter under the DESCRIPTION parameter or at the end of the protocol address with its value set to the expected number of bytes.
Default
The default value for this parameter is operating-system specific. The default for the Solaris 2.6 Operating System is 32768 bytes (32 KB).
Usage Notes
|
See Also: Oracle Net Services Administrator's Guide for information about configuring this parameter |
Example
listener_name= (DESCRIPTION= (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521) (RECV_BUF_SIZE=11784)) (ADDRESS=(PROTOCOL=ipc)(KEY=extproc) (RECV_BUF_SIZE=11784))) listener_name= (DESCRIPTION= (RECV_BUF_SIZE=11784)) (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521) (ADDRESS=(PROTOCOL=ipc)(KEY=extproc)))
Purpose
Use the parameter SEND_BUF_SIZE to specify, in bytes, the buffer space for send operations of sessions. This parameter is supported by the TCP/IP, TCP/IP with SSL, and SDP protocols.
|
Note: Additional protocols might support this parameter on certain operating systems. Refer to operating-system specific documentation for information about additional protocols that support thi parameter. |
Embed this parameter under the DESCRIPTION parameter or at the end of the protocol address.
Default
The default value for this parameter is operating-system specific. The default for the Solaris 2.6 Operating System is 8192 bytes (8 KB).
Usage Notes
|
See Also: Oracle Database Net Services Administrator's Guide for information about configuring this parameter |
Example
listener_name= (DESCRIPTION= (ADDRESS_LIST= (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521) (SEND_BUF_SIZE=11280)) (ADDRESS=(PROTOCOL=ipc)(KEY=extproc) (SEND_BUF_SIZE=11280)))) listener_name= (DESCRIPTION= (ADDRESS_LIST= (SEND_BUF_SIZE=11280)) (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521) (ADDRESS=(PROTOCOL=ipc)(KEY=extproc))))
You can use the SID_LIST section of the listener.ora to statically configure service information for the listener.
The SID_LIST section is required for Oracle8 release 8.0 or Oracle7 database services, as well as external procedure calls and Heterogeneous Services, and some management tools, including Oracle Enterprise Manager.
SID_LIST_listener_name= (SID_LIST= (SID_DESC= (GLOBAL_DBNAME=global_database_name) (SID_NAME=sid) (ORACLE_HOME=oracle_home)) (SID_DESC=...))
For later database releases, the listener uses the dynamic service information about the database and instance it has received through service registration before using statically configured information in the listener.ora file. Therefore, the SID_LIST is not required, unless Oracle Enterprise Manager is used to monitor an Oracle9i or Oracle8 database.
Purpose
Use the parameter SID_LIST to identify a list of SID descriptions.
Example
SID_LIST_listener_name= (SID_LIST= (SID_DESC=...) (SID_DESC=...))
Purpose
Use the parameter SID_DESC to specify 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:
Purpose
Use the parameter ENVS 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. 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 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=/oracle10g) (PROGRAM=extproc) (ENVS="LD_LIBRARY_PATH=/oracle/10g/lib:/oracle/10g/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")))
Purpose
Use the parameter GLOBAL_DBNAME to identify the database service.
While processing a client connection request, the listener tries to match the value of this parameter with the value of the SERVICE_NAME parameter in the client connect descriptor. If the client connect descriptor uses the SID parameter, then the listener does not attempt to map the values. This parameter is primarily intended for configurations with Oracle8 release 8.0 or Oracle7 databases (where dynamic service registration is not supported for dedicated servers). This parameter may also be required for use with Oracle9i and Oracle8 database services by some configurations and management tools.
The value for this parameter is typically obtained from the combination of the DB_NAME and DB_DOMAIN parameters (DB_NAME.DB_DOMAIN) in the initialization parameter file, but the value can also contain any valid name used by clients to identify the service.
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)))
Purpose
Use the parameter ORACLE_HOME to identify 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)))
Purpose
Use the parameter PROGRAM to identify the service executable program name.
Embed this parameter under the SID_DESC parameter.
Example
SID_LIST_listener_name= (SID_LIST= (SID_DESC= (SID_NAME=sales) (ORACLE_HOME=/usr/oracle) (PROGRAM=extproc)))
Purpose
Use the parameter SID_NAME to identify 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)))
Purpose
Use the parameter SDU to instruct Oracle Net to optimize the transfer rate of data packets being sent across the network with the session data unit (SDU) size you specify.
Embed this parameter under the SID_DESC parameter.
Usage
|
See Also: Oracle Database Net Services Administrator's Guide for information about configuring this parameter |
Default
2048 bytes (2KB)
Values
512 bytes to 32768 (32 KB)
Example
SID_LIST_listener_name= (SID_LIST= (SID_DESC= (SDU=2085) (GLOBAL_DBNAME=sales.us.acme.com) (SID_NAME=sales) (ORACLE_HOME=/usr/oracle)))
This section describes the following parameters that control the behavior of the listener:
Purpose
Use the parameter ADMIN_RESTRICTIONS_listener_name to restrict runtime administration of the listener. The parameter is useful if the listener is not password-protected.
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: Oracle Database Net Services Administrator's Guide for further information about password security of the listener |
Default
off
Example
ADMIN_RESTRICTIONS_listener=on
Purpose
Use the INBOUND_CONNECT_TIMEOUT_listener_name parameter to specify the time, in seconds, for the client to complete its connect request to the listener after the network connection had been established.
If the listener does not receive the client request in the time specified, then it terminates the connection. In addition, the listener logs the IP address of the client and an ORA-12525:TNS: listener has not received client's request in time allowed error message to the listener.log file.
To protect both the listener and the database server, Oracle Corporation recommends setting this parameter in combination with the SQLNET.INBOUND_CONNECT_TIMEOUT parameter in the sqlnet.ora file. When specifying values for these parameters, consider the following recommendations:
Set both parameters to an initial low value.
Set the value of the INBOUND_CONNECT_TIMEOUT_listener_name parameter to a lower value than the SQLNET.INBOUND_CONNECT_TIMEOUT parameter.
For example, you can set INBOUND_CONNECT_TIMEOUT_listener_name to 2 seconds and INBOUND_CONNECT_TIMEOUT parameter to 3 seconds. If clients are unable to complete connections within the specified time due to system or network delays that are normal for the particular environment, then increment the time as needed.
|
See Also: Oracle Database Net Services Administrator's Guide for information about configuring these parameters |
Default
60 seconds
Example
INBOUND_CONNECT_TIMEOUT_listener=2
Purpose
Use the parameter LOG_DIRECTORY_listener_name to specify the destination directory of the listener log file.
Default
The $ORACLE_HOME/network/log directory on UNIX operating systems and the ORACLE_HOME\network\log directory on Windows operating systems
Example
LOG_DIRECTORY_listener=/oracle/network/admin/log
Purpose
Use the parameter LOG_FILE_listener_name to specify the name of the log file for the listener.
Default
listener.log
Example
LOG_FILE_listener=list.log
Purpose
Use the parameter LOGGING_listener_name to turn logging on or off.
Default
on
Values
on | off
Example
LOGGING_listener=on
Purpose
Use the parameter PASSWORDS_listener_name to store 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: Oracle Database Net Services Administrator's Guide for further information about password security of the listener |
Example
PASSWORDS_LISTENER=(2D6C48144CF753AC)
Purpose
Use the parameter SAVE_CONFIG_ON_STOP_listener_name to specify whether or not runtime configuration changes are saved into the listener.ora file.
When you set the parameter to true, any parameters that 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. When you set the parameter to false, the Listener Control utility does not save the runtime configuration changes to the listener.ora file.
Default
false
Values
true | false
Example
SAVE_CONFIG_ON_STOP_listener=true
Purpose
Use the parameter SSL_CLIENT_AUTHENTICATION to specify 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.
Example
SSL_CLIENT_AUTHENTICATION=true
|
Note: This parameter is deprecated and will be desupported in a future release. If you require this parameter to run the listener, please notify Oracle Support Services. |
Purpose
Use the parameter STARTUP_WAIT_TIME_listener_name to set the number of seconds that the listener waits before responding to a Listener Control utility START command.
Default
0
Example
STARTUP_WAIT_TIME_listener=5
Purpose
Use the parameter TRACE_DIRECTORY_listener_name to specify the destination directory of the listener trace file.
Default
The $ORACLE_HOME/network/trace directory on UNIX operating systems and the ORACLE_HOME\network\trace directory on Windows
Example
TRACE_DIRECTORY_listener=/oracle/network/admin/trace
Purpose
Use the parameter TRACE_FILE_listener_name to specify the name of the trace file for the listener.
Default
listener.trc
Example
TRACE_FILE_listener=list.trc
Purpose
Use the parameter TRACE_FILELEN_listener_name to specify 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
Purpose
Use the parameter TRACE_FILENO_listener_name to specify 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
Purpose
Use the parameter TRACE_LEVEL_listener_name to turn listener tracing on, at a specific level, or off.
Default
off
Values
off for no trace output
user for user trace information
admin for administration trace information
support for Oracle Support Services trace information
Example
TRACE_LEVEL_listener=admin
Purpose
When parameter TRACE_LEVEL_listener_name is set to a specific tracing level, you can use the parameter TRACE_TIMESTAMP_listener_name to add a time stamp in the form of dd-mon-yyyy hh:mi:ss:mil to every trace event in the trace file for the listener.
Default
on
Values
on or true | off or false
Example
TRACE_TIMESTAMP_listener=true
Purpose
Use the parameter WALLET_LOCATION to specify the location of wallets. Wallets are certificates, keys, and trustpoints processed by SSL that allow for secure connections.
Syntax
Oracle wallets on file system:
WALLET_LOCATION=
(SOURCE=
(METHOD=file)
(METHOD_DATA=
(DIRECTORY=directory)
[(PKCS11=TRUE/FALSE)]))
Microsoft certificate store:
WALLET_LOCATION=
(SOURCE=
(METHOD=mcs))
Oracle wallets in the Windows 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)))
Subparameters
WALLET_LOCATION supports the following subparameters:
SOURCE: Specify the type of storage for wallets and storage location.
METHOD: Specify the type of storage.
METHOD_DATA: Specify the storage location.
DIRECTORY: Specify the location of Oracle wallets on file system.
KEY: Specify the wallet type and location in the Windows registry.
PROFILE: Specify the Entrust profile file (.epf).
INIFILE: Specify the 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 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 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)))