Understanding SQL*Net

Contents Glossary Index Home Previous Next

Using the Listener Control Utility

The network listener establishes listen endpoints on a machine. These listen endpoints are well-known addresses that clients and servers use to connect to a database. The Listener Control Utility, LSNRCTL, is a tool that you run from the operating system prompt to start and control the listener. For SQL*Net use, the general form of the Listener Control Utility is: 

LSNRCTL command [listener_name]

In this syntax:

LSNRCTL Specifies the name of the tool that controls the listener. In some operating systems, this fixed parameter is case sensitive. If the operating system is case sensitive, enter LSNRCTL in lowercase.
command Specifies the action to be performed.
listener_name Specifies the listener name defined in LISTENER.ORA. If listener_name is not included, the default value LISTENER is used.
You can also issue Listener Control commands at the program prompt. When you enter LSNRCTL on the command line, the program is opened. You can then enter the desired commands from the program prompt. For example, the following command starts the database subagent for a node managed by SNMP support.

LSNRCTL> dbsnmp_start

Commands for LSNRCTL Information

The Listener Control Utility has three commands that provide information about LSNRCTL itself. These commands are HELP, SET, and SHOW.

HELP

HELP provides a list of all the LSNRCTL commands available. An example follows:

iris[331] lsnrctl 
 
LSNRCTL for SunOS: Version 2.3.1.1.0 - Beta on 17-AUG-95 17:15:02 
 
Copyright (c) Oracle Corporation 1994.  All rights reserved. 
 
Welcome to LSNRCTL, type "help" for information. 
 
LSNRCTL> help 
The following operations are available 
An asterisk (*) denotes a modifier or extended command: 
 
start               stop                status 
services            version             reload 
trace               spawn               dbsnmp_start 
dbsnmp_stop         dbsnmp_status       change_password 
quit                exit                set* 
show*

SET

This command lists the operations that can be set using the SET command. 

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

password             trc_file             trc_directory
trc_level            log_file             log_directory
log_status           current_listener     connect_timeout
startup_waittime     use_plugandplay

SHOW

This command lists the operations that can be set using the SHOW command. 

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

trc_file             trc_directory        trc_level
log_file             log_directory        log_status
current_listener     connect_timeout      startup_waittime
snmp_visible         use_ckpfile          use_plugandplay

LSNRCTL Commands to Control the Listener

The following commands act on the listener. If there is more than one listener on the node, the command acts against the default LISTENER, unless you provide another listener name on the command line.

CHANGE_PASSWORD [listener_name]

You can dynamically change the password of a listener using LSNRCTL. From within LSNRCTL, enter the following:

change_password

The control utility prompts you for your old password, then for the new one. It asks you to re-enter the new one, then changes it.

Note: Neither the old nor the new password displays during this procedure.

The following is an example of changing a password:

iris> lsnrctl

LSNRCTL for SunOS: Version 2.3.2.0.0 - on 10-Sep-95 18:59:34
Copyright (c) Oracle Corporation 1994. All rights reserved.
Welcome to LSNRCTL, type "help" for information.
LSNRCTL> change_password
Old password:
New password:
Reenter new password:
Connecting to (ADDRESS=(PROTOCOL=ipc)(KEY=iris))
Password changed for LISTENER
The command completed successfully
LSNRCTL>

SPAWN

Use the SPAWN command to start a program stored on the machine on which the listener runs, and which is listed with an alias in the LISTENER.ORA file.

For example, you might create a program called NSTEST, and manually add the following to the LISTENER.ORA file:

nstest = (PROGRAM=(NAME=nstest)(ARGS=test1)(ENVS='ORACLE_HOME=/usr/oracle'))

To run the NSTEST program, you would enter the following:

lsnrctl spawn nstest

START [listener_name]

Starts the named listener. If no listener name is entered, LISTENER is started by default.

STOP [listener_name]

Stops the named listener. If no listener name is entered, LISTENER is stopped by default.

Note: You must have set a valid password if one is listed in the LISTENER.ORA parameter PASSWORDS_listener_name to be able to use this command.

STATUS [listener_name]

Displays basic information: version, start time, uptime, what LISTENER.ORA file is used, and whether tracing is turned on.

SERVICES [listener_name]

Provides detailed information about the services the listener listens for: how many connections have been established, how many refused. It displays three different types of services: dedicated servers from LISTENER.ORA, dispatcher information, and prespawned shadows.

Note: You must have set a valid password if one is listed in the LISTENER.ORA paramete,r PASSWORDS_listener_name, to be able to use this command.

