What is IP=FIRST in the LISTENER.ORA file ?

 In this Document

Purpose

Scope

Details

References

---

APPLIES TO:

Oracle Database - Enterprise Edition - Version 11.1.0.7 to 18.3.0.0.0 [Release 11.1 to 18]
Oracle Net Services - Version 11.1.0.7 to 18.1.0.0.0 [Release 11.1 to 18.1]
Information in this document applies to any platform.

PURPOSE

Starting with Oracle10g 10.1.0.3 you will see the property IP=FIRST in the LISTENER.ORA file. What is IP=FIRST used for ?

LISTENER_VENUS =
  (DESCRIPTION_LIST =
    (DESCRIPTION =
      (ADDRESS_LIST =
        (ADDRESS = (PROTOCOL = TCP)(HOST = <hostname>-vip)(PORT = 1521)(IP = FIRST))
        (ADDRESS = (PROTOCOL = TCP)(HOST = <hostname2>)(PORT = 1521)(IP = FIRST))
      )
    )
  )

SCOPE

This note is intended to clarify usage for the IP=FIRST statement, usually in RAC setups.

DETAILS

The (IP=FIRST) statement will make the listener create a listening endpoint on the IP address to which the given HOST resolves. By default, without (IP=FIRST), the listener will listen on all network interfaces (e.g. INADDR_ANY) — see Note 421305.1 for background information on listener binding behavior.

This new attribute is covered in the Oracle Net Services documentation since Oracle 11g Release 1.

REFERENCES

APPLIES TO:

Oracle Net Services - Version 8.1.7.2 to 11.2.0.4 [Release 8.1.7 to 11.2]
Information in this document applies to any platform.

PURPOSE

This note attempts to explain how the listener binds to network addresses when it is configured for the TCP protocol.

SCOPE

The knowledge contained in this note will help you discern and eventually predict the listener behavior based on the listener configuration and system settings.   This documentation is limited in scope to 10gR2 and older listeners.  It doesn't apply to 11gR1 and newer listener behavior.

DETAILS

Introduction

Starting with Oracle 8i, the listener behavior in how it binds to IP addresses when configured with TCP protocol endpoints has changed (see Note 69026.1 for the rationale). The general rule may appear to you as being "listen on all interfaces if a hostname is specified". While this may prove correct most of the time, in particular situations the listener may behave differently.

You may force the listener into binding only to the specific IP address (even when using hostnames) by using the (IP=FIRST) statement in the address endpoint configuration in LISTENER.ORA (see Note 300729.1).

Since the listener binding point is critical for the database instances to register themselves with the listener (see Note 359277.1), it is important to understand what is the algorithm used by the listener to decide in what way to listen on its TCP endpoints.

General algorithm

You may use the following schema in order to interpret the listener behavior when it comes to binding to a TCP protocol address:

(1) If you provide an IP address, the listener will listen on that IP address

(2) If you provide a hostname:

  (a) Oracle does a gethostbyname() on that hostname (getaddrinfo() in 11g and higer); potentially more than one IP address is returned.

The gethostbyname() / getaddrinfo() library function may query the DNS server(s), the /etc/hosts file, the NIS service and perhaps other methods, based on the system configuration. How this works exactly depends on the operating system type, but usually the /etc/host.conf, /etc/nsswitch.conf and /etc/resolv.conf files are governing the functionality on the UNIX platforms.

You can find the value that is expected to be given by using the ping tool (e.g. "ping <hostname>" or "ping -s <hostname>" and see what IP address will the hostname resolve to). Do not use host, nslookup or dig to find this information, since these tools will query only the DNS service and may give wrong answers in certain situations.

Be careful that even the ping utility may not disclose you all the information, e.g. it will not show all the addresses associated with a hostname, if there are more than one. Best choice is to use the check-lsnrbind program, attached to this note (see below section "Checking tool").

   (b) Oracle does a gethostname() / getaddrinfo() which will return the system's configured hostname.

The gethostname() / getaddrinfo() library function (notice the missing by particle) will return the standard hostname set for the system (or current processor, per manual pages); this is usually done at system startup.

You can find the value that is expected to be given by using the hostname tool, without any parameters (e.g. simply run "hostname").

   (c) Oracle does a gethostbyname() / getaddrinfo() on the system's hostname found in the previous step (2b).

   (d) Oracle compares the first IP returned in (2a) to all of the IPs returned in (2c). If no match is found, then the listener will bind to the resolved IP address. The IP address is registered in the listening endpoints list.

