Oracle Net8 Configuration and Troubleshooting

The Listener Control Utility

You have to start a listener before you can use it. So after you edit the listener.ora file, you need to use the Listener Control utility to actually start the listener that you’ve defined. Listener Control (lsnrctl) is an Oracle utility that allows you to start, stop, and check the status of a listener and to make changes to a running listener.

Listener Control is a command-line utility, and you start it from the command prompt using the lsnrctl command as shown in the following example:

[oracle@donna oracle]$ lsnrctl

LSNRCTL for Linux: Version 8.1.5.0.0 - Production on 27-APR-00 20:26:54

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

Welcome to LSNRCTL, type "help" for information.

LSNRCTL>

On Windows NT systems running releases of Oracle prior to 8.1, the first two digits of the Net8 release number are used to form part of the executable name. If you’re running Oracle8, Release 8.0, for example, you would use the command lsnrct80 to start the Listener Control utility.

Starting a Listener

To start a listener, use the Listener Control utility’s START command. The START command takes the listener name as an optional argument. The following example shows the listener named PRODUCTION_LISTENER being started:

LSNRCTL> START production_listener
Starting tnslsnr: please wait...

Service OracleOraHome81TNSListenerproduction_listener start pending.
Service OracleOraHome81TNSListenerproduction_listener started.
TNSLSNR for 32-bit Windows: Version 8.1.5.0.0 - Production
System parameter file is E:\Oracle\Ora81\network\admin\listener.ora

If you omit the listener name as an argument, then Listener Control will start what is referred to as the current listener . The current listener is one that you’ve chosen, using the SET CURRENT_LISTENER command, to be the default for all commands that take a listener name as a parameter. The default current listener is named LISTENER. LISTENER is also the default listener name used when you do a fresh install of Oracle. The fact that those two names match is the reason you can often start a listener simply by using the START command, as shown in this next example:

LSNRCTL> START
Starting /s01/app/oracle/product/8.1.5/bin/tnslsnr: please wait...

TNSLSNR for Linux: Version 8.1.5.0.0 - Production
System parameter file is /s01/app/oracle/product/8.1.5/network/admin/listener.ora

On Linux and Unix systems, the listener is implemented as a background process that you can see by issuing the ps command. For example:

[oracle@donna oracle]$ ps -e | grep tns
  569 ?        00:00:00 tnslsnr

On Windows NT systems, the listener process is implemented as an NT service, which you can see listed in the Services control panel. Also on Windows NT, when you start a listener for the first time, the Listener Control utility automatically creates a service for that listener. Unfortunately, the service is created without first checking listener.ora to verify that the listener name is valid. Here’s an example:

LSNRCTL> START foobong
Starting tnslsnr: please wait...

Failed to open service <OracleOraHome81TNSListenerfoobong>, error 1060.
Service OracleOraHome81TNSListenerfoobong created, exe <E:\Oracle\Ora81\BIN\TNSL
SNR >.
Service OracleOraHome81TNSListenerfoobong start pending.
Service OracleOraHome81TNSListenerfoobong started.
TNSLSNR for 32-bit Windows: Version 8.1.5.0.0 - Production
System parameter file is E:\Oracle\Ora81\network\admin\listener.ora
Log messages written to E:\Oracle\Ora81\network\log\foobong.log
TNS-01151: Missing listener name, foobong, in LISTENER.ORA

Here you can see that after an initial failure to contact a service named OracleOraHome81TNSListenerfoobong, the Listener Control utility went ahead and created one. After that service was created, the newly started listener read the listener.ora file, couldn’t find any parameters for itself, and consequently failed with a TNS-01151 error. The bad part about all this is that the erroneous NT service still remains. To find out how to delete it, read Section 4.6.2.

Stopping a Listener

To stop a listener, use the Listener Control utility’s STOP command. As with START, the STOP command accepts a listener name as an optional parameter. In this example, STOP is used without an argument to stop the current listener, which in this case is named LISTENER:

LSNRCTL> STOP
Connecting to (ADDRESS=(PROTOCOL=tcp)(HOST=donna.gennick.org)(PORT=1521))
The command completed successfully

On Windows NT systems, you can stop a listener by stopping its service from the Services control panel, or by using the NET STOP command from the Windows NT command prompt. To use NET STOP, you need to know the full service name. For example:

C:\>NET STOP OracleOraHome81TNSListenerproduction_listener
The OracleOraHome81TNSListenerproduction_listener service is stopping.
The OracleOraHome81TNSListenerproduction_listener service was stopped
successfully.

The one downside to stopping the service like this, without going through the Listener Control utility, is that you’re basically killing the process. There’s no orderly shutdown. With a listener, that’s not normally a problem anyway, but it can be if you are using the SAVE_CONFIG_ON_STOP option described later in this chapter.

Starting the Listener at Boot Time

You may find it convenient to configure your server so that the Net8 listener starts automatically when the system boots. This is especially helpful if you’re running an operating system that needs to be rebooted on a regular basis. On Windows NT systems, you use the Services control panel to configure a listener to start when the system boots. On Linux and Unix-based operating systems, you need to modify the system startup scripts.

Starting a listener at boot time on Windows NT systems

To configure a listener’s startup mode on Windows NT, open the Services control panel, scroll down to find the specific listener service that you want to configure, and click on the service name in order to highlight it. Figure 4.6 shows the Services control panel with the service for the listener named PRODUCTION_LISTENER highlighted.

Figure 4-6. Highlighting the service for the listener named PRODUCTION_LISTENER