RELOAD [listener_name]

Shuts down everything except listener addresses, and re-reads the LISTENER.ORA file. This command enables you to add or change services without rebooting the system.

Note: You must have set a valid password, if one is listed in the LISTENER.ORA file parameter PASSWORDS_listener_name, to be able to use this command.

TRACE [listener_name] level

Turns on tracing for the listener. Choices of level are OFF, USER, or ADMIN. USER provides a limited level of tracing; ADMIN provides a more detailed trace. This command overrides the setting in the LISTENER.ORA file. (This command has the same functionality as SET TRC_LEVEL.)

Note: You must have set a valid password, if one is listed in the LISTENER.ORA file parameter PASSWORDS_listener_name, to be able to use this command.

For detailed information on how to use tracing, see the Oracle Network Products Troubleshooting Guide.

VERSION [listener_name]

Use this command if you are asked to provide version information to Oracle Worldwide Customer Support. It provides version numbers for the following:

DBSNMP_START

Use this command to start the SNMP subagent for an Oracle database running on the same node.

DBSNMP START must be run locally--you cannot run it remotely.

DBSNMP_STOP

Use this command to stop the SNMP subagent for an Oracle database running on the same node.

DBSNMP STOP must be run locally--you cannot run it remotely.

DBSNMP_STATUS

Use this command to verify whether the SNMP subagent for an Oracle database is running.

DBSNMP STATUS must be run on the same node the Oracle database is on.

SET PASSWORD [listener_name]

Enter this command if you want to perform administrator-only tasks on the listener. For example, you must enter the SET PASSWORD command before you can stop the listener. The password should match one listed in the LISTENER.ORA file. You may enter this command when you start up the shell or any time during your session.

The preferred, secure way to enter your password is in interactive mode. Enter the command from within LSNRCTL, for example, 

LSNRCTL> SET PASSWORD

The Listener Control Utility responds:

enter listener password:

When you enter your password and press [Return], the password is not echoed on the terminal. You receive the message:

Command successful

