Single hosts file Release binding: minor Problem ============== The /etc/inet/ipnodes database was created to hold both IPv4 and IPv6 host addresses. The ipnodes database is searched first by applications using the getaddrinfo()/getnameinfo() API. The /etc/inet/hosts database was left for legacy applications supporting only IPv4 addresses and calling the gethostby* API. Changes were approved in case PSARC/1998/039 and integrated in Solaris 8. The drawback of the split is IPv4 entries in both databases have to be always in sync. Problems arise in applications when an entry differs in the two databases and host lookup results vary depending on the API used. System administrators must make it a point when changing one file to update the other. The problem is documented in CR 6219146. The opinion for PSARC/1998/039 explains that a database separate from /etc/hosts be used to store both IPv4 and IPv6 addresses (this became /etc/inet/ipnodes), and that /etc/hosts remain for legacy applications and eventually be declared obsolete as IPv6 gains traction and IPv4 is phased out. The opinion also requested a follow-on case be filed to confirm a standard name agreed upon by the IETF for this new combined database. Since then, the rest of the industry has converged on using /etc/hosts as a combined database, not /etc/inet/ipnodes. This case is that follow-on case, confirming that /etc/hosts is the industry standard for storing all IP address mappings. Solution ======== This case proposes to remove the current limitation in maintaining two databases for IP addresses and to avoid the problems posed when entries in the two databases are conflicting. The /etc/inet/hosts database will be the single configuration file that associates host names with their IP addresses, both IPv4 and IPv6 addresses. The /etc/inet/ipnodes file will be left as a symlink to /etc/inet/hosts for backwards compatibility. Adding IPv6 address entries in /etc/inet/hosts does not break host lookups using the gethostby* API. In the gethostby* implementation addresses found in the database not in IPv4 address format are disregarded during the search. Host lookups using the getaddrinfo()/getnameinfo() API will also be unaffected after the ipnodes conversion to a symlink. We chose to leave the /etc/inet/ipnodes as a symlink and not remove the file entirely in keeping with the file's classification as a 'Stable' interface. Removing the file entirely runs the risk of breaking existing applications depending on the file and may cause users to re-create the ipnodes file to satisfy such applications. Keeping the symlink could also cause issues in applications expecting two distinct files holding IPv4 addresses. F.e. an application adding IPv4 addresses previously to two distinct hosts and ipnodes files may now add entries twice in the same hosts file. We feel the advantages of keeping a stable interface by keeping the ipnodes file as a symlink outweigh risks with applications continuing to treat the two files as distinct. Experience from other unix platforms which use a single hosts file suggests that software having problems parsing /etc/inet/hosts file with IPv6 address entries is extremely rare. Even if there are the cost of modifying such software is far less than the incurred cost in maintaining two separate databases. NetBSD based UNIXes and Linux have a single hosts file from the beginning. Bringing Solaris closer to NetBSD and Linux in this regard is also a good thing. Merge Script ============ The task of merging entries from the ipnodes database to the hosts database is performed by a class action script in the SUNWcsr package. The merge script creates copies of the existing hosts and ipnodes config files before making any changes. The merge script also adds a comment in the resulting hosts file about the occurrence of a merge. The merge script copies over entries from the ipnodes database to the hosts database and in the resulting hosts file removes duplicate entries and coalesces multiple address entries of a hostname. Entries that exist with both IP address and host name aliases identical (often when the same entry is added in both hosts and ipnodes) are considered duplicates and only one such entry is kept. For hostname entry with multiple addresses, all entries are moved to consecutive lines in the resulting hosts file. When a duplicate entry is removed by the merge script any comment lines preceding the entry are also removed. However if the removed entry is the first in the file any preceding comment lines possibly specifying the file header are not removed. Solaris Upgrade =============== Solaris OS upgrade detects any configuration file changes in new package versions and renames the modified files as reference copies prior to the upgrade. The ipnodes file change to a symlink when found in the new package, the existing ipnodes file is renamed before upgrading the system. But this safeguard against losing configuration changes due to upgrade does not permit the class action script to merge ipnodes contents into hosts correctly. An entry therefore will be added in the SUNWcsr pkghistory to ignore the ipnodes file change and not rename the file. NIS ipnodes =========== This case does not propose any changes to nsswitch nor removing the ipnodes database from the switch file. NIS servers upgrading to a build containing the above changes will have a merged hosts file. But the maps for hosts and ipnodes will continue to be distinct as /var/yp/Makefile filters out all non-IPv4 addresses when creating the hosts map. The ipnodes map will have both IPv4 and IPv6 addresses. The stdhosts filter used by /var/yp/Makefile will be updated to support the merged hosts file. Running the filter on the hosts file to convert IPv4 addresses should not generate warnings due to IPv6 address entries. Interface Table =================== The following existing interfaces are affected: /etc/inet/hosts Stable /etc/inet/ipnodes Stable * Please note that PSARC/1998/039 case includes references to /etc/inet/hosts6 file. During review one of the issues raised was on the choice of filename. Though there is no explicit mention of ipnodes being chosen as the new filename the proposed /etc/inet/hosts6 filename was changed to /etc/inet/ipnodes. References ========== 1. PSARC/1998/039 "Naming Services Support of IPv6" 2. CR 6219146 "/etc/inet/hosts and /etc/inet/ipnodes need to be the same file" Manual page changes =================== The new hosts man page is listed below: File Formats hosts(4) NAME hosts - host name database SYNOPSIS /etc/inet/hosts /etc/hosts + /etc/inet/ipnodes + DESCRIPTION The hosts file is a local database that associates the names - of hosts with their Internet Protocol (IP) addresses. The + of hosts with their Internet Protocol (IP) addresses. IP + addresses can be either an IPv4 or an IPv6 address. The hosts file can be used in conjunction with, or instead of, other hosts databases, including the Domain Name System (DNS), the NIS hosts map, the NIS+ hosts table, or informa- tion from an LDAP server. Programs use library interfaces to access information in the hosts file. The hosts file has one entry for each IP address of each host. If a host has more than one IP address, it will have one entry for each, on consecutive lines. The format of each line is: IP-address official-host-name nicknames... Items are separated by any number of SPACE and/or TAB char- acters. The first item on a line is the host's IP address. The second entry is the host's official name. Subsequent entries on the same line are alternative names for the same machine, or "nicknames." Nicknames are optional. For a host with more than one IP address, consecutive entries for these addresses may contain the same or differ- ing nicknames. Different nicknames are useful for assigning distinct names to different addresses. A call to gethostbyname(3NSL) returns a hostent structure - containing the union of all addresses and nicknames from - each line containing a matching official name or nickname. + containing the union of all IPv4 addresses and nicknames + from each line containing a matching official name or + nickname. A call to getipnodebyname(3SOCKET) is similar, + but is capable of returning hostent structures + containing IPv4 and IPv6 addresses. Applications may + also preferably use the address-family independent + getaddrinfo(3SOCKET) API for name to address + lookups. A `#' indicates the beginning of a comment; characters up to the end of the line are not interpreted by routines that search the file. - Network addresses are written in the conventional "decimal - dot" notation and interpreted using the inet_addr routine - from the Internet address manipulation library, - inet(3SOCKET). + Network addresses are written in one of two ways: - This interface supports host names as defined in Internet - RFC 952 which states: + o The conventional "decimal dot" notation and interpreted + using the inet_addr routine from the Internet address + manipulation library, inet(3SOCKET). SunOS 5.10 Last change: 30 Sep 2005 1 File Formats hosts(4) + o The IP Version 6 protocol [IPV6], defined in RFC 1884 + and interpreted using the inet_pton() routine from the + Internet address manipulation library. See + inet(3SOCKET). + These interfaces supports node names as defined in Internet + RFC 952 which states: + A "name" (Net, Host, Gateway, or Domain name) is a text string up to 24 characters drawn from the alphabet (A- Z), digits (0-9), minus sign (-), and period (.). Note that periods are only allowed when they serve to del- imit components of "domain style names". (See RFC 921, "Domain Name System Implementation Schedule," for back- ground). No blank or space characters are permitted as part of a name. No distinction is made between upper- case and lowercase. The first character must be an alpha character [or a digit. (RFC 1123 relaxed RFC 952's limitation of the first character to only alpha characters.)] The last character must not be a minus sign or period. Host names must not consist of numbers only. A host name must contain at least one alphabetical or special character. Although the interface accepts host names longer than 24 characters for the host portion (exclusive of the domain component), choosing names for hosts that adhere to the 24 character restriction will insure maximum interoperability on the Internet. A host which serves as a GATEWAY should have "-GATEWAY" or "-GW" as part of its name. Hosts which do not serve as Internet gateways should not use "-GATEWAY" and "-GW" as part of their names. A host which is a TAC should have "-TAC" as the last part of its host name, if it is a DoD host. Single character names or nicknames are not allowed. EXAMPLES Example 1: Example of a typical line from the hosts file. Here is a typical line from the hosts file: 192.9.1.20 gaia # John Smith + Example 2: Example of an IPv6 address entry. + + 2001:0db8:3c4d:55:a00:20ff:fe8e:f3ad myhost # John Smith + + SEE ALSO gethostbyname(3NSL), inet(3SOCKET), nsswitch.conf(4), resolv.conf(4) + Braden, B., editor, RFC 1123, Requirements for Internet + Hosts - Application and Support, Network Working Group, + October, 1989. + + Harrenstien, K., Stahl, M., and Feinler, E., RFC 952, DOD + INTERNET HOST TABLE SPECIFICATION, Network Working Group, + October 1985. + + Hinden, R., and Deering, S., editors, RFC 1884, IP Version 6 + Addressing Architecture, Network Working Group, December, + 1995. + + Postel, Jon, RFC 921, Domain Name System Implementation + Schedule - Revised, Network Working Group, October 1984. + + NOTES /etc/inet/hosts is the official SVR4 name of the hosts file. The symbolic link /etc/hosts exists for BSD compatibility. + The symbolic link /etc/hosts/ipnodes exists for backwards + compatibility with previous Solaris releases. The nssitch.conf (4) man page is also updated with a new note about the ipnodes file change to a symlink: *** nss Wed May 3 13:24:11 2006 --- nss.new Wed May 3 13:34:24 2006 *************** *** 672,726 **** --- 672,728 ---- getdefaultproj(3PROJECT), inproj(3PROJECT), setproject(3PROJECT), getauthnam(3SECDB), getexecprof(3SECDB), getprofnam(3SECDB), getuserattr(3SECDB), getusernam(3SECDB), ethers(3SOCKET), getaddrinfo(3SOCKET), getnetbyname(3SOCKET), getprotobyname(3SOCKET), getservbyname(3SOCKET), auth_attr(4), netconfig(4), project(4), resolv.conf(4), user_attr(4), ypfiles(4) NOTES Within each process that uses nsswitch.conf, the entire file is read only once; if the file is later changed, the process will continue using the old configuration. The use of both nis and nisplus as sources for the same database is strongly discouraged since both the name ser- vices are expected to store similar information and the lookups on the database may yield different results depend- ing on which name service is operational at the time of the request. The same applies for using ldap along with nis or nisplus. Misspelled names of sources and databases will be treated as legitimate names of (most likely nonexistent) sources and databases. The following functions do not use the switch: fgetgrent(3C), fgetprojent(3PROJECT), fgetpwent(3C), fgetspent(3C), getpw(3C), putpwent(3C), shadow(4). + The files source to both ipnodes and hosts databases is identical + as /etc/inet/ipnodes is a symbolic link to /etc/inet/hosts.