Createlistener

How to create a Listener Networking Tips

Copyright © Howard Rogers 2002 3/24/2002 Page 1 of 14

How to create a Listener? The process of creating a Listener is really nothing more than knocking together a passable listener.ora file, and then using the LSNRCTL utility to start the thing. In Windows, this last step will cause a new service to be created (which is then visible in the Control Panel Services applet). On Unix, all that happens is that a new process is spawned, which then carries out the functions of the Listener. So we start with the need for a listener.ora file. What�s the best way of creating that? Well, it�s just a text file, so you could open vi or notepad and start typing. But there�s a lot of significant formatting and some crazy syntax involved, so it�s better to use the Oracle-supplied Net8 Configuration Assistant to do the job (for Oracle 9i, that utility got renamed as simply the �Net Assistant�, but it�s essentially the same tool). To launch that tool on Windows, you click [Start][Programs][Oracle - <Oracle Home>] [Network Administration][Net8 Configuration Assistant]. (Note that for 9i, the location changed: [Start][Programs][Oracle - <Oracle Home>][Configuration and Migration Tools][Net Configuration Assistant]. For Unix, you just type nwca at the command prompt, though frequently many people use the Configuration Assistant on Windows, and then ftp the resulting configuration across to the Unix server. When you start the Assistant, you�ll see this screen:



Obviously, the option we need is the top one, which is already selected. So just click [Next]. That will bring up a screen like this:

There are four options available here, but only the �Add� one will be available if this is the first Listener to be created on the Server. If there�s an existing Listener, the other three options will be available, giving you the ability to change its properties, its name, or to get rid of it altogether. Since we�re creating a new Listener, make sure �Add� is selected, and click [Next]. The screen changes to this:



The first thing you have to do is give your Listener a name. The default name, and the one offered as a default, is the strikingly unoriginal �Listener�. A Server can have several Listeners running on it simultaneously, but each must be uniquely named. So if there�s already one with this default name, you�ll have to change it here (simply highlight the suggested name, and over-type it). However, if there is no chance of the default name conflicting with an existing Listener, I�d recommend you accept the default, however unoriginal it is. The reason for that is simple: being the default, Oracle relies on its existamce for such important things as automatic Instance registration (the ability of an Instance to automatically tell the Listener that it exists). Use a non-default Listener name, and you�ll be signing up to having to perform additional configuration of the init.ora for all Instances that this Listener is going to service. Having chosen a name (or if you like the suggested one), click [Next]. The next screen will then appear:

Here, you have to state which networking protocols the new Listener will be listening on. A single Listener can listen on many protocols, so you don�t need one Listener per protocol. The available protocols are shown in the left-hand pane. The selected ones are on the right. TCP/IP is the default protocol, and so it should already be in the right-hand pane. To add others, click on an entry on the left, and then use the top �>� button to transfer it across to the right. Reverse the process to de-select a protocol. You can then use the up and down buttons on the right to prioritise the selected protocols if there are more than one of them. Prioritising protocols like this only makes a difference to the formatting of the listener.ora text file, and has no effect on the subsequent performance of the Listener.



Incidentally, the list of available protocols will vary from machine to machine, depending on what Oracle networking protocol adapters you selected to install when installing Oracle in the first place. When the correct protocols are displayed in the right-hand pane, click [Next]. The next screen will then appear:

Here, you select the port that the Listener will monitor to detect connection requests to a database. A single Listener can only listen on one port, however many databases it�s servicing connection requests for. The default port for standard TCP/IP connections is 1521 (it used to be 1526 in Oracle 7). This is a good one to accept because, again, if you elect to listen on a non-default port, Automatic Instance Registration won�t work without some extra configuration of each database�s init.ora. This happens to be the screen to configure standard TCP/IP connections. If you�ve configured other protocols on the previous screen, you�ll need to supply the appropriate information those other protocols need (for example, Named Pipes requires you to supply a pipe name; IPC requires a Key Value). If you selected the TCPS protocol on the previous screen, which is a secured TCP/IP protocol, the default port number suggested will be 2484. That can again be accepted or changed by supplying your own port number. Finally, if you�ve selected multiple protocols on the previous screen, the relevant configuration screens (such as this one for TCP) will display one after the other, in the order in which you prioritised the protocols when selecting them.



So, having configured how the Listener should interact with your networking protocol(s), click [Next], and the following screen should appear:

Assuming you only want to configure one Listener at the present time, you�d accept the already-highlighted �No� option, and just press [Next]. If you choose [Yes], you�ll go back to the beginning. If you answered �No�, clicking [Next] will bring up a confirmation message that Listener Configuration is complete. One more click of the [Next] option takes you back to the first screen we saw, where you can click [Finish], at which point the wizard will close. On Windows, by the time you get the ‘configuration complete’ confirmation message, Oracle will have created and started the relevant service for you. On Unix, the Listener process will be started automatically, but obviously no service will have been created, since no such concept exists on Unix. The fact that the Listener is created and started automatically for you on completion of the Assistant wizard can be a problem, particularly if you�ve used the Windows version intending to ftp the resulting listener.ora to your Unix server, or if you�ve used the wizard on a Windows client intending to transfer it later to a Windows server. Expect dire errors to be raised when a listener.ora referencing hostname �Britten�, for example, is transferred to an Oracle server actually called �Mozart� unchanged. Also, be prepared to invest in a tool that can remove services created �inadvertently� like this on a Windows machine. Personally, I use Service+ (downloadable at www.activeplus.com), but the Windows Resource Kit provides a command-line utility that does the same thing for free.



However, this raises an important point: if you are going to make further configuration changes to the listener.ora, you need to stop the Listener process or service which has been automatically created for you. On Windows, this is most easily accomplished by finding the Control Panel Services applet (often found in Administrative Tools), highlighting the relevant service, and then using the menu options to stop it. On Unix, you need to find a command line prompt and type: lsnrctl stop listener_name. If you earlier opted to use the default listener name, LISTENER, then you can leave off the �listener name� part of that syntax.

Further Configuration You will probably want to check what the Wizard has created for you, and maybe make some alterations to it. In fact, the Wizard creates a text file called listener.ora in the ORACLE_HOME/network/admin directory (it�s the same directory for Windows, for versions 8i and 9i, except that the slashes go the other way around!). Bear in mind that any alterations you make to this file have not the slightest effect on a Listener that is already running. You�ll need to stop and start the Listener before it becomes aware of configuration changes in the listener.ora file. You should open that file, and see what it looks like. In my case, I get this: LISTENER = (DESCRIPTION_LIST = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = britten)(PORT = 1521)) ) (ADDRESS_LIST = (ADDRESS = (PROTOCOL = IPC)(KEY = EXTPROC0)) ) ) ) SID_LIST_LISTENER = (SID_LIST = (SID_DESC = (SID_NAME = PLSExtProc) (ORACLE_HOME = F:\oracle\ora90) (PROGRAM = extproc) ) )

