diff --git a/lib/libc/net/getaddrinfo.3 b/lib/libc/net/getaddrinfo.3 index bd7455127390..a91a26973ecb 100644 --- a/lib/libc/net/getaddrinfo.3 +++ b/lib/libc/net/getaddrinfo.3 @@ -1,519 +1,519 @@ .\" $KAME: getaddrinfo.3,v 1.36 2005/01/05 03:23:05 itojun Exp $ .\" $OpenBSD: getaddrinfo.3,v 1.35 2004/12/21 03:40:31 jaredy Exp $ .\" .\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") .\" Copyright (C) 2000, 2001 Internet Software Consortium. .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY .\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" .\" $FreeBSD$ .\" -.Dd February 10, 2019 +.Dd June 27, 2022 .Dt GETADDRINFO 3 .Os .Sh NAME .Nm getaddrinfo , .Nm freeaddrinfo .Nd socket address structure to host and service name .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netdb.h .Ft int .Fo getaddrinfo .Fa "const char *hostname" "const char *servname" .Fa "const struct addrinfo *hints" "struct addrinfo **res" .Fc .Ft void .Fn freeaddrinfo "struct addrinfo *ai" .Sh DESCRIPTION The .Fn getaddrinfo function is used to get a list of addresses and port numbers for host .Fa hostname and service .Fa servname . It is a replacement for and provides more flexibility than the .Xr gethostbyname 3 and .Xr getservbyname 3 functions. .Pp The .Fa hostname and .Fa servname arguments are either pointers to NUL-terminated strings or the null pointer. An acceptable value for .Fa hostname is either a valid host name or a numeric host address string consisting of a dotted decimal IPv4 address, an IPv6 address, or a UNIX-domain address. The .Fa servname is either a decimal port number or a service name listed in .Xr services 5 . At least one of .Fa hostname and .Fa servname must be non-null. .Pp .Fa hints is an optional pointer to a .Li struct addrinfo , as defined by .Aq Pa netdb.h : .Bd -literal struct addrinfo { int ai_flags; /* AI_PASSIVE, AI_CANONNAME, .. */ int ai_family; /* AF_xxx */ int ai_socktype; /* SOCK_xxx */ int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ socklen_t ai_addrlen; /* length of ai_addr */ char *ai_canonname; /* canonical name for hostname */ struct sockaddr *ai_addr; /* binary address */ struct addrinfo *ai_next; /* next structure in linked list */ }; .Ed .Pp This structure can be used to provide hints concerning the type of socket that the caller supports or wishes to use. The caller can supply the following structure elements in .Fa hints : .Bl -tag -width "ai_socktypeXX" .It Fa ai_family The address family that should be used. When .Fa ai_family is set to .Dv AF_UNSPEC , it means the caller will accept any address family supported by the operating system. .It Fa ai_socktype Denotes the type of socket that is wanted: .Dv SOCK_STREAM , .Dv SOCK_DGRAM , .Dv SOCK_SEQPACKET , or .Dv SOCK_RAW . When .Fa ai_socktype is zero the caller will accept any socket type. .It Fa ai_protocol Indicates which transport protocol is desired, .Dv IPPROTO_UDP , .Dv IPPROTO_TCP , .Dv IPPROTO_SCTP , or .Dv IPPROTO_UDPLITE . If .Fa ai_protocol is zero the caller will accept any protocol. .It Fa ai_flags The .Fa ai_flags field to which the .Fa hints parameter points shall be set to zero or be the bitwise-inclusive OR of one or more of the values .Dv AI_ADDRCONFIG , .Dv AI_ALL , .Dv AI_CANONNAME , .Dv AI_NUMERICHOST , .Dv AI_NUMERICSERV , .Dv AI_PASSIVE and .Dv AI_V4MAPPED . For a UNIX-domain address, .Fa ai_flags is ignored. .Bl -tag -width "AI_CANONNAMEXX" .It Dv AI_ADDRCONFIG If the .Dv AI_ADDRCONFIG bit is set, IPv4 addresses shall be returned only if an IPv4 address is configured on the local system, and IPv6 addresses shall be returned only if an IPv6 address is configured on the local system. .It Dv AI_ALL If the .Dv AI_ALL flag is used with the .Dv AI_V4MAPPED flag, then .Fn getaddrinfo shall return all matching IPv6 and IPv4 addresses. .Pp For example, when using the DNS, queries are made for both AAAA records and A records, and .Fn getaddrinfo returns the combined results of both queries. Any IPv4 addresses found are returned as IPv4-mapped IPv6 addresses. .Pp The .Dv AI_ALL flag without the .Dv AI_V4MAPPED flag is ignored. .It Dv AI_CANONNAME If the .Dv AI_CANONNAME bit is set, a successful call to .Fn getaddrinfo will return a NUL-terminated string containing the canonical name of the specified hostname in the .Fa ai_canonname element of the first .Li addrinfo structure returned. .It Dv AI_NUMERICHOST If the .Dv AI_NUMERICHOST bit is set, it indicates that .Fa hostname should be treated as a numeric string defining an IPv4 or IPv6 address and no name resolution should be attempted. .It Dv AI_NUMERICSERV If the .Dv AI_NUMERICSERV bit is set, then a non-null .Fa servname string supplied shall be a numeric port string. Otherwise, an .Dv EAI_NONAME error shall be returned. This bit shall prevent any type of name resolution service (for example, NIS+) from being invoked. .It Dv AI_PASSIVE If the .Dv AI_PASSIVE bit is set it indicates that the returned socket address structure is intended for use in a call to .Xr bind 2 . In this case, if the .Fa hostname argument is the null pointer, then the IP address portion of the socket address structure will be set to .Dv INADDR_ANY for an IPv4 address or .Dv IN6ADDR_ANY_INIT for an IPv6 address. .Pp If the .Dv AI_PASSIVE bit is not set, the returned socket address structure will be ready for use in a call to .Xr connect 2 for a connection-oriented protocol or .Xr connect 2 , .Xr sendto 2 , or .Xr sendmsg 2 if a connectionless protocol was chosen. The .Tn IP address portion of the socket address structure will be set to the loopback address if .Fa hostname is the null pointer and .Dv AI_PASSIVE is not set. .It Dv AI_V4MAPPED If the .Dv AI_V4MAPPED flag is specified along with an ai_family of .Dv AF_INET6 , then .Fn getaddrinfo shall return IPv4-mapped IPv6 addresses on finding no matching IPv6 addresses ( .Fa ai_addrlen shall be 16). .Pp For example, when using the DNS, if no AAAA records are found then a query is made for A records and any found are returned as IPv4-mapped IPv6 addresses. .Pp The .Dv AI_V4MAPPED flag shall be ignored unless .Fa ai_family equals .Dv AF_INET6 . .El .El .Pp All other elements of the .Li addrinfo structure passed via .Fa hints must be zero or the null pointer. .Pp If .Fa hints is the null pointer, .Fn getaddrinfo behaves as if the caller provided a .Li struct addrinfo with .Fa ai_family set to .Dv AF_UNSPEC and all other elements set to zero or .Dv NULL . .Pp After a successful call to .Fn getaddrinfo , .Fa *res is a pointer to a linked list of one or more .Li addrinfo structures. The list can be traversed by following the .Fa ai_next pointer in each .Li addrinfo structure until a null pointer is encountered. Each returned .Li addrinfo structure contains three members that are suitable for a call to .Xr socket 2 : .Fa ai_family , .Fa ai_socktype , and .Fa ai_protocol . For each .Li addrinfo structure in the list, the .Fa ai_addr member points to a filled-in socket address structure of length .Fa ai_addrlen . .Pp This implementation of .Fn getaddrinfo allows numeric IPv6 address notation with scope identifier, as documented in chapter 11 of RFC 4007. By appending the percent character and scope identifier to addresses, one can fill the .Li sin6_scope_id field for addresses. This would make management of scoped addresses easier and allows cut-and-paste input of scoped addresses. .Pp At this moment the code supports only link-local addresses with the format. The scope identifier is hardcoded to the name of the hardware interface associated with the link .Po such as .Li ne0 .Pc . An example is .Dq Li fe80::1%ne0 , which means .Do .Li fe80::1 on the link associated with the .Li ne0 interface .Dc . .Pp The current implementation assumes a one-to-one relationship between the interface and link, which is not necessarily true from the specification. .Pp All of the information returned by .Fn getaddrinfo is dynamically allocated: the .Li addrinfo structures themselves as well as the socket address structures and the canonical host name strings included in the .Li addrinfo structures. .Pp Memory allocated for the dynamically allocated structures created by a successful call to .Fn getaddrinfo is released by the .Fn freeaddrinfo function. The .Fa ai pointer should be a .Li addrinfo structure created by a call to .Fn getaddrinfo . .Sh IMPLEMENTATION NOTES The behavior of .Li freeadrinfo(NULL) is left unspecified by both .St -susv4 and .Dv "RFC 3493" . The current implementation ignores a .Dv NULL argument for compatibility with programs that rely on the implementation details of other operating systems. .Sh RETURN VALUES .Fn getaddrinfo returns zero on success or one of the error codes listed in .Xr gai_strerror 3 if an error occurs. .Sh EXAMPLES The following code tries to connect to .Dq Li www.kame.net service .Dq Li http via a stream socket. It loops through all the addresses available, regardless of address family. If the destination resolves to an IPv4 address, it will use an .Dv AF_INET socket. Similarly, if it resolves to IPv6, an .Dv AF_INET6 socket is used. Observe that there is no hardcoded reference to a particular address family. The code works even if .Fn getaddrinfo returns addresses that are not IPv4/v6. .Bd -literal -offset indent struct addrinfo hints, *res, *res0; int error; int s; const char *cause = NULL; memset(&hints, 0, sizeof(hints)); hints.ai_family = AF_UNSPEC; hints.ai_socktype = SOCK_STREAM; error = getaddrinfo("www.kame.net", "http", &hints, &res0); if (error) { errx(1, "%s", gai_strerror(error)); /* NOTREACHED */ } s = -1; for (res = res0; res; res = res->ai_next) { s = socket(res->ai_family, res->ai_socktype, res->ai_protocol); if (s < 0) { cause = "socket"; continue; } if (connect(s, res->ai_addr, res->ai_addrlen) < 0) { cause = "connect"; close(s); s = -1; continue; } break; /* okay we got one */ } if (s < 0) { err(1, "%s", cause); /* NOTREACHED */ } freeaddrinfo(res0); .Ed .Pp The following example tries to open a wildcard listening socket onto service .Dq Li http , for all the address families available. .Bd -literal -offset indent struct addrinfo hints, *res, *res0; int error; int s[MAXSOCK]; int nsock; const char *cause = NULL; memset(&hints, 0, sizeof(hints)); hints.ai_family = AF_UNSPEC; hints.ai_socktype = SOCK_STREAM; hints.ai_flags = AI_PASSIVE; error = getaddrinfo(NULL, "http", &hints, &res0); if (error) { errx(1, "%s", gai_strerror(error)); /* NOTREACHED */ } nsock = 0; for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) { s[nsock] = socket(res->ai_family, res->ai_socktype, res->ai_protocol); if (s[nsock] < 0) { cause = "socket"; continue; } if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) { cause = "bind"; close(s[nsock]); continue; } (void) listen(s[nsock], 5); nsock++; } if (nsock == 0) { err(1, "%s", cause); /* NOTREACHED */ } freeaddrinfo(res0); .Ed .Sh SEE ALSO .Xr bind 2 , .Xr connect 2 , .Xr send 2 , .Xr socket 2 , .Xr gai_strerror 3 , .Xr gethostbyname 3 , .Xr getnameinfo 3 , .Xr getservbyname 3 , .Xr resolver 3 , .Xr inet 4 , .Xr inet6 4 , .Xr unix 4 , .Xr hosts 5 , .Xr resolv.conf 5 , .Xr services 5 , .Xr hostname 7 .Rs .%A R. Gilligan .%A S. Thomson .%A J. Bound .%A J. McCann .%A W. Stevens .%T Basic Socket Interface Extensions for IPv6 .%R RFC 3493 .%D February 2003 .Re .Rs .%A S. Deering .%A B. Haberman .%A T. Jinmei .%A E. Nordmark .%A B. Zill .%T "IPv6 Scoped Address Architecture" .%R RFC 4007 .%D March 2005 .Re .Rs .%A Craig Metz .%T Protocol Independence Using the Sockets API .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" .%D June 2000 .Re .Sh STANDARDS The .Fn getaddrinfo function is defined by the .St -p1003.1-2004 specification and documented in .Dv "RFC 3493" , .Dq Basic Socket Interface Extensions for IPv6 . diff --git a/lib/libc/net/gethostbyname.3 b/lib/libc/net/gethostbyname.3 index 9f7156b7cd9c..85b6806092e5 100644 --- a/lib/libc/net/gethostbyname.3 +++ b/lib/libc/net/gethostbyname.3 @@ -1,402 +1,402 @@ .\" Copyright (c) 1983, 1987, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 .\" $FreeBSD$ .\" -.Dd June 20, 2022 +.Dd June 27, 2022 .Dt GETHOSTBYNAME 3 .Os .Sh NAME .Nm gethostbyname , .Nm gethostbyname2 , .Nm gethostbyaddr , .Nm gethostent , .Nm sethostent , .Nm endhostent , .Nm herror , .Nm hstrerror , .Nm gethostbyname_r , .Nm gethostbyname2_r , .Nm gethostbyaddr_r .Nd get network host entry .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In netdb.h .Vt int h_errno ; .Ft struct hostent * .Fn gethostbyname "const char *name" .Ft struct hostent * .Fn gethostbyname2 "const char *name" "int af" .Ft struct hostent * .Fn gethostbyaddr "const void *addr" "socklen_t len" "int af" .Ft struct hostent * .Fn gethostent void .Ft void .Fn sethostent "int stayopen" .Ft void .Fn endhostent void .Ft void .Fn herror "const char *string" .Ft const char * .Fn hstrerror "int err" .Ft int .Fn gethostbyname_r "const char *name" "struct hostent *he" "char *buffer" "size_t buflen" "struct hostent **result" "int *h_errnop" .Ft int .Fn gethostbyname2_r "const char *name" "int af" "struct hostent *he" "char *buffer" "size_t buflen" "struct hostent **result" "int *h_errnop" .Ft int .Fn gethostbyaddr_r "const void *addr" "socklen_t len" "int af" "struct hostent *hp" "char *buf" "size_t buflen" "struct hostent **result" "int *h_errno"p .Sh DESCRIPTION .Bf -symbolic The .Xr getaddrinfo 3 and .Xr getnameinfo 3 functions are preferred over the .Fn gethostbyname , .Fn gethostbyname2 , and .Fn gethostbyaddr functions. .Ef .Pp The .Fn gethostbyname , .Fn gethostbyname2 and .Fn gethostbyaddr functions each return a pointer to an object with the following structure describing an internet host referenced by name or by address, respectively. .Pp The .Fa name argument passed to .Fn gethostbyname or .Fn gethostbyname2 should point to a .Dv NUL Ns -terminated hostname. The .Fa addr argument passed to .Fn gethostbyaddr should point to an address which is .Fa len bytes long, in binary form (i.e., not an IP address in human readable .Tn ASCII form). The .Fa af argument specifies the address family (e.g.\& .Dv AF_INET , AF_INET6 , etc.) of this address. .Pp The structure returned contains either the information obtained from the name server, broken-out fields from a line in .Pa /etc/hosts , or database entries supplied by the .Xr yp 8 system. The order of the lookups is controlled by the .Sq hosts entry in .Xr nsswitch.conf 5 . .Bd -literal struct hostent { char *h_name; /* official name of host */ char **h_aliases; /* alias list */ int h_addrtype; /* host address type */ int h_length; /* length of address */ char **h_addr_list; /* list of addresses from name server */ }; #define h_addr h_addr_list[0] /* address, for backward compatibility */ .Ed .Pp The members of this structure are: .Bl -tag -width h_addr_list .It Va h_name Official name of the host. .It Va h_aliases A .Dv NULL Ns -terminated array of alternate names for the host. .It Va h_addrtype The type of address being returned; usually .Dv AF_INET . .It Va h_length The length, in bytes, of the address. .It Va h_addr_list A .Dv NULL Ns -terminated array of network addresses for the host. Host addresses are returned in network byte order. .It Va h_addr The first address in .Va h_addr_list ; this is for backward compatibility. .El .Pp When using the nameserver, .Fn gethostbyname and .Fn gethostbyname2 will search for the named host in the current domain and its parents unless the name ends in a dot. If the name contains no dot, and if the environment variable .Dq Ev HOSTALIASES contains the name of an alias file, the alias file will first be searched for an alias matching the input name. See .Xr hostname 7 for the domain search procedure and the alias file format. .Pp The .Fn gethostbyname2 function is an evolution of .Fn gethostbyname which is intended to allow lookups in address families other than .Dv AF_INET , for example .Dv AF_INET6 . .Pp The .Fn sethostent function may be used to request the use of a connected .Tn TCP socket for queries. Queries will by default use .Tn UDP datagrams. If the .Fa stayopen flag is non-zero, a .Tn TCP connection to the name server will be used. It will remain open after calls to .Fn gethostbyname , .Fn gethostbyname2 or .Fn gethostbyaddr have completed. .Pp The .Fn endhostent function closes the .Tn TCP connection. .Pp The .Fn herror function writes a message to the diagnostic output consisting of the string argument .Fa string , the constant string .Qq Li ":\ " , and a message corresponding to the value of .Va h_errno . .Pp The .Fn hstrerror function returns a string which is the message text corresponding to the value of the .Fa err argument. .Pp Functions with the .Em _r suffix provide reentrant versions of their respective counterparts. The caller must supply five additional parameters: a .Vt struct hostent variable to be filled on success, a .Va buffer of .Va buflen bytes in size, a .Vt struct hostent .Va result variable that will point to the result on success or be set to .Dv NULL on failure or if the name is not found. The .Va h_errnop variable will be filled with the error code if any. All these functions return 0 on success. .Sh FILES .Bl -tag -width /etc/nsswitch.conf -compact .It Pa /etc/hosts .It Pa /etc/nsswitch.conf .It Pa /etc/resolv.conf .El .Sh EXAMPLES Print out the hostname associated with a specific IP address: .Bd -literal -offset indent const char *ipstr = "127.0.0.1"; struct in_addr ip; struct hostent *hp; if (!inet_aton(ipstr, &ip)) errx(1, "can't parse IP address %s", ipstr); if ((hp = gethostbyaddr((const void *)&ip, sizeof ip, AF_INET)) == NULL) errx(1, "no name associated with %s", ipstr); printf("name associated with %s is %s\en", ipstr, hp->h_name); .Ed .Sh DIAGNOSTICS Error return status from .Fn gethostbyname , .Fn gethostbyname2 and .Fn gethostbyaddr is indicated by return of a .Dv NULL pointer. The integer .Va h_errno may then be checked to see whether this is a temporary failure or an invalid or unknown host. The routine .Fn herror can be used to print an error message describing the failure. If its argument .Fa string is .Pf non- Dv NULL , it is printed, followed by a colon and a space. The error message is printed with a trailing newline. .Pp The variable .Va h_errno can have the following values: .Bl -tag -width HOST_NOT_FOUND .It Dv HOST_NOT_FOUND No such host is known. .It Dv TRY_AGAIN This is usually a temporary error and means that the local server did not receive a response from an authoritative server. A retry at some later time may succeed. .It Dv NO_RECOVERY Some unexpected server failure was encountered. This is a non-recoverable error. .It Dv NO_DATA The requested name is valid but does not have an IP address; this is not a temporary error. This means that the name is known to the name server but there is no address associated with this name. Another type of request to the name server using this domain name will result in an answer; for example, a mail-forwarder may be registered for this domain. .El .Sh SEE ALSO .Xr getaddrinfo 3 , .Xr getnameinfo 3 , .Xr inet_aton 3 , .Xr resolver 3 , .Xr hosts 5 , .Xr hostname 7 .Sh HISTORY The .Fn herror function appeared in .Bx 4.3 . The .Fn endhostent , .Fn gethostbyaddr , .Fn gethostbyname , .Fn gethostent , and .Fn sethostent functions appeared in .Bx 4.2 . The .Fn gethostbyname2 function first appeared in .Tn BIND version 4.9.4. .Sh CAVEATS The .Fn gethostent function is defined, and .Fn sethostent and .Fn endhostent are redefined, when .Lb libc is built to use only the routines to lookup in .Pa /etc/hosts and not the name server. .Pp The .Fn gethostent function reads the next line of .Pa /etc/hosts , opening the file if necessary. .Pp The .Fn sethostent function opens and/or rewinds the file .Pa /etc/hosts . If the .Fa stayopen argument is non-zero, the file will not be closed after each call to .Fn gethostbyname , .Fn gethostbyname2 or .Fn gethostbyaddr . .Pp The .Fn endhostent function closes the file. .Sh BUGS These functions use a thread-specific data storage; if the data is needed for future use, it should be copied before any subsequent calls overwrite it. .Pp Though these functions are thread-safe, still it is recommended to use the .Xr getaddrinfo 3 family of functions, instead. .Pp Only the Internet address format is currently understood. diff --git a/lib/libc/net/getipnodebyname.3 b/lib/libc/net/getipnodebyname.3 index 138d048ff8c6..d57f529a0707 100644 --- a/lib/libc/net/getipnodebyname.3 +++ b/lib/libc/net/getipnodebyname.3 @@ -1,473 +1,473 @@ .\" $KAME: getipnodebyname.3,v 1.6 2000/08/09 21:16:17 itojun Exp $ .\" .\" Copyright (c) 1983, 1987, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 .\" $FreeBSD$ .\" -.Dd August 6, 2004 +.Dd June 27, 2022 .Dt GETIPNODEBYNAME 3 .Os .\" .Sh NAME .Nm getipnodebyname , .Nm getipnodebyaddr , .Nm freehostent .Nd nodename-to-address and address-to-nodename translation .\" .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netdb.h .Ft "struct hostent *" .Fn getipnodebyname "const char *name" "int af" "int flags" "int *error_num" .Ft "struct hostent *" .Fn getipnodebyaddr "const void *src" "size_t len" "int af" "int *error_num" .Ft void .Fn freehostent "struct hostent *ptr" .\" .Sh DESCRIPTION The .Fn getipnodebyname and .Fn getipnodebyaddr functions are very similar to .Xr gethostbyname 3 , .Xr gethostbyname2 3 and .Xr gethostbyaddr 3 . The functions cover all the functionalities provided by the older ones, and provide better interface to programmers. The functions require additional arguments, .Fa af , and .Fa flags , for specifying address family and operation mode. The additional arguments allow programmer to get address for a nodename, for specific address family (such as .Dv AF_INET or .Dv AF_INET6 ) . The functions also require an additional pointer argument, .Fa error_num to return the appropriate error code, to support thread safe error code returns. .Pp The type and usage of the return value, .Li "struct hostent" is described in .Xr gethostbyname 3 . .Pp For .Fn getipnodebyname , the .Fa name argument can be either a node name or a numeric address string (i.e., a dotted-decimal IPv4 address or an IPv6 hex address). The .Fa af argument specifies the address family, either .Dv AF_INET or .Dv AF_INET6 . The .Fa flags argument specifies the types of addresses that are searched for, and the types of addresses that are returned. We note that a special flags value of .Dv AI_DEFAULT (defined below) should handle most applications. That is, porting simple applications to use IPv6 replaces the call .Bd -literal -offset indent hptr = gethostbyname(name); .Ed .Pp with .Bd -literal -offset indent hptr = getipnodebyname(name, AF_INET6, AI_DEFAULT, &error_num); .Ed .Pp Applications desiring finer control over the types of addresses searched for and returned, can specify other combinations of the .Fa flags argument. .Pp A .Fa flags of .Li 0 implies a strict interpretation of the .Fa af argument: .Bl -bullet .It If .Fa flags is 0 and .Fa af is .Dv AF_INET , then the caller wants only IPv4 addresses. A query is made for .Li A records. If successful, the IPv4 addresses are returned and the .Li h_length member of the .Li hostent structure will be 4, else the function returns a .Dv NULL pointer. .It If .Fa flags is 0 and if .Fa af is .Li AF_INET6 , then the caller wants only IPv6 addresses. A query is made for .Li AAAA records. If successful, the IPv6 addresses are returned and the .Li h_length member of the .Li hostent structure will be 16, else the function returns a .Dv NULL pointer. .El .Pp Other constants can be logically-ORed into the .Fa flags argument, to modify the behavior of the function. .Bl -bullet .It If the .Dv AI_V4MAPPED flag is specified along with an .Fa af of .Dv AF_INET6 , then the caller will accept IPv4-mapped IPv6 addresses. That is, if no .Li AAAA records are found then a query is made for .Li A records and any found are returned as IPv4-mapped IPv6 addresses .Li ( h_length will be 16). The .Dv AI_V4MAPPED flag is ignored unless .Fa af equals .Dv AF_INET6 . .It The .Dv AI_V4MAPPED_CFG flag is exact same as the .Dv AI_V4MAPPED flag only if the kernel supports IPv4-mapped IPv6 address. .It If the .Dv AI_ALL flag is used in conjunction with the .Dv AI_V4MAPPED flag, and only used with the IPv6 address family. When .Dv AI_ALL is logically or'd with .Dv AI_V4MAPPED flag then the caller wants all addresses: IPv6 and IPv4-mapped IPv6. A query is first made for .Li AAAA records and if successful, the IPv6 addresses are returned. Another query is then made for .Li A records and any found are returned as IPv4-mapped IPv6 addresses. .Li h_length will be 16. Only if both queries fail does the function return a .Dv NULL pointer. This flag is ignored unless af equals AF_INET6. If both .Dv AI_ALL and .Dv AI_V4MAPPED are specified, .Dv AI_ALL takes precedence. .It The .Dv AI_ADDRCONFIG flag specifies that a query for .Li AAAA records should occur only if the node has at least one IPv6 source address configured and a query for .Li A records should occur only if the node has at least one IPv4 source address configured. .Pp For example, if the node has no IPv6 source addresses configured, and .Fa af equals AF_INET6, and the node name being looked up has both .Li AAAA and .Li A records, then: (a) if only .Dv AI_ADDRCONFIG is specified, the function returns a .Dv NULL pointer; (b) if .Dv AI_ADDRCONFIG | .Dv AI_V4MAPPED is specified, the .Li A records are returned as IPv4-mapped IPv6 addresses; .El .Pp The special flags value of .Dv AI_DEFAULT is defined as .Bd -literal -offset indent #define AI_DEFAULT (AI_V4MAPPED_CFG | AI_ADDRCONFIG) .Ed .Pp We noted that the .Fn getipnodebyname function must allow the .Fa name argument to be either a node name or a literal address string (i.e., a dotted-decimal IPv4 address or an IPv6 hex address). This saves applications from having to call .Xr inet_pton 3 to handle literal address strings. When the .Fa name argument is a literal address string, the .Fa flags argument is always ignored. .Pp There are four scenarios based on the type of literal address string and the value of the .Fa af argument. The two simple cases are when .Fa name is a dotted-decimal IPv4 address and .Fa af equals .Dv AF_INET , or when .Fa name is an IPv6 hex address and .Fa af equals .Dv AF_INET6 . The members of the returned hostent structure are: .Li h_name points to a copy of the .Fa name argument, .Li h_aliases is a .Dv NULL pointer, .Li h_addrtype is a copy of the .Fa af argument, .Li h_length is either 4 (for .Dv AF_INET ) or 16 (for .Dv AF_INET6 ) , .Li h_addr_list[0] is a pointer to the 4-byte or 16-byte binary address, and .Li h_addr_list[1] is a .Dv NULL pointer. .Pp When .Fa name is a dotted-decimal IPv4 address and .Fa af equals .Dv AF_INET6 , and .Dv AI_V4MAPPED is specified, an IPv4-mapped IPv6 address is returned: .Li h_name points to an IPv6 hex address containing the IPv4-mapped IPv6 address, .Li h_aliases is a .Dv NULL pointer, .Li h_addrtype is .Dv AF_INET6 , .Li h_length is 16, .Li h_addr_list[0] is a pointer to the 16-byte binary address, and .Li h_addr_list[1] is a .Dv NULL pointer. .Pp It is an error when .Fa name is an IPv6 hex address and .Fa af equals .Dv AF_INET . The function's return value is a .Dv NULL pointer and the value pointed to by .Fa error_num equals .Dv HOST_NOT_FOUND . .Pp The .Fn getipnodebyaddr function takes almost the same argument as .Xr gethostbyaddr 3 , but adds a pointer to return an error number. Additionally it takes care of IPv4-mapped IPv6 addresses, and IPv4-compatible IPv6 addresses. .Pp The .Fn getipnodebyname and .Fn getipnodebyaddr functions dynamically allocate the structure to be returned to the caller. The .Fn freehostent function reclaims memory region allocated and returned by .Fn getipnodebyname or .Fn getipnodebyaddr . .\" .Sh FILES .Bl -tag -width /etc/nsswitch.conf -compact .It Pa /etc/hosts .It Pa /etc/nsswitch.conf .It Pa /etc/resolv.conf .El .\" .Sh DIAGNOSTICS The .Fn getipnodebyname and .Fn getipnodebyaddr functions returns .Dv NULL on errors. The integer values pointed to by .Fa error_num may then be checked to see whether this is a temporary failure or an invalid or unknown host. The meanings of each error code are described in .Xr gethostbyname 3 . .\" .Sh SEE ALSO .Xr getaddrinfo 3 , .Xr gethostbyaddr 3 , .Xr gethostbyname 3 , .Xr getnameinfo 3 , .Xr hosts 5 , .Xr nsswitch.conf 5 , .Xr services 5 , .Xr hostname 7 .Pp .Rs .%A R. Gilligan .%A S. Thomson .%A J. Bound .%A W. Stevens .%T Basic Socket Interface Extensions for IPv6 .%R RFC2553 .%D March 1999 .Re .\" .Sh STANDARDS The .Fn getipnodebyname and .Fn getipnodebyaddr functions are documented in .Dq Basic Socket Interface Extensions for IPv6 (RFC2553). .\" .Sh HISTORY The implementation first appeared in KAME advanced networking kit. .\" .Sh BUGS The .Fn getipnodebyname and .Fn getipnodebyaddr functions do not handle scoped IPv6 address properly. If you use these functions, your program will not be able to handle scoped IPv6 addresses. For IPv6 address manipulation, .Fn getaddrinfo 3 and .Fn getnameinfo 3 are recommended. .Pp The text was shamelessly copied from RFC2553. diff --git a/lib/libc/net/getnameinfo.3 b/lib/libc/net/getnameinfo.3 index b72b1c1e6545..021505542cfa 100644 --- a/lib/libc/net/getnameinfo.3 +++ b/lib/libc/net/getnameinfo.3 @@ -1,311 +1,311 @@ .\" $KAME: getnameinfo.3,v 1.37 2005/01/05 03:23:05 itojun Exp $ .\" $OpenBSD: getnameinfo.3,v 1.36 2004/12/21 09:48:20 jmc Exp $ .\" .\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") .\" Copyright (C) 2000, 2001 Internet Software Consortium. .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY .\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" .\" $FreeBSD$ .\" -.Dd March 15, 2018 +.Dd June 27, 2022 .Dt GETNAMEINFO 3 .Os .Sh NAME .Nm getnameinfo .Nd socket address structure to hostname and service name .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netdb.h .Ft int .Fo getnameinfo .Fa "const struct sockaddr *sa" "socklen_t salen" "char *host" .Fa "size_t hostlen" "char *serv" "size_t servlen" "int flags" .Fc .Sh DESCRIPTION The .Fn getnameinfo function is used to convert a .Li sockaddr structure to a pair of host name and service strings. It is a replacement for and provides more flexibility than the .Xr gethostbyaddr 3 and .Xr getservbyport 3 functions and is the converse of the .Xr getaddrinfo 3 function. .Pp If a link-layer address or UNIX-domain address is passed to .Fn getnameinfo , its ASCII representation will be stored in .Fa host . The string pointed to by .Fa serv will be set to the empty string if non-NULL; .Fa flags will always be ignored. For a link-layer address, this can be used as a replacement of the legacy .Xr link_ntoa 3 function. .Pp The .Li sockaddr structure .Fa sa should point to either a .Li sockaddr_in , .Li sockaddr_in6 , .Li sockaddr_dl , or .Li sockaddr_un structure .Po for IPv4 , IPv6, link-layer, or UNIX-domain respectively .Pc that is .Fa salen bytes long. If .Fa salen is shorter than the length corresponding to the specified address family or longer than .Fn sizeof "struct sockaddr_storage" , it returns .Er EAI_FAMILY . Note that .Va sa->sa_len should be consistent with .Fa salen though the value of .Va sa->sa_len is not directly used in this function. .Pp The host and service names associated with .Fa sa are stored in .Fa host and .Fa serv which have length parameters .Fa hostlen and .Fa servlen . The maximum value for .Fa hostlen is .Dv NI_MAXHOST and the maximum value for .Fa servlen is .Dv NI_MAXSERV , as defined by .Aq Pa netdb.h . If a length parameter is zero, no string will be stored. Otherwise, enough space must be provided to store the host name or service string plus a byte for the NUL terminator. .Pp The .Fa flags argument is formed by .Tn OR Ns 'ing the following values: .Bl -tag -width "NI_NUMERICSCOPEXX" .It Dv NI_NOFQDN A fully qualified domain name is not required for local hosts. The local part of the fully qualified domain name is returned instead. .It Dv NI_NUMERICHOST Return the address in numeric form, as if calling .Xr inet_ntop 3 , instead of a host name. .It Dv NI_NAMEREQD A name is required. If the host name cannot be found in DNS and this flag is set, a non-zero error code is returned. If the host name is not found and the flag is not set, the address is returned in numeric form. .It NI_NUMERICSERV The service name is returned as a digit string representing the port number. .It NI_NUMERICSCOPE The scope identifier is returned as a digit string. .It NI_DGRAM Specifies that the service being looked up is a datagram service, and causes .Xr getservbyport 3 to be called with a second argument of .Dq udp instead of its default of .Dq tcp . This is required for the few ports (512\-514) that have different services for .Tn UDP and .Tn TCP . .El .Pp This implementation allows numeric IPv6 address notation with scope identifier, as documented in chapter 11 of RFC 4007. IPv6 link-local address will appear as a string like .Dq Li fe80::1%ne0 . Refer to .Xr getaddrinfo 3 for more information. .Sh RETURN VALUES .Fn getnameinfo returns zero on success or one of the error codes listed in .Xr gai_strerror 3 if an error occurs. .Sh EXAMPLES The following code tries to get a numeric host name, and service name, for a given socket address. Observe that there is no hardcoded reference to a particular address family. .Bd -literal -offset indent struct sockaddr *sa; /* input */ char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV]; if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf, sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) { errx(1, "could not get numeric hostname"); /* NOTREACHED */ } printf("host=%s, serv=%s\en", hbuf, sbuf); .Ed .Pp The following version checks if the socket address has a reverse address mapping: .Bd -literal -offset indent struct sockaddr *sa; /* input */ char hbuf[NI_MAXHOST]; if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0, NI_NAMEREQD)) { errx(1, "could not resolve hostname"); /* NOTREACHED */ } printf("host=%s\en", hbuf); .Ed .Sh SEE ALSO .Xr gai_strerror 3 , .Xr getaddrinfo 3 , .Xr gethostbyaddr 3 , .Xr getservbyport 3 , .Xr inet_ntop 3 , .Xr link_ntoa 3 , .Xr resolver 3 , .Xr inet 4 , .Xr inet6 4 , .Xr unix 4 , .Xr hosts 5 , .Xr resolv.conf 5 , .Xr services 5 , .Xr hostname 7 .Rs .%A R. Gilligan .%A S. Thomson .%A J. Bound .%A J. McCann .%A W. Stevens .%T Basic Socket Interface Extensions for IPv6 .%R RFC 3493 .%D February 2003 .Re .Rs .%A S. Deering .%A B. Haberman .%A T. Jinmei .%A E. Nordmark .%A B. Zill .%T "IPv6 Scoped Address Architecture" .%R RFC 4007 .%D March 2005 .Re .Rs .%A Craig Metz .%T Protocol Independence Using the Sockets API .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" .%D June 2000 .Re .Sh STANDARDS The .Fn getnameinfo function is defined by the .St -p1003.1-2004 specification and documented in .Tn "RFC 3493" , .Dq Basic Socket Interface Extensions for IPv6 . .Sh CAVEATS .Fn getnameinfo can return both numeric and FQDN forms of the address specified in .Fa sa . There is no return value that indicates whether the string returned in .Fa host is a result of binary to numeric-text translation (like .Xr inet_ntop 3 ) , or is the result of a DNS reverse lookup. Because of this, malicious parties could set up a PTR record as follows: .Bd -literal -offset indent 1.0.0.127.in-addr.arpa. IN PTR 10.1.1.1 .Ed .Pp and trick the caller of .Fn getnameinfo into believing that .Fa sa is .Li 10.1.1.1 when it is actually .Li 127.0.0.1 . .Pp To prevent such attacks, the use of .Dv NI_NAMEREQD is recommended when the result of .Fn getnameinfo is used for access control purposes: .Bd -literal -offset indent struct sockaddr *sa; socklen_t salen; char addr[NI_MAXHOST]; struct addrinfo hints, *res; int error; error = getnameinfo(sa, salen, addr, sizeof(addr), NULL, 0, NI_NAMEREQD); if (error == 0) { memset(&hints, 0, sizeof(hints)); hints.ai_socktype = SOCK_DGRAM; /*dummy*/ hints.ai_flags = AI_NUMERICHOST; if (getaddrinfo(addr, "0", &hints, &res) == 0) { /* malicious PTR record */ freeaddrinfo(res); printf("bogus PTR record\en"); return -1; } /* addr is FQDN as a result of PTR lookup */ } else { /* addr is numeric string */ error = getnameinfo(sa, salen, addr, sizeof(addr), NULL, 0, NI_NUMERICHOST); } .Ed .\".Pp .\".Ox .\"intentionally uses a different .\".Dv NI_MAXHOST .\"value from what .\".Tn "RFC 2553" .\"suggests, to avoid buffer length handling mistakes. diff --git a/lib/libc/net/getnetent.3 b/lib/libc/net/getnetent.3 index 9fea2f391eff..de2811f07ac9 100644 --- a/lib/libc/net/getnetent.3 +++ b/lib/libc/net/getnetent.3 @@ -1,168 +1,168 @@ .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)getnetent.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" -.Dd June 4, 1993 +.Dd June 27, 2022 .Dt GETNETENT 3 .Os .Sh NAME .Nm getnetent , .Nm getnetbyaddr , .Nm getnetbyname , .Nm setnetent , .Nm endnetent .Nd get network entry .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In netdb.h .Ft struct netent * .Fn getnetent void .Ft struct netent * .Fn getnetbyname "const char *name" .Ft struct netent * .Fn getnetbyaddr "uint32_t net" "int type" .Ft void .Fn setnetent "int stayopen" .Ft void .Fn endnetent void .Sh DESCRIPTION The .Fn getnetent , .Fn getnetbyname , and .Fn getnetbyaddr functions each return a pointer to an object with the following structure describing an internet network. This structure contains either the information obtained from the nameserver, broken-out fields of a line in the network data base .Pa /etc/networks , or entries supplied by the .Xr yp 8 system. The order of the lookups is controlled by the `networks' entry in .Xr nsswitch.conf 5 . .Bd -literal -offset indent struct netent { char *n_name; /* official name of net */ char **n_aliases; /* alias list */ int n_addrtype; /* net number type */ uint32_t n_net; /* net number */ }; .Ed .Pp The members of this structure are: .Bl -tag -width n_addrtype .It Fa n_name The official name of the network. .It Fa n_aliases A zero terminated list of alternate names for the network. .It Fa n_addrtype The type of the network number returned; currently only AF_INET. .It Fa n_net The network number. Network numbers are returned in machine byte order. .El .Pp The .Fn getnetent function reads the next line of the file, opening the file if necessary. .Pp The .Fn setnetent function opens and rewinds the file. If the .Fa stayopen flag is non-zero, the net data base will not be closed after each call to .Fn getnetbyname or .Fn getnetbyaddr . .Pp The .Fn endnetent function closes the file. .Pp The .Fn getnetbyname function and .Fn getnetbyaddr sequentially search from the beginning of the file until a matching net name or net address and type is found, or until .Dv EOF is encountered. The .Fa type argument must be .Dv AF_INET . Network numbers are supplied in host order. .Sh FILES .Bl -tag -width /etc/nsswitch.conf -compact .It Pa /etc/networks .It Pa /etc/nsswitch.conf .It Pa /etc/resolv.conf .El .Sh DIAGNOSTICS Null pointer returned on .Dv EOF or error. .Sh SEE ALSO .Xr networks 5 .Pp .%T RFC 1101 .Sh HISTORY The .Fn getnetent , .Fn getnetbyaddr , .Fn getnetbyname , .Fn setnetent , and .Fn endnetent functions appeared in .Bx 4.2 . .Sh BUGS The data space used by these functions is thread-specific; if future use requires the data, it should be copied before any subsequent calls to these functions overwrite it. Only Internet network numbers are currently understood. Expecting network numbers to fit in no more than 32 bits is probably naive. diff --git a/lib/libc/net/hesiod.3 b/lib/libc/net/hesiod.3 index 4b2624ebf7f8..af62468557d2 100644 --- a/lib/libc/net/hesiod.3 +++ b/lib/libc/net/hesiod.3 @@ -1,175 +1,175 @@ .\" $NetBSD: hesiod.3,v 1.1 1999/01/25 03:43:04 lukem Exp $ .\" .\" from: #Id: hesiod.3,v 1.9.2.1 1997/01/03 21:02:23 ghudson Exp # .\" .\" Copyright 1988, 1996 by the Massachusetts Institute of Technology. .\" .\" Permission to use, copy, modify, and distribute this .\" software and its documentation for any purpose and without .\" fee is hereby granted, provided that the above copyright .\" notice appear in all copies and that both that copyright .\" notice and this permission notice appear in supporting .\" documentation, and that the name of M.I.T. not be used in .\" advertising or publicity pertaining to distribution of the .\" software without specific, written prior permission. .\" M.I.T. makes no representations about the suitability of .\" this software for any purpose. It is provided "as is" .\" without express or implied warranty. .\" .\" $FreeBSD$ .\" -.Dd November 30, 1996 +.Dd June 27, 2022 .Dt HESIOD 3 .Os .Sh NAME .Nm hesiod , .Nm hesiod_init , .Nm hesiod_resolve , .Nm hesiod_free_list , .Nm hesiod_to_bind , .Nm hesiod_end .Nd Hesiod name server interface library .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In hesiod.h .Ft int .Fn hesiod_init "void **context" .Ft char ** .Fn hesiod_resolve "void *context" "const char *name" "const char *type" .Ft void .Fn hesiod_free_list "void *context" "char **list" .Ft char * .Fn hesiod_to_bind "void *context" "const char *name" "const char *type" .Ft void .Fn hesiod_end "void *context" .Sh DESCRIPTION This family of functions allows you to perform lookups of Hesiod information, which is stored as text records in the Domain Name Service. To perform lookups, you must first initialize a .Fa context , an opaque object which stores information used internally by the library between calls. The .Fn hesiod_init function initializes a context, storing a pointer to the context in the location pointed to by the .Fa context argument. The .Fn hesiod_end function frees the resources used by a context. .Pp The .Fn hesiod_resolve function is the primary interface to the library. If successful, it returns a list of one or more strings giving the records matching .Fa name and .Fa type . The last element of the list is followed by a .Dv NULL pointer. It is the caller's responsibility to call .Fn hesiod_free_list to free the resources used by the returned list. .Pp The .Fn hesiod_to_bind function converts .Fa name and .Fa type into the DNS name used by .Fn hesiod_resolve . It is the caller's responsibility to free the returned string using .Fn free . .Sh RETURN VALUES .Rv -std hesiod_init On failure, .Fn hesiod_resolve and .Fn hesiod_to_bind return .Dv NULL and set the global variable .Va errno to indicate the error. .Sh ENVIRONMENT .Bl -tag -width HESIOD_CONFIG .It Ev HES_DOMAIN If the environment variable .Ev HES_DOMAIN is set, it will override the domain in the Hesiod configuration file. .It Ev HESIOD_CONFIG If the environment variable .Ev HESIOD_CONFIG is set, it specifies the location of the Hesiod configuration file. .El .Sh ERRORS Hesiod calls may fail because of: .Bl -tag -width Er .It Bq Er ENOMEM Insufficient memory was available to carry out the requested operation. .It Bq Er ENOEXEC The .Fn hesiod_init function failed because the Hesiod configuration file was invalid. .It Bq Er ECONNREFUSED The .Fn hesiod_resolve function failed because no name server could be contacted to answer the query. .It Bq Er EMSGSIZE The .Fn hesiod_resolve or .Fn hesiod_to_bind function failed because the query or response was too big to fit into the packet buffers. .It Bq Er ENOENT The .Fn hesiod_resolve function failed because the name server had no text records matching .Fa name and .Fa type , or .Fn hesiod_to_bind failed because the .Fa name argument had a domain extension which could not be resolved with type .Dq rhs\-extension in the local Hesiod domain. .El .Sh SEE ALSO .Xr hesiod.conf 5 .Rs .%T "Hesiod - Project Athena Technical Plan -- Name Service" .Re .Sh AUTHORS .An Steve Dyer , IBM/Project Athena .An Greg Hudson , MIT Team Athena .Pp Copyright 1987, 1988, 1995, 1996 by the Massachusetts Institute of Technology. .Sh BUGS The strings corresponding to the .Va errno values set by the Hesiod functions are not particularly indicative of what went wrong, especially for .Er ENOEXEC and .Er ENOENT . diff --git a/lib/libc/net/resolver.3 b/lib/libc/net/resolver.3 index 4f1269e993bb..98778f746a03 100644 --- a/lib/libc/net/resolver.3 +++ b/lib/libc/net/resolver.3 @@ -1,460 +1,460 @@ .\" Copyright (c) 1985, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)resolver.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" -.Dd May 29, 2009 +.Dd June 27, 2022 .Dt RESOLVER 3 .Os .Sh NAME .Nm res_query , .Nm res_search , .Nm res_mkquery , .Nm res_send , .Nm res_init , .Nm dn_comp , .Nm dn_expand , .Nm dn_skipname , .Nm ns_get16 , .Nm ns_get32 , .Nm ns_put16 , .Nm ns_put32 .Nd resolver routines .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In netinet/in.h .In arpa/nameser.h .In resolv.h .Ft int .Fo res_query .Fa "const char *dname" .Fa "int class" .Fa "int type" .Fa "u_char *answer" .Fa "int anslen" .Fc .Ft int .Fo res_search .Fa "const char *dname" .Fa "int class" .Fa "int type" .Fa "u_char *answer" .Fa "int anslen" .Fc .Ft int .Fo res_mkquery .Fa "int op" .Fa "const char *dname" .Fa "int class" .Fa "int type" .Fa "const u_char *data" .Fa "int datalen" .Fa "const u_char *newrr_in" .Fa "u_char *buf" .Fa "int buflen" .Fc .Ft int .Fo res_send .Fa "const u_char *msg" .Fa "int msglen" .Fa "u_char *answer" .Fa "int anslen" .Fc .Ft int .Fn res_init void .Ft int .Fo dn_comp .Fa "const char *exp_dn" .Fa "u_char *comp_dn" .Fa "int length" .Fa "u_char **dnptrs" .Fa "u_char **lastdnptr" .Fc .Ft int .Fo dn_expand .Fa "const u_char *msg" .Fa "const u_char *eomorig" .Fa "const u_char *comp_dn" .Fa "char *exp_dn" .Fa "int length" .Fc .Ft int .Fn dn_skipname "const u_char *comp_dn" "const u_char *eom" .Ft u_int .Fn ns_get16 "const u_char *src" .Ft u_long .Fn ns_get32 "const u_char *src" .Ft void .Fn ns_put16 "u_int src" "u_char *dst" .Ft void .Fn ns_put32 "u_long src" "u_char *dst" .Sh DESCRIPTION These routines are used for making, sending and interpreting query and reply messages with Internet domain name servers. .Pp Global configuration and state information that is used by the resolver routines is kept in the structure .Va _res . Most of the values have reasonable defaults and can be ignored. Options stored in .Va _res.options are defined in .In resolv.h and are as follows. Options are stored as a simple bit mask containing the bitwise ``or'' of the options enabled. .Bl -tag -width RES_USE_INET6 .It Dv RES_INIT True if the initial name server address and default domain name are initialized (i.e., .Fn res_init has been called). .It Dv RES_DEBUG Print debugging messages. .It Dv RES_AAONLY Accept authoritative answers only. With this option, .Fn res_send should continue until it finds an authoritative answer or finds an error. Currently this is not implemented. .It Dv RES_USEVC Use .Tn TCP connections for queries instead of .Tn UDP datagrams. .It Dv RES_STAYOPEN Used with .Dv RES_USEVC to keep the .Tn TCP connection open between queries. This is useful only in programs that regularly do many queries. .Tn UDP should be the normal mode used. .It Dv RES_IGNTC Unused currently (ignore truncation errors, i.e., do not retry with .Tn TCP ) . .It Dv RES_RECURSE Set the recursion-desired bit in queries. This is the default. .Pf ( Fn res_send does not do iterative queries and expects the name server to handle recursion.) .It Dv RES_DEFNAMES If set, .Fn res_search will append the default domain name to single-component names (those that do not contain a dot). This option is enabled by default. .It Dv RES_DNSRCH If this option is set, .Fn res_search will search for host names in the current domain and in parent domains; see .Xr hostname 7 . This is used by the standard host lookup routine .Xr gethostbyname 3 . This option is enabled by default. .It Dv RES_NOALIASES This option turns off the user level aliasing feature controlled by the .Dq Ev HOSTALIASES environment variable. Network daemons should set this option. .It Dv RES_USE_INET6 Enables support for IPv6-only applications. This causes IPv4 addresses to be returned as an IPv4 mapped address. For example, .Li 10.1.1.1 will be returned as .Li ::ffff:10.1.1.1 . The option is meaningful with certain kernel configuration only. .It Dv RES_USE_EDNS0 Enables support for OPT pseudo-RR for EDNS0 extension. With the option, resolver code will attach OPT pseudo-RR into DNS queries, to inform of our receive buffer size. The option will allow DNS servers to take advantage of non-default receive buffer size, and to send larger replies. DNS query packets with EDNS0 extension is not compatible with non-EDNS0 DNS servers. .El .Pp The .Fn res_init routine reads the configuration file (if any; see .Xr resolver 5 ) to get the default domain name, search list and the Internet address of the local name server(s). If no server is configured, the host running the resolver is tried. The current domain name is defined by the hostname if not specified in the configuration file; it can be overridden by the environment variable .Ev LOCALDOMAIN . This environment variable may contain several blank-separated tokens if you wish to override the .Em "search list" on a per-process basis. This is similar to the .Ic search command in the configuration file. Another environment variable .Dq Ev RES_OPTIONS can be set to override certain internal resolver options which are otherwise set by changing fields in the .Va _res structure or are inherited from the configuration file's .Ic options command. The syntax of the .Dq Ev RES_OPTIONS environment variable is explained in .Xr resolver 5 . Initialization normally occurs on the first call to one of the following routines. .Pp The .Fn res_query function provides an interface to the server query mechanism. It constructs a query, sends it to the local server, awaits a response, and makes preliminary checks on the reply. The query requests information of the specified .Fa type and .Fa class for the specified fully-qualified domain name .Fa dname . The reply message is left in the .Fa answer buffer with length .Fa anslen supplied by the caller. .Pp The .Fn res_search routine makes a query and awaits a response like .Fn res_query , but in addition, it implements the default and search rules controlled by the .Dv RES_DEFNAMES and .Dv RES_DNSRCH options. It returns the first successful reply. .Pp The remaining routines are lower-level routines used by .Fn res_query . The .Fn res_mkquery function constructs a standard query message and places it in .Fa buf . It returns the size of the query, or \-1 if the query is larger than .Fa buflen . The query type .Fa op is usually .Dv QUERY , but can be any of the query types defined in .In arpa/nameser.h . The domain name for the query is given by .Fa dname . The .Fa newrr_in argument is currently unused but is intended for making update messages. .Pp The .Fn res_send routine sends a pre-formatted query and returns an answer. It will call .Fn res_init if .Dv RES_INIT is not set, send the query to the local name server, and handle timeouts and retries. The length of the reply message is returned, or \-1 if there were errors. .Pp The .Fn dn_comp function compresses the domain name .Fa exp_dn and stores it in .Fa comp_dn . The size of the compressed name is returned or \-1 if there were errors. The size of the array pointed to by .Fa comp_dn is given by .Fa length . The compression uses an array of pointers .Fa dnptrs to previously-compressed names in the current message. The first pointer points to the beginning of the message and the list ends with .Dv NULL . The limit to the array is specified by .Fa lastdnptr . A side effect of .Fn dn_comp is to update the list of pointers for labels inserted into the message as the name is compressed. If .Fa dnptr is .Dv NULL , names are not compressed. If .Fa lastdnptr is .Dv NULL , the list of labels is not updated. .Pp The .Fn dn_expand entry expands the compressed domain name .Fa comp_dn to a full domain name The compressed name is contained in a query or reply message; .Fa msg is a pointer to the beginning of the message. The uncompressed name is placed in the buffer indicated by .Fa exp_dn which is of size .Fa length . The size of compressed name is returned or \-1 if there was an error. .Pp The .Fn dn_skipname function skips over a compressed domain name, which starts at a location pointed to by .Fa comp_dn . The compressed name is contained in a query or reply message; .Fa eom is a pointer to the end of the message. The size of compressed name is returned or \-1 if there was an error. .Pp The .Fn ns_get16 function gets a 16-bit quantity from a buffer pointed to by .Fa src . .Pp The .Fn ns_get32 function gets a 32-bit quantity from a buffer pointed to by .Fa src . .Pp The .Fn ns_put16 function puts a 16-bit quantity .Fa src to a buffer pointed to by .Fa dst . .Pp The .Fn ns_put32 function puts a 32-bit quantity .Fa src to a buffer pointed to by .Fa dst . .Sh IMPLEMENTATION NOTES This implementation of the resolver is thread-safe, but it will not function properly if the programmer attempts to declare his or her own .Va _res structure in an attempt to replace the per-thread version referred to by that macro. .Pp The following compile-time option can be specified to change the default behavior of resolver routines when necessary. .Bl -tag -width RES_ENFORCE_RFC1034 .It Dv RES_ENFORCE_RFC1034 If this symbol is defined during compile-time, .Fn res_search will enforce RFC 1034 check, namely, disallow using of underscore character within host names. This is used by the standard host lookup routines like .Xr gethostbyname 3 . For compatibility reasons this option is not enabled by default. .El .Sh RETURN VALUES The .Fn res_init function will return 0 on success, or \-1 in a threaded program if per-thread storage could not be allocated. .Pp The .Fn res_mkquery , .Fn res_search , and .Fn res_query functions return the size of the response on success, or \-1 if an error occurs. The integer .Vt h_errno may be checked to determine the reason for error. See .Xr gethostbyname 3 for more information. .Sh FILES .Bl -tag -width /etc/resolv.conf .It Pa /etc/resolv.conf The configuration file, see .Xr resolver 5 . .El .Sh SEE ALSO .Xr gethostbyname 3 , .Xr resolver 5 , .Xr hostname 7 .Pp .%T RFC1032 , .%T RFC1033 , .%T RFC1034 , .%T RFC1035 , .%T RFC974 .Rs .%T "Name Server Operations Guide for BIND" .Re .Sh HISTORY The .Nm function appeared in .Bx 4.3 . diff --git a/sbin/routed/routed.8 b/sbin/routed/routed.8 index 530b2b6c5cc8..6988e916fa78 100644 --- a/sbin/routed/routed.8 +++ b/sbin/routed/routed.8 @@ -1,744 +1,744 @@ .\" $Revision: 2.26 $ .\" .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)routed.8 8.2 (Berkeley) 12/11/93 .\" $FreeBSD$ .\" -.Dd August 26, 2014 +.Dd June 27, 2022 .Dt ROUTED 8 .Os .Sh NAME .Nm routed , .Nm rdisc .Nd network RIP and router discovery routing daemon .Sh SYNOPSIS .Nm .Op Fl isqdghmpAtv .Op Fl T Ar tracefile .Oo .Fl F .Ar net Ns Op /mask Ns Op ,metric .Oc .Op Fl P Ar parms .Sh DESCRIPTION The .Nm utility is a daemon invoked at boot time to manage the network routing tables. It uses Routing Information Protocol, RIPv1 (RFC\ 1058), RIPv2 (RFC\ 1723), and Internet Router Discovery Protocol (RFC 1256) to maintain the kernel routing table. The RIPv1 protocol is based on the reference .Bx 4.3 daemon. .Pp It listens on the .Xr udp 4 socket for the .Xr route 8 service (see .Xr services 5 ) for Routing Information Protocol packets. It also sends and receives multicast Router Discovery ICMP messages. If the host is a router, .Nm periodically supplies copies of its routing tables to any directly connected hosts and networks. It also advertises or solicits default routes using Router Discovery ICMP messages. .Pp When started (or when a network interface is later turned on), .Nm uses an AF_ROUTE address family facility to find those directly connected interfaces configured into the system and marked "up". It adds necessary routes for the interfaces to the kernel routing table. Soon after being first started, and provided there is at least one interface on which RIP has not been disabled, .Nm deletes all pre-existing non-static routes in kernel table. Static routes in the kernel table are preserved and included in RIP responses if they have a valid RIP -hopcount (see .Xr route 8 ) . .Pp If more than one interface is present (not counting the loopback interface), it is assumed that the host should forward packets among the connected networks. After transmitting a RIP .Em request and Router Discovery Advertisements or Solicitations on a new interface, the daemon enters a loop, listening for RIP request and response and Router Discovery packets from other hosts. .Pp When a .Em request packet is received, .Nm formulates a reply based on the information maintained in its internal tables. The .Em response packet generated contains a list of known routes, each marked with a "hop count" metric (a count of 16 or greater is considered "infinite"). The advertised metric for a route reflects the metrics associated with interfaces (see .Xr ifconfig 8 ) though which it is received and sent, so setting the metric on an interface is an effective way to steer traffic. See also .Cm adj_inmetric and .Cm adj_outmetric parameters below. .Pp Responses do not include routes with a first hop on the requesting network to implement in part .Em split-horizon . Requests from query programs such as .Xr rtquery 8 are answered with the complete table. .Pp The routing table maintained by the daemon includes space for several gateways for each destination to speed recovery from a failing router. RIP .Em response packets received are used to update the routing tables provided they are from one of the several currently recognized gateways or advertise a better metric than at least one of the existing gateways. .Pp When an update is applied, .Nm records the change in its own tables and updates the kernel routing table if the best route to the destination changes. The change in the kernel routing table is reflected in the next batch of .Em response packets sent. If the next response is not scheduled for a while, a .Em flash update response containing only recently changed routes is sent. .Pp In addition to processing incoming packets, .Nm also periodically checks the routing table entries. If an entry has not been updated for 3 minutes, the entry's metric is set to infinity and marked for deletion. Deletions are delayed until the route has been advertised with an infinite metric to ensure the invalidation is propagated throughout the local internet. This is a form of .Em poison reverse . .Pp Routes in the kernel table that are added or changed as a result of ICMP Redirect messages are deleted after a while to minimize .Em black-holes . When a TCP connection suffers a timeout, the kernel tells .Nm , which deletes all redirected routes through the gateway involved, advances the age of all RIP routes through the gateway to allow an alternate to be chosen, and advances of the age of any relevant Router Discovery Protocol default routes. .Pp Hosts acting as internetwork routers gratuitously supply their routing tables every 30 seconds to all directly connected hosts and networks. These RIP responses are sent to the broadcast address on nets that support broadcasting, to the destination address on point-to-point links, and to the router's own address on other networks. If RIPv2 is enabled, multicast packets are sent on interfaces that support multicasting. .Pp If no response is received on a remote interface, if there are errors while sending responses, or if there are more errors than input or output (see .Xr netstat 1 ) , then the cable or some other part of the interface is assumed to be disconnected or broken, and routes are adjusted appropriately. .Pp The .Em Internet Router Discovery Protocol is handled similarly. When the daemon is supplying RIP routes, it also listens for Router Discovery Solicitations and sends Advertisements. When it is quiet and listening to other RIP routers, it sends Solicitations and listens for Advertisements. If it receives a good Advertisement and it is not multi-homed, it stops listening for broadcast or multicast RIP responses. It tracks several advertising routers to speed recovery when the currently chosen router dies. If all discovered routers disappear, the daemon resumes listening to RIP responses. It continues listening to RIP while using Router Discovery if multi-homed to ensure all interfaces are used. .Pp The Router Discovery standard requires that advertisements have a default "lifetime" of 30 minutes. That means should something happen, a client can be without a good route for 30 minutes. It is a good idea to reduce the default to 45 seconds using .Fl P Cm rdisc_interval=45 on the command line or .Cm rdisc_interval=45 in the .Pa /etc/gateways file. .Pp While using Router Discovery (which happens by default when the system has a single network interface and a Router Discover Advertisement is received), there is a single default route and a variable number of redirected host routes in the kernel table. On a host with more than one network interface, this default route will be via only one of the interfaces. Thus, multi-homed hosts running with .Fl q might need .Cm no_rdisc described below. .Pp See the .Cm pm_rdisc facility described below to support "legacy" systems that can handle neither RIPv2 nor Router Discovery. .Pp By default, neither Router Discovery advertisements nor solicitations are sent over point to point links (e.g.\& PPP). The netmask associated with point-to-point links (such as SLIP or PPP, with the IFF_POINTOPOINT flag) is used by .Nm to infer the netmask used by the remote system when RIPv1 is used. .Pp The following options are available: .Bl -tag -width indent .It Fl i allow .Nm to accept a RIP request from non-router node. When specified once, .Nm replies to a route information query from neighbor nodes. When specified twice, it replies to a query from remote nodes in addition. .Xr rtquery 8 utility can be used to send a request. .Pp This feature is disabled by default because of a risk of reflection attack though it is useful for debugging purpose. .It Fl s force .Nm to supply routing information. This is the default if multiple network interfaces are present on which RIP or Router Discovery have not been disabled, and if the kernel switch ipforwarding=1. .It Fl q is the opposite of the .Fl s option. This is the default when only one interface is present. With this explicit option, the daemon is always in "quiet-mode" for RIP and does not supply routing information to other computers. .It Fl d do not run in the background. This option is meant for interactive use. .It Fl g used on internetwork routers to offer a route to the "default" destination. It is equivalent to .Fl F .Cm 0/0,1 and is present mostly for historical reasons. A better choice is .Fl P Cm pm_rdisc on the command line or .Cm pm_rdisc in the .Pa /etc/gateways file, since a larger metric will be used, reducing the spread of the potentially dangerous default route. This is typically used on a gateway to the Internet, or on a gateway that uses another routing protocol whose routes are not reported to other local routers. Notice that because a metric of 1 is used, this feature is dangerous. It is more commonly accidentally used to create chaos with a routing loop than to solve problems. .It Fl h cause host or point-to-point routes to not be advertised, provided there is a network route going the same direction. That is a limited kind of aggregation. This option is useful on gateways to Ethernets that have other gateway machines connected with point-to-point links such as SLIP. .It Fl m cause the machine to advertise a host or point-to-point route to its primary interface. It is useful on multi-homed machines such as NFS servers. This option should not be used except when the cost of the host routes it generates is justified by the popularity of the server. It is effective only when the machine is supplying routing information, because there is more than one interface. The .Fl m option overrides the .Fl q option to the limited extent of advertising the host route. .It Fl A do not ignore RIPv2 authentication if we do not care about RIPv2 authentication. This option is required for conformance with RFC 1723. However, it makes no sense and breaks using RIP as a discovery protocol to ignore all RIPv2 packets that carry authentication when this machine does not care about authentication. .It Fl t increase the debugging level, which causes more information to be logged on the tracefile specified with .Fl T or standard out. The debugging level can be increased or decreased with the .Em SIGUSR1 or .Em SIGUSR2 signals or with the .Xr rtquery 8 command. .It Fl T Ar tracefile increases the debugging level to at least 1 and causes debugging information to be appended to the trace file. Note that because of security concerns, it is wisest to not run .Nm routinely with tracing directed to a file. .It Fl v display and logs the version of daemon. .It Fl F Ar net[/mask][,metric] minimize routes in transmissions via interfaces with addresses that match .Em net/mask , and synthesizes a default route to this machine with the .Em metric . The intent is to reduce RIP traffic on slow, point-to-point links such as PPP links by replacing many large UDP packets of RIP information with a single, small packet containing a "fake" default route. If .Em metric is absent, a value of 14 is assumed to limit the spread of the "fake" default route. This is a dangerous feature that when used carelessly can cause routing loops. Notice also that more than one interface can match the specified network number and mask. See also .Fl g . .It Fl P Ar parms is equivalent to adding the parameter line .Em parms to the .Pa /etc/gateways file. .El .Pp Any other argument supplied is interpreted as the name of a file in which the actions of .Nm should be logged. It is better to use .Fl T instead of appending the name of the trace file to the command. .Pp The .Nm utility also supports the notion of "distant" .Em passive or .Em active gateways. When .Nm is started, it reads the file .Pa /etc/gateways to find such distant gateways which may not be located using only information from a routing socket, to discover if some of the local gateways are .Em passive , and to obtain other parameters. Gateways specified in this manner should be marked passive if they are not expected to exchange routing information, while gateways marked active should be willing to exchange RIP packets. Routes through .Em passive gateways are installed in the kernel's routing tables once upon startup and are not included in transmitted RIP responses. .Pp Distant active gateways are treated like network interfaces. RIP responses are sent to the distant .Em active gateway. If no responses are received, the associated route is deleted from the kernel table and RIP responses advertised via other interfaces. If the distant gateway resumes sending RIP responses, the associated route is restored. .Pp Such gateways can be useful on media that do not support broadcasts or multicasts but otherwise act like classic shared media like Ethernets such as some ATM networks. One can list all RIP routers reachable on the HIPPI or ATM network in .Pa /etc/gateways with a series of "host" lines. Note that it is usually desirable to use RIPv2 in such situations to avoid generating lists of inferred host routes. .Pp Gateways marked .Em external are also passive, but are not placed in the kernel routing table nor are they included in routing updates. The function of external entries is to indicate that another routing process will install such a route if necessary, and that other routes to that destination should not be installed by .Nm . Such entries are only required when both routers may learn of routes to the same destination. .Pp The .Pa /etc/gateways file is comprised of a series of lines, each in one of the following two formats or consist of parameters described later. Blank lines and lines starting with '#' are comments. .Bd -ragged .Cm net .Ar Nname[/mask] .Cm gateway .Ar Gname .Cm metric .Ar value .Pf < Cm passive No \&| .Cm active No \&| .Cm extern Ns > .Ed .Bd -ragged .Cm host .Ar Hname .Cm gateway .Ar Gname .Cm metric .Ar value .Pf < Cm passive No \&| .Cm active No \&| .Cm extern Ns > .Ed .Pp .Ar Nname or .Ar Hname is the name of the destination network or host. It may be a symbolic network name or an Internet address specified in "dot" notation (see .Xr inet 3 ) . (If it is a name, then it must either be defined in .Pa /etc/networks or .Pa /etc/hosts , or a method in .Xr nsswitch.conf 5 must be able to resolve it.) .Pp .Ar Mask is an optional number between 1 and 32 indicating the netmask associated with .Ar Nname . .Pp .Ar Gname is the name or address of the gateway to which RIP responses should be forwarded. .Pp .Ar Value is the hop count to the destination host or network. .Pp .Cm Host Ar hname is equivalent to .Cm net Ar nname/32 . .Pp One of the keywords .Cm passive , .Cm active or .Cm external must be present to indicate whether the gateway should be treated as .Cm passive or .Cm active (as described above), or whether the gateway is .Cm external to the scope of the RIP protocol. .Pp As can be seen when debugging is turned on with .Fl t , such lines create pseudo-interfaces. To set parameters for remote or external interfaces, a line starting with .Cm if=alias(Hname) , .Cm if=remote(Hname) , etc.\& should be used. .Ss Parameters Lines that start with neither "net" nor "host" must consist of one or more of the following parameter settings, separated by commas or blanks: .Bl -tag -width indent .It Cm if Ns = Ns Ar ifname indicates that the other parameters on the line apply to the interface name .Ar ifname . .It Cm subnet Ns = Ns Ar nname Ns Oo / Ns Ar mask Oc Ns Op , Ns Ar metric advertises a route to network .Ar nname with mask .Ar mask and the supplied metric (default 1). This is useful for filling "holes" in CIDR allocations. This parameter must appear by itself on a line. The network number must specify a full, 32-bit value, as in 192.0.2.0 instead of 192.0.2. .Pp Do not use this feature unless necessary. It is dangerous. .It Cm ripv1_mask Ns = Ns Ar nname Ns / Ns Ar mask1 , Ns Ar mask2 specifies that netmask of the network of which .Ar nname Ns / Ns Ar mask1 is a subnet should be .Ar mask2 . For example, .Dq Li ripv1_mask=192.0.2.16/28,27 marks 192.0.2.16/28 as a subnet of 192.0.2.0/27 instead of 192.0.2.0/24. It is better to turn on RIPv2 instead of using this facility, for example with .Cm ripv2_out . .It Cm passwd Ns = Ns Ar XXX[|KeyID[start|stop]] specifies a RIPv2 cleartext password that will be included on all RIPv2 responses sent, and checked on all RIPv2 responses received. Any blanks, tab characters, commas, or '#', '|', or NULL characters in the password must be escaped with a backslash (\\). The common escape sequences \\n, \\r, \\t, \\b, and \\xxx have their usual meanings. The .Cm KeyID must be unique but is ignored for cleartext passwords. If present, .Cm start and .Cm stop are timestamps in the form year/month/day@hour:minute. They specify when the password is valid. The valid password with the most future is used on output packets, unless all passwords have expired, in which case the password that expired most recently is used, or unless no passwords are valid yet, in which case no password is output. Incoming packets can carry any password that is valid, will be valid within the next 24 hours, or that was valid within the preceding 24 hours. To protect the secrets, the passwd settings are valid only in the .Pa /etc/gateways file and only when that file is readable only by UID 0. .It Cm md5_passwd Ns \&= Ns Ar XXX|KeyID[start|stop] specifies a RIPv2 MD5 password. Except that a .Cm KeyID is required, this keyword is similar to .Cm passwd . .It Cm no_ag turns off aggregation of subnets in RIPv1 and RIPv2 responses. .It Cm no_super_ag turns off aggregation of networks into supernets in RIPv2 responses. .It Cm passive marks the interface to not be advertised in updates sent via other interfaces, and turns off all RIP and router discovery through the interface. .It Cm no_rip disables all RIP processing on the specified interface. If no interfaces are allowed to process RIP packets, .Nm acts purely as a router discovery daemon. .Pp Note that turning off RIP without explicitly turning on router discovery advertisements with .Cm rdisc_adv or .Fl s causes .Nm to act as a client router discovery daemon, not advertising. .It Cm no_rip_mcast causes RIPv2 packets to be broadcast instead of multicast. .It Cm no_rip_out causes no RIP updates to be sent. .It Cm no_ripv1_in causes RIPv1 received responses to be ignored. .It Cm no_ripv2_in causes RIPv2 received responses to be ignored. .It Cm ripv2_out turns on RIPv2 output and causes RIPv2 advertisements to be multicast when possible. .It Cm ripv2 is equivalent to .Cm no_ripv1_in and .Cm no_ripv1_out . This enables RIPv2. .It Cm no_rdisc disables the Internet Router Discovery Protocol. .It Cm no_solicit disables the transmission of Router Discovery Solicitations. .It Cm send_solicit specifies that Router Discovery solicitations should be sent, even on point-to-point links, which by default only listen to Router Discovery messages. .It Cm no_rdisc_adv disables the transmission of Router Discovery Advertisements. .It Cm rdisc_adv specifies that Router Discovery Advertisements should be sent, even on point-to-point links, which by default only listen to Router Discovery messages. .It Cm bcast_rdisc specifies that Router Discovery packets should be broadcast instead of multicast. .It Cm rdisc_pref Ns \&= Ns Ar N sets the preference in Router Discovery Advertisements to the optionally signed integer .Ar N . The default preference is 0. Default routes with smaller or more negative preferences are preferred by clients. .It Cm rdisc_interval Ns \&= Ns Ar N sets the nominal interval with which Router Discovery Advertisements are transmitted to N seconds and their lifetime to 3*N. .It Cm fake_default Ns \&= Ns Ar metric has an identical effect to .Fl F Ar net[/mask][=metric] with the network and mask coming from the specified interface. .It Cm pm_rdisc is similar to .Cm fake_default . When RIPv2 routes are multicast, so that RIPv1 listeners cannot receive them, this feature causes a RIPv1 default route to be broadcast to RIPv1 listeners. Unless modified with .Cm fake_default , the default route is broadcast with a metric of 14. That serves as a "poor man's router discovery" protocol. .It Cm adj_inmetric Ns \&= Ns Ar delta adjusts the hop count or metric of received RIP routes by .Ar delta . The metric of every received RIP route is increased by the sum of two values associated with the interface. One is the adj_inmetric value and the other is the interface metric set with .Xr ifconfig 8 . .It Cm adj_outmetric Ns \&= Ns Ar delta adjusts the hop count or metric of advertised RIP routes by .Ar delta . The metric of every received RIP route is increased by the metric associated with the interface by which it was received, or by 1 if the interface does not have a non-zero metric. The metric of the received route is then increased by the adj_outmetric associated with the interface. Every advertised route is increased by a total of four values, the metric set for the interface by which it was received with .Xr ifconfig 8 , the .Cm adj_inmetric Ar delta of the receiving interface, the metric set for the interface by which it is transmitted with .Xr ifconfig 8 , and the .Cm adj_outmetric Ar delta of the transmitting interface. .It Cm trust_gateway Ns \&= Ns Ar rname[|net1/mask1|net2/mask2|...] causes RIP packets from router .Ar rname and other routers named in other .Cm trust_gateway keywords to be accepted, and packets from other routers to be ignored. If networks are specified, then routes to other networks will be ignored from that router. .It Cm redirect_ok allows the kernel to listen ICMP Redirect messages when the system is acting as a router and forwarding packets. Otherwise, ICMP Redirect messages are overridden and deleted when the system is acting as a router. .El .Sh FILES .Bl -tag -width /etc/gateways -compact .It Pa /etc/gateways for distant gateways .El .Sh SEE ALSO .Xr icmp 4 , .Xr udp 4 , .Xr rtquery 8 .Rs .%T Internet Transport Protocols .%R XSIS 028112 .%Q Xerox System Integration Standard .Re .Sh HISTORY The .Nm utility appeared in .Bx 4.2 . .\" LocalWords: loopback ICMP rtquery ifconfig multicasting Solicitations RIPv .\" LocalWords: netstat rdisc .Sh BUGS It does not always detect unidirectional failures in network interfaces, for example, when the output side fails. diff --git a/usr.bin/hesinfo/hesinfo.1 b/usr.bin/hesinfo/hesinfo.1 index 80e53245fbab..d9731822bec3 100644 --- a/usr.bin/hesinfo/hesinfo.1 +++ b/usr.bin/hesinfo/hesinfo.1 @@ -1,197 +1,197 @@ .\" $NetBSD: hesinfo.1,v 1.1 1999/01/25 22:45:55 lukem Exp $ .\" .\" from: #Id: hesinfo.1,v 1.9 1996/11/07 01:57:12 ghudson Exp # .\" .\" Copyright 1987, 1996 by the Massachusetts Institute of Technology. .\" .\" Permission to use, copy, modify, and distribute this .\" software and its documentation for any purpose and without .\" fee is hereby granted, provided that the above copyright .\" notice appear in all copies and that both that copyright .\" notice and this permission notice appear in supporting .\" documentation, and that the name of M.I.T. not be used in .\" advertising or publicity pertaining to distribution of the .\" software without specific, written prior permission. .\" M.I.T. makes no representations about the suitability of .\" this software for any purpose. It is provided "as is" .\" without express or implied warranty. .\" .\" $FreeBSD$ .\" -.Dd October 27, 1996 +.Dd June 27, 2022 .Dt HESINFO 1 .Os .Sh NAME .Nm hesinfo .Nd "find out what is stored in the Hesiod database" .Sh SYNOPSIS .Nm .Op Fl bl .Ar HesiodName HesiodNameType .Sh DESCRIPTION The .Nm utility takes two arguments, a name to be resolved and a string, known as a .Ar HesiodNameType . It then prints the information returned by the Hesiod nameserver. .Pp The value returned by .Nm is of the type .Ar HesiodNameType . .Pp The following options are available: .Bl -tag -width indent .It Fl l Selects long format. .It Fl b Prints the fully\-qualified string passed to the nameserver. .El .Ss VALID Hesiod_Names The following types of identifiers may be used in the .Ar HesiodName argument to .Nm . These values will be resolved by accessing the .Xr hesiod 3 database. .Bl -tag -width indent .It Aq Ar username the 8\-character\-or\-less string used to identify users or classes (e.g.\& joeuser, root, 1.00, etc). Used with the .Ar Hesiod_Name_Types .Cm passwd , .Cm pobox , and .Cm filsys . .It Aq Ar uid the id number assigned to a user. .It Aq Ar groupid the id number assigned to a group. .It Aq Ar groupname a name identifying a unique group. .It Aq Ar file\-system\-name the name of an Athena file system. .It Xo .Ao Ar "rvd\-server" Ac : Ns Aq Ar pack .Xc the name of an rvd's server and pack separated by a colon. .It Xo .Ao Ar "nfs\-server" Ac : Ns Aq Ar partition .Xc the name of an .Tn NFS server and its partition separated by a colon. .It Aq Ar workstation\-name the machine name of an Athena workstation (e.g.\& E40\-343\-3). .It Aq Ar service\-name name of an Athena service (e.g.\& Zephyr). .It Aq Ar service\-type name of .Ux service (valid entries are defined in .Pa /etc/services ) . .It Aq Ar printer\-name name of a printer. .It Aq Ar printer\-cluster\-name name of an Athena print cluster. .It Aq Ar foo some .Nm calls (e.g.\& .Cm prclusterlist ) do not require a specific .Ar HesiodName argument. However, you must include a dummy string (e.g.\& .Ql foo ) for .Nm to work properly. .El .Ss VALID Hesiod_Name_Types The following symbols are valid substitutions for the .Ar HesiodNameType argument to .Nm . .Bl -tag -width indent .It Cm passwd returns string suitable for inclusion in .Pa /etc/passwd , searching with .Aq Ar username . .It Cm pobox returns information on the pobox assigned to the user specified by .Ar HesiodName , searching with .Aq Ar username . .It Cm uid returns string suitable for inclusion in .Pa /etc/passwd , searching with .Aq Ar uid . .It Cm gid returns string suitable for inclusion in .Pa /etc/group , searching with .Aq Ar groupid . .It Cm group returns string suitable for inclusion in .Pa /etc/group , searching with .Aq Ar groupname . .It Cm grplist returns subgroups included in superset defined by .Aq Ar groupname . .It Cm filsys returns file system type, export point, server, mount mode, and import point for the following valid .Ar HesiodNames (see above) - .Aq Ar "file\-system\-name" , .Aq Ar username , .Ao Ar "rvd\-server" Ac : Ns Aq Ar pack , and .Ao Ar "nfs\-server" Ac : Ns Aq Ar partition . .It Cm cluster returns information about the local cluster the workstation, specified by .Aq Ar "workstation\-name" . Included is information about the local file and print servers. This information is accesses by .Sy clusterinfo at boot time. .It Cm sloc returns network name of service host for .Aq Ar service\-name . .It Cm service returns Internet protocol type and protocol service port for .Aq Ar service\-type . .It Cm pcap returns a valid entry for .Pa /etc/printcap for .Aq Ar printer\-name . .It Cm prcluserlist returns a list of print clusters. .It Cm prcluster returns a list of printers in a cluster specified by .Aq Ar printer\-cluster\-name . .El .Sh FILES .Bl -tag -width /etc/hesiod.conf .It Pa /etc/hesiod.conf .El .Sh SEE ALSO .Xr hesiod 3 .Rs .%T "Hesiod - Project Athena Technical Plan -- Name Service" .Re .Sh AUTHORS .An Steve Dyer , IBM/Project Athena .Pp Copyright 1987, 1988, 1996 by the Massachusetts Institute of Technology.