Note: You must enter the SET PASSWORD command before you can stop the listener (with the STOP [listener_name)

Note: The listener supports encrypted and unencrypted passwords.

SET TRC_LEVEL [listener_name] level

Turns on tracing for the listener. Choices of level are OFF, USER, or ADMIN. Selecting USER provides a limited level of tracing; ADMIN provides a more detailed trace. This command overrides the setting in the LISTENER.ORA file. (This command has the same functionality as TRACE.)

Note: You must have set a valid password, if one is listed in the LISTENER.ORA file parameter PASSWORDS_listener_name to be able to use this command.

For detailed information on how to use tracing, see the Oracle Network Products Troubleshooting Guide.

SET TRC_FILE [listener_name]

Use this command to set a non-default name for the trace file.

For example, the following command sets the name of the file that contains listener trace information:

LSNRCTL> set trc_file list.trc

The computer output would be something like the following:

Connecting to (ADDRESS=(PROTOCOL=ipc)(KEY=iris))
LISTENER parameter "trc_file" set to list.trc
The command completed successfully

SET TRC_DIRECTORY [listener_name]

Use this command to set a non-default location for the trace file or to return the location to the default.

For example, the following command sets the directory in which the trace file is placed:

LSNRCTL> set trc_directory /usr/oracle/admin

The computer output would be something like the following:

Connecting to (ADDRESS=(PROTOCOL=ipc)(KEY=iris))
LISTENER parameter "trc_directory" set to /usr/oracle/admin
The command completed successfully

SET LOG_STATUS

Logging for a listener is always ON. This command has no effect.

SET LOG_FILE [listener_name]

Use this command to set a non-default name for the log file.

For example, the following command sets the name of the file that contains listener log information:

LSNRCTL> set log_file list.trc

The computer output would be something like the following:

Connecting to (ADDRESS=(PROTOCOL=ipc)(KEY=iris))
LISTENER parameter "log_file" set to list.log
The command completed successfully

SET LOG_DIRECTORY [listener_name]

Use this command to set a non-default location for the log file or to return the location to the default.

For example, the following command sets the directory in which the log file is placed:

LSNRCTL> set log_directory /usr/oracle/admin

The computer output would be something like the following:

Connecting to (ADDRESS=(PROTOCOL=ipc)(KEY=iris))
LISTENER parameter "log_directory" set to /usr/oracle/admin
The command completed successfully

SET CURRENT_LISTENER [listener_name]

If there is more than one listener on a node, any LSNRCTL command acts on the default listener (LISTENER) unless another listener has been set.

For example, suppose there were two listeners on a node, LISTENER and LSNR1. If you wanted to set or show parameters for LSNR1, you would first need to send the following command from within LSNRCTL:

LSNRCTL> set current_listener lsnr1

Any subsequent LSNRCTL commands within the same LSNRCTL session would then apply to LSNR1, unless CURRENT_LISTENER were reset. For example, if the current listener had been set to LSNR1, then the STAT command would produce something like the following output:

LSNRCTL> stat
Connecting to (ADDRESS=(PROTOCOL=IPC)(KEY=IRIS))
STATUS of the LISTENER
-----------------------
Alias 		lsnr1
Version		TNSLSNR for SunOS: Version 2.3.1.1.0- Beta
Start Date		18-Aug-95 11:25:45
Uptime		0 days 0 hr. 0 min. 3 sec
Trace Level		admin
Security		OFF
SNMP			ON
Listener Parameter File	/etc/oracle/network/admin/listener.ora
Listenr Log File	/etc/oracle/network/log/lsnr1.log
Listener Trace File	/etc/oracle/network/trace/lsnr1.trc
Services Summary...
  db1		has 1 service handler(s)
The command completed successfully

You can also display the current listener by using the LSNRCTL SHOW command.

Note: You must enter SET CURRENT_LISTENER from within the LSNRCTL utility. When you exit the utility, the setting will be lost.

SET CONNECT_TIMEOUT TIME [listener_name]

This command determines the amount of time the listener will wait for a valid connection request after a connection has been started

LSNRCTL> set connect_timeout 20

The computer output would be something like the following:

Connecting to (ADDRESS=(PROTOCOL=ipc)(KEY=iris))
LISTENER parameter "connect_timeout" set to 20
The command completed successfully

SET STARTUP_WAITTIME TIME [listener_name]

This command sets the amount of time the listener sleeps before responding to a STATUS command:

lSNRCTL> set startup_waittime 10

The computer output would be something like the following:

Connecting to (ADDRESS=(PROTOCOL=ipc)(KEY=iris))
LISTENER parameter "startup_waittime" set to 10
The command completed successfully

SET USE_PLUGANDPLAY [listener_name] ON|OFF

Use this command to determine whether the Dynamic Discovery Option of Oracle Names is enabled on a listener:

LSNRCTL> set use_plugandplay ON|OFF

By default, the value of this parameter is OFF. If Oracle Names version 2 has been installed, and you want the listener to use the Dynamic Discovery Option (that is, to register itself with a well-known Names Server, set it to ON. You can also set the value in LISTENER.ORA through Oracle Network Manager, which places a slightly different parameter into LISTENER.ORA, as follows:

use_plugandplay_listener_name=[ON|OFF]

If the Dynamic Discovery Option is enabled, you can use the LSNRCTL STATUS command to see whether a service has registered itself. For example:

LSNRCTL> stat lsnr1
Connecting to (ADDRESS=(PROTOCOL=IPC)(KEY=IRIS))
STATUS of the LISTENER
-----------------------
Alias 		lsnr1
Version		TNSLSNR for SunOS: Version 2.3.1.1.0- Beta
Start Date		18-Aug-95 11:25:45
Uptime		0 days 0 hr. 1 min. 49 sec
Trace Level		admin
Security		OFF
SNMP			ON
Listener Parameter File	/etc/oracle/network/admin/listener.ora
Listener Log File	/etc/oracle/network/log/lsnr1.log
Listener Trace File	/etc/oracle/network/trace/lsnr1.trc
Services Summary...
  db1 (Registered)	has 1 service handler(s)
The command completed successfully

SHOW [listener_name] subcommand

All of the SET commands listed except SET PASSWORD have equivalent SHOW commands. In response to one of the SHOW comands, LSNRCTL displays the current setting of the listener for that parameter.

In addition, there are two other parameters that can be shown, but not set, through LSNRCTL.

SHOW [listener_name] SNMP_VISIBLE

This command displays whether the listener is accessible to SNMP clients:

LSNRCTL> show snmp_visible

The computer output would be something like the following:

Connecting to (ADDRESS=(PROTOCOL=ipc)(KEY=iris))
LISTENER parameter "snmp_visible" set to ON
The command completed successfully

Note: The SNMP_VISIBLE parameter can be displayed, but not set, through LSNRCTL:

SHOW [listener_name] USE_CKPFILE

Use LSNRCTL to see whether the the use of a checkpoint file has been enabled in LISTENER.ORA:

LSNRCTL> show use_ckpfile

The computer output would be something like the following:

Connecting to (ADDRESS=(PROTOCOL=ipc)(KEY=iris))
LISTENER parameter "use_ckpfile" set to OFF
The command completed successfully

If USE_CKPFILE_listener_name is not set in LISTENER.ORA, and you use LSNRCTL SET commands to change listener parameters, when you stop the listener, LSNRCTL sends a message reminding you that the changes you have made are not persistent.

Note: You cannot set this parameter using LSNRCTL; it must be set in LISTENER.ORA. For more information about the use of checkpoint files, see "Persistent Changes" later in this chapter.

QUIT

Use this command to quit LSNRCTL and return to the operating system prompt. (Same as EXIT.)

EXIT

Use this command tp quit LSNRCTL and return to the operating system prompt. (Same as QUIT.)

Making Changes Persistent

If set to ON, the following parameter in LISTENER.ORA will make the changes you make by using the SET command in LSNRCTL persistent; that is, if you shut down the listener and then start it up again, the parameters will retain the values you set through LSNRCTL. 

use_ckpfile_listener_name=ON

If this parameter is in the LISTENER.ORA file, the parameters you set using LSNRCTL are saved to a checkpoint file, listener_name.CKP, either in the TNS_ADMIN directory if one exists, or in the ORACLE_HOME/NETWORK/ADMIN directory. The values in this checkpoint file will override the values set in LISTENER.ORA.

If the USE_CKPFILE parameter is set to OFF in LISTENER.ORA, the values set by LSNRCTL are lost when the listener is restarted or the LISTENER.ORA parameters are reloaded. The default is for USE_CKPFILE to be OFF.

Note: If checkpointing is enabled and parameters in LISTENER.ORA are changed, the changes will not be visible because they are overridden by the parameters in the checkpoint file. If you want the changes in LISTENER.ORA to be visible, set the value of USE_CKPFILE to OFF and use the LSNRCTL RELOAD command to reread the LISTENER.ORA file.

Examples of the Use of LSNRCTL

This section provides some examples of the most common uses of the LSNRCTL utility.

Starting the Listener

To start a default listener, that is, a listener defined in the LISTENER.ORA file using the name LISTENER, use the command: 

LSNRCTL START

Alternatively, you can enter LSNRCTL on the command line and then enter START from the program prompt.

To start a listener configured in the LISTENER.ORA file with a name other than LISTENER, include that name. For example, if the listener name is TCP_LSNR, enter: 

LSNRCTL START TCP_LSNR

Or, from the LSNRCTL program prompt, just enter:

LSNRCTL> START TCP_LSNR

Stopping the Listener

To stop the default listener, use the command: 

LSNRCTL STOP

To stop a running listener defined in LISTENER .ORA as TCP_LSNR, use the command: 

LSNRCTL STOP TCP_LSNR

Remember, if there are any passwords in the LISTENER.ORA file, you must use the SET PASSWORD command before you can use the STOP command. You must set the password from within the LSNRCTL program; you cannot set it from the operating system command line. The method for setting the password depends on whether you are using the encrypted password feature. If you are not using an encrypted password, enter the password on the LSNRCTL command line. For example, the following commands stop the TCP_LSNR using an unencrypted password:

LSNRCTL 
LSNRCTL> SET PASSWORD password
LSNRCTL> STOP TCP_LSNR

If you are using an encrypted password, enter the password in interactive mode. For example, the following commands stop the listener named TCP_LSNR:

LSNRCTL 
LSNRCTL> SET PASSWORD 
	Enter listener password (password is not displayed)
	Command successful
LSNRCTL> STOP TCP_LSNR

Stopping a listener when in batch mode is not recommended, because to do so you must include your password in a cleartext batch file, which would threaten your security. However, if you are not using an encrypted password, stopping a listener can be done by redirecting input into the command interpreter.

Note: You should not stop the listener in batch mode if it requires an encrypted password.

Different operating systems use different syntax. An example for VMS and two alternative methods for UNIX follow.

To stop a listener in batch mode on VMS, create a DCL script, with a name like LSNRSTOP.COM, as follows:

$ lsnrctl 
set password password
stop listener_name
exit

When you want to stop the listener, run the script as follows:

@LSNRSTOP

On a UNIX system or on OS/2, the following procedure would be effective:

Create a file with a name like LSNRSTOP that contains the following lines:

set password password
stop listener_name

You can then stop the listener from the command line by entering:

lsnrctl < LSNRSTOP

Alternatively, in UNIX you can stop the listener by creating a shell script named something like "lsnrstop". The shell script would look something like this::

lsnrctl <<!
set password password
stop listener_name
exit
!

You can then stop the listener from the command line by entering:

LSNRSTOP

Again, Oracle Corporation recommends against stopping a listener in batch mode because of the need to expose your password.

Note: Be careful when stopping a listener. On some platforms and with some protocols, when a listener is stopped any SQL*Net connections currently running are shut down. In some situations the connections continue, but it is then not possible to start the listener again until the running processes have been closed. It is good practice to send a warning message to all network users before stopping a listener.

Checking Listener Status

One of the most useful commands available with the Listener Control Utility is the STATUS command. With the status command, an administrator can get a view of the "state" of a listener by checking:

Suppose that a user wanted to know the status of a listener on a UNIX system defined in LISTENER.ORA with the default name LISTENER. The user would enter the following command at the operating system command line:

LSNRCTL STATUS

Following is sample output from a status report of a UNIX listener : 

LSNRCTL for SunOS: Version 2.2.2.0 - Production on 15-FEB-95 07:07:10
Copyright (c) Oracle Corporation 1995. All rights reserved.
Connecting to (ADDRESS=(PROTOCOL=IPC)(HOST=orchid)(port=1334))
STATUS of the LISTENER
------------------------
Alias                  LISTENER
Version                TNSLSNR for SunOS: Version 2.2.2.0 - 
  Production
Start Date             10-FEB-94 07:06:34
Uptime                 0 days 0 hr. 0 min. 44 sec
Trace Level            ADMIN
Security               ON
SNMP                   ON
Listener Parameter File   /private1/dvl/7012/network/admin/listener.ora
Listener Log File         /private1/dvl/7012/network/log/listener.log
Listener Trace File       /private1/dvl/7012/network/trace/listener.trc
Listening on            (ADDRESS=(PROTOCOL=tcp)(HOST=orchid)
  (port=1334)))
                        (ADDRESS=(PROTOCOL=decnet)(node=23.106)
  (object=orchid)))