Now, although I only selected for TCP protocol, the Wizard has arranged things so that I automatically get an IPC protocol to handle calls to external procedures (which is what the bit under the SID_LIST_LISTENER heading is all about). Whether you get the same result, or something else, depends very much on the specific configuration of Oracle that you�ve installed.



You may find, for example, that if a database has already been created on the machine that you ran the networking wizard on, it will have automatically discovered the existence of that database, and added a reference to that in the SID_LIST_LISTENER bit of the file, too. Feel free to edit this text file if it�s not what you want: but bear in mind that the indentation and formatting created by the wizard is not irrelevant, or there just to make things look good. Go overboard in your re-formatting and you might have trouble actually starting the Listener. In my case, I don�t want external procedures to be called. So whilst I don�t strictly need to remove references to it, there�s no harm in doing so either. With a bit of judicious editing, I�m left with a listener.ora that looks like this: LISTENER = (DESCRIPTION_LIST = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = britten)(PORT = 1521)) ) ) )

You will notice that nowhere in this newly-revised file does it state precisely on behalf of which databases the Listener should be listening. That�s significant, and it�s an entirely 8i and above feature. Databases of those versions are able to register themselves with the Listener, so the Listener doesn�t need to be explicitly told about them ahead of time in the listener.ora. But databases earlier than 8i cannot register themselves automatically, and the listener.ora needs to reference those databases explicitly. Let�s assume I wanted my new Listener to listen out for connection requests to an Oracle 8.0.6 database called HR. How would I add that requirement to the listener.ora? Well, again, you could just edit the file, but it�s easier if you use the Net8 Assistant (renamed the Net Manager in 9i). Don�t confuse that with the Net8 Configuration Assistant, by the way. The latter is a wizard-based way of creating the relevant networking configuration files. The former is a tool to manage things in a way that assumes you know what it is that you are doing. Let�s fire up the Net8 Assistant, then, to add in this reference to an Oracle 8 database. In Windows, click [Start][Programs][Oracle � <Oracle Home>][Network Administration][Net8 Assistant]. (In 9i, it�s [Start][Programs][Oracle � <Oracle Home>][Configuration and Migration Tools][Net Manager]). Here�s the first screen:



Open the �Local� branch of the tree structure in the left-hand pane, and then the �Listeners� branch within that, and you�ll see this:

The Listener you configured using the Wizard will be displayed in the tree structure. Click on that entry, and the right-hand pane will display this:



This is the �Listening Locations� page. It just describes what machine the Listener is going to run on, what port it will use, and what protocol is going to be used to contact it. If you look carefully, you�ll see that it corresponds precisely with the edited listener.ora shown above. But remember what we wanted to do: add in a reference to an 8.0 database called �HR�, so that this Listener, when finally its gets to run, will handle the connection requests for that database. Here�s what we do. Go to the �Listening Locations� label, and click the little down-arrow symbol on its right. From the menu that is then displayed, select the �Database Services� option. The left-hand pane will then change to display� pretty well nothing. That�s the point, of course. At the moment, we haven�t configured any databases to be listened for, so there are no �database services� to display. But that�s all about to change. Click the �Add Database� button at the bottom of the pane. The screen will change to show the following:



You need to supply just three pieces of information here: the global database name, that database�s Oracle Home, and the SID by which it is identified. I�ve filled in this screen shot using the example of a database called �HR�. However, you will probably find that the screen is initially filled in with a whole bunch of stuff referring to a database called �ORCL� (which is the default name of the starter database you tend to get when you install Oracle in the first place). Just overtype that information with your own details, as I�ve done here. If you need to specify another non-8i or non-9i database, click [Add Database] again, and keep going. If you make a mistake, select the appropriate tab containing the erroneous database details, and click [Remove Database]. When everything is completed to your satisfaction, you need to make sure that the changes you�ve made in this tool are actually written to the listener.ora configuration file. So click [File] [Save Network Configuration]. Then click [File][Exit]. For some utterly bizarre reason, you�ll be asked to save your configuration changes one more time, just in case. Click the [Save] option when prompted, and the tool will finally close. If you now open up the listener.ora text file, you�ll see something like this: LISTENER = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = britten)(PORT = 1521)) )



SID_LIST_LISTENER = (SID_LIST = (SID_DESC = (GLOBAL_DBNAME = HR.aldeburgh.local) (ORACLE_HOME = d:\oracle\ora806) (SID_NAME = HR) ) )