— OR —

   (e) If a match is found in (2d), the listener binds on all (working) network interfaces. The fully qualified system hostname is  registered in the listening endpoints list.

You may recognize that the listener has bound to all interfaces from the "netstat -an" output: if the listener is bound to all interfaces then the IP address 0.0.0.0 will be shown — it programmers' slang this is known as the INADDR_ANY address.

Interpreting listener status

You can easily judge what is the way the listener has bound to the TCP addresses from its status output: check whether the Listening Endpoints Summary lists an IP address or a hostname. If you see an IP address then the listener had bound only to that IP, but if instead you see a hostname then the listener has bound to all interfaces (INADDR_ANY).

Let's take the following example:

$ lsnrctl status

LSNRCTL for Linux: Version 10.2.0.1.0 - Production on 07-MAY-2007 15:29:48

Copyright (c) 1991, 2005, Oracle.  All rights reserved.

Connecting to (DESCRIPTION=(ADDRESS=(PROTOCOL=IPC)(KEY=EXTPROC1)))
STATUS of the LISTENER
------------------------
Alias                     LISTENER
Version                   TNSLSNR for Linux: Version 10.2.0.1.0 - Production
Start Date                13-APR-2007 14:11:16
Uptime                    24 days 1 hr. 18 min. 32 sec
Trace Level               off
Security                  ON: Local OS Authentication
SNMP                      OFF
Listener Parameter File   /opt/oracle/product/10.2.0/db_1/network/admin/listener.ora
Listener Log File         /opt/oracle/product/10.2.0/db_1/network/log/listener.log
Listening Endpoints Summary...
  (DESCRIPTION=(ADDRESS=(PROTOCOL=ipc)(KEY=EXTPROC1)))
  (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=10.10.10.10)(PORT=1527)))
  (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=myhost.ro.oracle.com)(PORT=1521)))

In this case, the listener has bound to specific IP address 10.10.10.10 on port 1527 as well as to all interfaces (0.0.0.0 / INADDR_ANY) on port 1521.

Side effects

Some of the operating systems (e.g. UNIX platforms) may allow multiple bindings on the same TCP port, eventually coming from different listeners, as long as the (numeric) IP addresses do not conflict. For example, you may have one listener bound on the generic INADDR_ANY address and other(s) on specific IP address(es). In this case, connections may go to different listeners based on the destination IP address, including database instance registration attempts — be sure you are able to discern the way the connections and database registrations are working in this setup.

On the contrary, other operating systems (e.g. the Microsoft Windows platform), disallow having multiple bindings on the same TCP port no matter the IP addresses used, so a second attempt to bind on the same port will fail, triggering errors when starting listener(s).

Checking tool:  Please be aware that Oracle support does not support this tool nor can we assist with issues that arise in trying to compile it.

In order to check for the listener binding behavior of the Oracle listener you can use the attached C program check-lsnrbind.c. This tool needs to be run on the target server, in order to correctly identify the system hostname and to resolve the probed hostnames through the same services as the real listener.

Before using it you will need to compile it, with a command similar to the following:

cc check-lsnrbind.c -o check-lsnrbind

 

To compile the program on the Sun Solaris platform, you will need to add "-lnsl" to the command line, like the following:

cc check-lsnrbind.c -o check-lsnrbind -lnsl

The syntax is simple: just give the hostnames you want to check on its command line; if you want to see the associated IP addresses, then insert the "-v" parameter first in the command line. Here are some examples:

./check-lsnrbind test
./check-lsnrbind test1 test2.foo.com
./check-lsnrbind -v mysite.domain.com

The program has been tested to compile and run on the following platforms:

• Linux
• Sun Solaris 10 (needs "-lnsl" when compiling)
• HP-UX 11.11
• AIX 5L
• AIX 4.3
• TruUNIX Alpha 5.1B
• MS Windows with CygWin

REFERENCES

NOTE:359277.1 - Changing Default Listener Port Number
NOTE:300729.1 - What is IP=FIRST in the LISTENER.ORA file ?
NOTE:69026.1 - Oracle8i and socket LISTEN operations

NOTE:421305.1 - How The Listener Binds On TCP Protocol Addresses

What is IP=FIRST in the LISTENER.ORA file ? (Doc ID 300729.1)