Services Summary...
  orchid		has 1 service handlers
The command completed successfully

Retrieving Listener Services

A database administrator who wanted to get information about the services of the listener would enter the following commands from within LSNRCTL:

LSNRCTL>[SET PASSWORD password]
LSNRCTL> SERVICES

The output of a LSNRCTL SERVICES command follows:

LSNRCTL for SunOS: Version 2.1.3.0.0 - Production on 10-FEB-94 07:14:55

Copyright (c) Oracle Corporation 1993.  All rights reserved.

Connecting to (ADDRESS=(PROTOCOL=IPC)(KEY=ruth))
Services Summary...
  ruth		has 1 service handlers
    DEDICATED SERVER established:99 refused:0
The LSNRCTL command completed successfully

In this example, the LSNRCTL SERVICES command returned the information that the listener had established 99 connections using a dedicated server process and refused none.

In the following example the LSNRCTL SERVICES command returns information about four types of service handlers.

LSNRCTL for SunOS: Version 2.2.2.0.0 - Production on 15-Mar-1995 17:41:12



Copyright (c) Oracle Corporation 1994.  All rights reserved.



Connecting to (ADDRESS=(PROTOCOL=ipc)(KEY=orchid))

Services Summary...

   listener          has 4 service handlers

    DEDICATED SERVER established:0 refused:0

    PRESPAWNED SERVER established:0 refused:0 current:0 max:1 state:ready

      PID:15439

      (ADDRESS=(PROTOCOL=ipc)(DEV=4)(KEY=#15439.1))

    PRESPAWNED SERVER established:5 refused:0 current:0 max:1 state:ready

      PID:15441

      (ADDRESS=(PROTOCOL=tcp)(DEV=4)(HOST=139.185.22.25)(PORT=3334))

    DISPATCHER established:30 refused:0 current:7 max:21 state:ready

      D000 (machine: orchid, pid: 15406)

      (ADDRESS=(PROTOCOL=tcp)(DEV=7)(HOST=139.185.22.25)(PORT=3330))

The command completed successfully

This message shows that since this listener has been running, it has made a total of five connections using a prespawned server for TCP/IP, and that it has one running at this time. It also shows that there are seven connections currently established using a multi-threaded server dispatcher, with a total of 30 established since the process started.

Contents Glossary Index Home Previous Next