So, the configuration of a non-8i or non-9i version of the database results in the appending of a SID_LIST_LISTENER section to the file (which it had originally, of course, with the bits about allowing external procedure calls). This is an important point. Anything that is listed within a SID_LIST_LISTENER part of a listener.ora is said to be statically configured. The configuration information, as you can see, is fairly minimal (we need to know the ORACLE_HOME to make sure that the right version of the executables are called, if needed. The SID is needed so we know what to connect to in the first place). But it must be explicitly configured, like this, for any version of the database prior to 8i. Databases of versions 8i or higher can perform dynamic configuration �that is, they can inform the Listener, on startup, of their own existence, and they do not therefore need to be specified in the listener.ora at all. Even in 8i or higher databases, however, certain non-core-database services have to be statically configured. Calls to external procedures have to be, for example, which is why the configuration wizard automatically put those lines into the original version of my file. Heterogeneous Services (basically, gateways to non-Oracle databases) must also be statically configured, even with 8i or 9i databases.

Starting the Listener With the listener.ora configured one way or another, it�s time to actually start the Listener. If you ran the configuration wizard described earlier on the Server itself, then the service has probably already been started for you, as I mentioned on page 5. Quite often, however, you may run the configuration wizard on your local PC, and then transport the resulting listener.ora over to the server for later running. If that�s what you�ve done, you�ll have to start the Listener yourself, using good old manual methods. To do this, get yourself to a command line prompt on the server that hosts the database, and type lsnrctl start listener_name



If you accepted the default name earlier (�LISTENER�), then you don�t need to specify the listener name part of this command. If you chose to name your Listener something exotic, such as FredandGinger, then you must explicitly name it here, otherwise it won�t work. You�ll see something like the following appear on your screen: C:\Documents and Settings\Administrator>LSNRCTL start listenerabc LSNRCTL for 32-bit Windows: Version 9.0.1.1.1 - Production on 24-MAR-2002 15:54:37 Copyright (c) 1991, 2001, Oracle Corporation. All rights reserved. Starting tnslsnr: please wait... Failed to open service <OracleOraHome91TNSListenerlistenerabc>, error 1060. TNSLSNR for 32-bit Windows: Version 9.0.1.1.1 - Production System parameter file is d:\oracle\ora91\network\admin\listener.ora Log messages written to d:\oracle\ora91\network\log\listenerabc.log Listening on: (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=mozart.aldeburgh.local)(PORT=1521))) Connecting to (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=mozart)(PORT=1521))) STATUS of the LISTENER ------------------------ Alias listenerabc Version TNSLSNR for 32-bit Windows: Version 9.0.1.1.1 - Production Start Date 24-MAR-2002 15:54:41 Uptime 0 days 0 hr. 0 min. 2 sec Trace Level off Security OFF SNMP OFF Listener Parameter File d:\oracle\ora91\network\admin\listener.ora Listener Log File d:\oracle\ora91\network\log\listenerabc.log Listening Endpoints Summary... (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=mozart.aldeburgh.local)(PORT=1521))) The listener supports no services The command completed successfully

In this example, I had to specify a Listener name on the command line, because it was called �listenerabc�, and not the plain old default �listener�. The operating system reacted to the request to start my Listener with a quite nasty-looking error: Failed to open service <OracleOraHome91TNSListenerlistenerabc>, error 1060. TNSLSNR for 32-bit Windows: Version 9.0.1.1.1 - Production System parameter file is d:\oracle\ora91\network\admin\listener.ora Log messages written to d:\oracle\ora91\network\log\listenerabc.log

That�s actually perfectly normal (for Windows, the first time). It just means that the O/S has discovered that the service for the Listener doesn�t exist �which prompts it to create the service for you. On Unix, there should be no such messages. To be absolutely sure the thing is working correctly, try to stop the Listener and then immediately re-start it (I�ve highlighted the relevant commands):



C:\Documents and Settings\Administrator>lsnrctl stop listenerabc LSNRCTL for 32-bit Windows: Version 9.0.1.1.1 - Production on 24-MAR-2002 16:02:51 Copyright (c) 1991, 2001, Oracle Corporation. All rights reserved. Connecting to (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=mozart)(PORT=1521))) The command completed successfully