In Figure 4.6, the listener’s startup type is set to manual, which means the listener won’t start at boot time. Instead, you’ll need to start it manually. To change the listener’s startup mode, click the Startup button. In the resulting dialog, select Automatic as the Startup Type, as shown in Figure 4.7.

Figure 4-7. Changing a listener’s startup mode to Automatic

When you have the startup type set the way you want it, click the OK button to close the dialog. Your change takes effect the next time you boot the server. If the startup type is Automatic, the listener starts at boot time.

Starting a listener at boot time on Linux and Unix systems

On Linux and Unix systems, you can modify the startup scripts to start the listener at boot time. There are several approaches to doing this, and you’ll have to find one that you and your system administrator can agree upon. One possible approach is to simply add the necessary commands to the dbstart script used to start your databases.

Another reasonable approach is to create a script to start and stop the listener, and link it to one of the runlevel directories. The example in this section shows you how to do this on a system running Red Hat Linux 6.0.

To start with, you need a shell script capable of starting and stopping the listener. The script needs to support two arguments, start and stop, and it needs to reside in the /etc/rc.d/init.d directory. The following commands, placed in a file named dbora , are sufficient to start and stop the default listener named LISTENER:

#!/bin/sh

case "$1" in
  start)
    echo -n "Starting the Oracle Net8  Listener..."
    su - oracle -c "lsnrctl start listener"
  ;;
  stop)
    echo -n "Stopping the Oracle Net8 Listener..."
    su - oracle -c "lsnrctl stop listener"
  ;;
esac
exit 0

The case statement in this script looks at the first argument to see whether it is start or stop. Those are the arguments that the Linux startup scripts will pass, depending on whether the system is being booted or shut down. The two su commands each change the current user to oracle. Because the hyphen (-) is used between the su command and the username, the oracle user’s login script will be executed in order to establish the proper environment settings. The -c option on the command is used to execute a single operating-system command.

Warning

The dbora script shown here will fail if the oracle user’s login script prompts for any values. In order for the dbora script to function properly, make sure that the oracle user’s login script is non-interactive.

Once you’ve created the dbora script as shown here, you should be able to test it while logged in as root using the following commands:

./dbora start
./dbora stop

After you have the script working, you can link it into your startup scripts by using two commands such as these:

ln -s /etc/rc.d/init.d/dbora /etc/rc.d/rc0.d/K10dbora
ln -s /etc/rc.d/init.d/dbora /etc/rc.d/rc5.d/S99dbora

The first ln command shown here creates a symbolic link in the rc0.d directory, which contains the scripts to be executed for runlevel 0. On Red Hat Linux, runlevel is used to shut down the system. The Kxxx scripts are used to shut down processes before the system is halted. The second ln command creates a symbolic link to the rc5.d directory and names the script beginning with an S. The Sxxx scripts are invoked to start services when a Linux system boots. Runlevel 5 is the runlevel at which the X Windows system runs, and it happens to be the default runlevel on our system. If you boot to a different runlevel, then you’ll need to link to the appropriate directory.

Tip

Your system may already have a dbora script containing commands to automatically start databases at boot time. If that’s the case, you can either add in the commands to start and stop the listener, or you can create an entirely separate script for that purpose.

The example shown here is specific to Red Hat Linux 6.0. The general scheme for managing startup and shutdown scripts is the same for most versions of Linux and Unix, but you may encounter differences in directory structures. The example here also executes Listener Control commands directly. Any changes would need to be made by the system administrator. To give you, the DBA, more control, you can have dbora execute a script owned by the oracle user rather than directly execute lsnrctl commands. That way, you can log in as the oracle user and modify the script whenever necessary.

Other Ways to Execute Listener Control Commands

So far, you’ve only seen how to execute Listener Control commands from the Listener Control utility’s command prompt. There are, however, two other approaches that you can use. One allows you to execute Listener Control commands from your operating-system prompt; the other allows you to execute Listener Control scripts.

Executing Listener Control commands from the operating-system command line

To execute a Listener Control command from your operating-system command prompt, simply pass the command as an argument to the lsnrctl command used to invoke Listener Control. For example:

[oracle@donna oracle]$ lsnrctl stop listener

LSNRCTL for Linux: Version 8.1.5.0.0 - Production on 28-APR-00 15:12:13

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

Connecting to (ADDRESS=(PROTOCOL=tcp)(HOST=donna.gennick.org)(PORT=1521))
The command completed successfully
[oracle@donna oracle]$ lsnrctl start listener

LSNRCTL for Linux: Version 8.1.5.0.0 - Production on 28-APR-00 15:13:16

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

Starting /s01/app/oracle/product/8.1.5/bin/tnslsnr: please wait...

TNSLSNR for Linux: Version 8.1.5.0.0 - Production
System parameter file is /s01/app/oracle/product/8.1.5/network/admin/listener.ora
...
[oracle@donna oracle]$

This technique is ideal if you want to start or stop a listener from within a shell script. It does, however, require that you restart the Listener Control program for each command that you want to execute.

Executing Listener Control commands from a script file

If you have several Listener Control commands to execute, and you don’t want to invoke the Listener Control utility separately for each command, you can use the at sign character (@) to pass in a filename. This file may contain one or more valid Listener Control commands. As an example, say you had a file named start_listener that contained the following commands:

start listener
set connect_timeout 60
trace off

If you had such a file, you could execute it using a command like this:

lsnrctl @start_listener

The at sign character (@) actually represents a valid Listener Control command. It causes the Listener Control utility to open the named file and to read and execute commands from that file.

Tip

You won’t see this documented in the manuals, nor in the online help, but the @ command may even be used from the Listener Control command prompt.