usr/src/man/man4/hosts.4

   1 '\" te
   2 .\"  Copyright 1989 AT&T Copyright (c) 1988, 1995 Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH HOSTS 4 "Feb 25, 2017"
   7 .SH NAME
   8 hosts \- host name database
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fB/etc/inet/hosts\fR
  13 .fi
  14
  15 .LP
  16 .nf
  17 \fB/etc/hosts\fR
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fB/etc/inet/ipnodes\fR
  23 .fi
  24
  25 .SH DESCRIPTION
  26 .LP
  27 The \fBhosts\fR file is a local database that associates the names of hosts
  28 with their Internet Protocol (IP) addresses. An IP address can be in either
  29 IPv4 or IPv6 format. The \fBhosts\fR file can be used in conjunction with, or
  30 instead of, other hosts databases, including the Domain Name System (DNS), the
  31 NIS \fBhosts\fR map, or information from an LDAP
  32 server. Programs use library interfaces to access information in the
  33 \fBhosts\fR file.
  34 .sp
  35 .LP
  36 Note that \fB/etc/hosts\fR and \fB/etc/inet/ipnodes\fR are symbolic links to
  37 \fB/etc/inet/hosts\fR.
  38 .sp
  39 .LP
  40 The \fBhosts\fR file has one entry for each IP address of each host. If a host
  41 has more than one IP address, it will have one entry for each, on consecutive
  42 lines. The format of each line is:
  43 .sp
  44 .LP
  45 \fIIP-address\fR \fIofficial-host-name\fR \fInicknames\|.\|.\|\fR.
  46 .sp
  47 .LP
  48 Items are separated by any number of \fBSPACE\fR and/or \fBTAB\fR characters.
  49 The first item on a line is the host's IP address. The second entry is the
  50 host's official name. Subsequent entries on the same line are alternative names
  51 for the same machine, or "nicknames." Nicknames are optional.
  52 .sp
  53 .LP
  54 For a host with more than one IP address, consecutive entries for these
  55 addresses may contain the same or differing nicknames. Different nicknames are
  56 useful for assigning distinct names to different addresses.
  57 .sp
  58 .LP
  59 A call to \fBgethostbyname\fR(3NSL) returns a \fBhostent\fR structure
  60 containing the union of all IPv4 addresses and nicknames from each line
  61 containing a matching official name or nickname. A call to
  62 \fBgetipnodebyname\fR(3SOCKET) is similar, but is capable of returning
  63 \fBhostent\fR structures containing IPv4 and IPv6 addresses. Applications might
  64 prefer to use the address-family independent \fBgetaddrinfo\fR(3SOCKET) API for
  65 name-to-address lookups.
  66 .sp
  67 .LP
  68 A `\fB#\fR' indicates the beginning of a comment; characters up to the end of
  69 the line are not interpreted by routines that search the file.
  70 .sp
  71 .LP
  72 Network addresses are written in one of two ways:
  73 .RS +4
  74 .TP
  75 .ie t \(bu
  76 .el o
  77 The conventional "decimal dot" notation and interpreted using the
  78 \fBinet_addr\fR routine from the Internet address manipulation library,
  79 \fBinet\fR(3SOCKET).
  80 .RE
  81 .RS +4
  82 .TP
  83 .ie t \(bu
  84 .el o
  85 The IP Version 6 protocol [IPV6], defined in RFC 1884 and interpreted using the
  86 \fBinet_pton()\fR routine from the Internet address manipulation library. See
  87 \fBinet\fR(3SOCKET).
  88 .RE
  89 .sp
  90 .LP
  91 This interface supports node names as defined in Internet RFC 952, which
  92 states:
  93 .sp
  94 .LP
  95 A "name" (Net, Host, Gateway, or Domain name) is a text string up to 24
  96 characters drawn from the alphabet (A-Z), digits (0-9), minus sign (\(mi), and
  97 period (.). Note that periods are only allowed when they serve to delimit
  98 components of "domain style names". (See RFC 921, "Domain Name System
  99 Implementation Schedule," for background). No blank or space characters are
 100 permitted as part of a name. No distinction is made between uppercase and
 101 lowercase. The first character must be an alpha character [or a digit. (RFC
 102 1123 relaxed RFC 952's limitation of the first character to only alpha
 103 characters.)] The last character must not be a minus sign or period.
 104 .sp
 105 .LP
 106 Host names must not consist of numbers only. A host name must contain at least
 107 one alphabetical or special character.
 108 .sp
 109 .LP
 110 Although the interface accepts host names longer than 24 characters for the
 111 host portion (exclusive of the domain component), choosing names for hosts that
 112 adhere to the 24 character restriction will insure maximum interoperability on
 113 the Internet.
 114 .sp
 115 .LP
 116 A host which serves as a GATEWAY should have "\(miGATEWAY" or "\(miGW" as part
 117 of its name. Hosts which do not serve as Internet gateways should not use
 118 "\(miGATEWAY" and "\(miGW" as part of their names. A host which is a TAC should
 119 have "\(miTAC" as the last part of its host name, if it is a DoD host. Single
 120 character names or nicknames are not allowed.
 121 .SH EXAMPLES
 122 .LP
 123 \fBExample 1 \fRExample \fBhosts\fR File Entry
 124 .sp
 125 .LP
 126 The following is a typical line from the \fBhosts\fR file:
 127
 128 .sp
 129 .in +2
 130 .nf
 131 192.9.1.20        gaia                        # John Smith
 132 .fi
 133 .in -2
 134 .sp
 135
 136 .LP
 137 \fBExample 2 \fRExample IPv6 Address Entry
 138 .sp
 139 .LP
 140 The following is an example of an IPv6 \fBhosts\fR entry:
 141
 142 .sp
 143 .in +2
 144 .nf
 145 2001:0db8:3c4d:55:a00:20ff:fe8e:f3ad  myhost  # John Smith
 146 .fi
 147 .in -2
 148 .sp
 149
 150 .SH SEE ALSO
 151 .LP
 152 \fBgethostbyname\fR(3NSL), \fBgetipnodebyname\fR(3SOCKET), \fBinet\fR(3SOCKET),
 153 \fBnsswitch.conf\fR(4), \fBresolv.conf\fR(4)
 154 .sp
 155 .LP
 156 Braden, B., editor, RFC 1123, \fIRequirements for Internet Hosts - Application
 157 and Support\fR, Network Working Group, October, 1989.
 158 .sp
 159 .LP
 160 Harrenstien, K., Stahl, M., and Feinler, E., RFC 952, \fIDOD Internet Host
 161 Table Specification\fR, Network Working Group, October 1985.
 162 .sp
 163 .LP
 164 Hinden, R., and Deering, S., editors, RFC 1884, \fIIP Version 6 Addressing
 165 Architecture\fR, Network Working Group, December, 1995.
 166 .sp
 167 .LP
 168 Postel, Jon, RFC 921, \fIDomain Name System Implementation Schedule
 169 (Revised)\fR, Network Working Group, October 1984.
 170 .SH NOTES
 171 .LP
 172 \fB/etc/inet/hosts\fR is the official SVR4 name of the \fBhosts\fR file. The
 173 symbolic link \fB/etc/hosts\fR exists for \fBBSD\fR compatibility.
 174 .sp
 175 .LP
 176 The symbolic link \fB/etc/net/ipnodes\fR exists for backwards compatibility
 177 with previous Solaris releases.