C:\Documents and Settings\Administrator>LSNRCTL start listenerabc LSNRCTL for 32-bit Windows: Version 9.0.1.1.1 - Production on 24-MAR-2002 16:02:56 Copyright (c) 1991, 2001, Oracle Corporation. All rights reserved. Starting tnslsnr: please wait... TNSLSNR for 32-bit Windows: Version 9.0.1.1.1 - Production System parameter file is d:\oracle\ora91\network\admin\listener.ora Log messages written to d:\oracle\ora91\network\log\listenerabc.log Listening on: (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=mozart.aldeburgh.local)(PORT=1521))) Connecting to (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=mozart)(PORT=1521))) STATUS of the LISTENER ------------------------ Alias listenerabc Version TNSLSNR for 32-bit Windows: Version 9.0.1.1.1 - Production Start Date 24-MAR-2002 16:02:59 Uptime 0 days 0 hr. 0 min. 2 sec Trace Level off Security OFF SNMP OFF Listener Parameter File d:\oracle\ora91\network\admin\listener.ora Listener Log File d:\oracle\ora91\network\log\listenerabc.log Listening Endpoints Summary... (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=mozart.aldeburgh.local)(PORT=1521))) The listener supports no services The command completed successfully

This time, you�ll notice no unpleasant messages at all. And so now you know the Listener can stop and start at will, you�ve successfully created and configured a Listener.

Other Issues If you use the Configuration wizard on one machine intending to transfer the resulting listener.ora to another one later on, you must edit the listener.ora by hand before attempting to start the Listener. For example, my earlier example of using the wizard was done on my client PC, called �Britten�, That�s why the listener.ora contained these lines: (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = britten)(PORT = 1521)) )



Unfortunately, my server hosting Oracle is actually called �Mozart�. Here�s what you can expect if you ship the listener.ora over to the real server without further modification, and try and start the Listener: C:\Documents and Settings\Administrator>LSNRCTL start listenerabc LSNRCTL for 32-bit Windows: Version 9.0.1.1.1 - Production on 24-MAR-2002 16:51:55 Copyright (c) 1991, 2001, Oracle Corporation. All rights reserved. Starting tnslsnr: please wait... Failed to open service <OracleOraHome91TNSListenerlistenerabc>, error 1060. TNSLSNR for 32-bit Windows: Version 9.0.1.1.1 - Production System parameter file is d:\oracle\ora91\network\admin\listener.ora Log messages written to d:\oracle\ora91\network\log\listenerabc.log Error listening on: (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=britten)(PORT=1521))) TNS-12545: Connect failed because target host or object does not exist TNS-12560: TNS:protocol adapter error TNS-00515: Connect failed because target host or object does not exist 32-bit Windows Error: 49: Unknown error Listener failed to start. See the error message(s) above...

I�ve highlighted the crucial error message, which is easy to miss because of the overwhelming nature of the complete error stack. Incidentally, on a Windows machine, even though the Listener couldn�t actually start because of the hostname issue, nevertheless, the Service is created for you. Here�s another error situation: if you create a Listener (called in this example �listenerabc�) whose name matches one that has already been created and started, expect something like this: C:\Documents and Settings\Administrator>LSNRCTL start listenerabc LSNRCTL for 32-bit Windows: Version 9.0.1.1.1 - Production on 24-MAR-2002 16:58:35 Copyright (c) 1991, 2001, Oracle Corporation. All rights reserved. Starting tnslsnr: please wait... Service OracleOraHome91TNSListenerlistenerabc already running. TNS-12536: TNS:operation would block TNS-12560: TNS:protocol adapter error TNS-00506: Operation would block 32-bit Windows Error: 997: Unknown error

In short, pay attention to the host�s name as recorded in the listener.ora, as well as the Listener Name itself. The former must be accurate, the latter must be unique.

Createlistener

Documents

new listener

existing listener

single listener

nondefault listener

unoriginal listener

listener networking

listener networking

selected protocols