diff --git a/lib/libc/net/getaddrinfo.3 b/lib/libc/net/getaddrinfo.3 index bd0084db2b3c..bd7455127390 100644 --- a/lib/libc/net/getaddrinfo.3 +++ b/lib/libc/net/getaddrinfo.3 @@ -1,520 +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 .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 , -.Xr named 8 +.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 883e033971fb..9f7156b7cd9c 100644 --- a/lib/libc/net/gethostbyname.3 +++ b/lib/libc/net/gethostbyname.3 @@ -1,405 +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 .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, -.Xr named 8 , -broken-out fields from a line in +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 , -.Xr named 8 +.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 3af6ea21bcff..138d048ff8c6 100644 --- a/lib/libc/net/getipnodebyname.3 +++ b/lib/libc/net/getipnodebyname.3 @@ -1,474 +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 .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 , -.Xr named 8 +.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 5d5719c010c7..b72b1c1e6545 100644 --- a/lib/libc/net/getnameinfo.3 +++ b/lib/libc/net/getnameinfo.3 @@ -1,312 +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 .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 , -.Xr named 8 +.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 29eabdacd6bf..4cd74d9b53b5 100644 --- a/lib/libc/net/getnetent.3 +++ b/lib/libc/net/getnetent.3 @@ -1,196 +1,194 @@ .\" 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 20, 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 .Ft int .Fn getnetent_r "struct netent *ne" "char *buffer" "size_t buflen" "struct netent **result" "int *h_errnop" .Ft int .Fn getnetbyaddr_r "uint32_t net" "int type" "struct netent *ne" "char *buffer" "size_t buflen" "struct netent **result" int *h_errorp" .Ft int .Fn getnetbyname_r "const char *name" "struct netent *ne" "char *buffer" "size_t buflen" "struct netent **result" "int *h_errorp" .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, -.Xr named 8 , -broken-out fields of a line in the network data base +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. .Pp Functions with the .Em _r suffix provide reentrant versions of their respective counterparts. The caller must supply five additional parameters: a .Vt struct netent variable to be filled on success, a .Va buffer of .Va buflen bytes in size, a .Vt struct netent .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/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 bae4e4419f82..4b2624ebf7f8 100644 --- a/lib/libc/net/hesiod.3 +++ b/lib/libc/net/hesiod.3 @@ -1,176 +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 .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 , -.Xr named 8 +.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 684f2e8d98fc..4f1269e993bb 100644 --- a/lib/libc/net/resolver.3 +++ b/lib/libc/net/resolver.3 @@ -1,461 +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 .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 , -.Xr named 8 +.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 63f8f4da66ed..530b2b6c5cc8 100644 --- a/sbin/routed/routed.8 +++ b/sbin/routed/routed.8 @@ -1,745 +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 .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 -.Xr named 8 , -must have been started before -.Nm . ) +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 7ab2d35d4a30..80e53245fbab 100644 --- a/usr.bin/hesinfo/hesinfo.1 +++ b/usr.bin/hesinfo/hesinfo.1 @@ -1,198 +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 .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 , -.Xr named 8 +.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. diff --git a/usr.sbin/jail/jail.8 b/usr.sbin/jail/jail.8 index 61fe91cf973e..f1e39ebe04ca 100644 --- a/usr.sbin/jail/jail.8 +++ b/usr.sbin/jail/jail.8 @@ -1,1427 +1,1421 @@ .\" Copyright (c) 2000, 2003 Robert N. M. Watson .\" Copyright (c) 2008-2012 James Gritton .\" 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. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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. .\" .\" $FreeBSD$ .\" .Dd April 4, 2021 .Dt JAIL 8 .Os .Sh NAME .Nm jail .Nd "manage system jails" .Sh SYNOPSIS .Nm .Op Fl dhilqv .Op Fl J Ar jid_file .Op Fl u Ar username .Op Fl U Ar username .Op Fl cmr .Ar param Ns = Ns Ar value ... .Op Cm command Ns = Ns Ar command ... .Nm .Op Fl dqv .Op Fl f Ar conf_file .Op Fl p Ar limit .Op Fl cmr .Op Ar jail .Nm .Op Fl qv .Op Fl f Ar conf_file .Op Fl rR .Op Cm * | Ar jail ... .Nm .Op Fl dhilqv .Op Fl J Ar jid_file .Op Fl u Ar username .Op Fl U Ar username .Op Fl n Ar jailname .Op Fl s Ar securelevel .Ar path hostname ip Ns [ Ns Ar ,... Ns ] Ar command ... .Nm .Op Fl f Ar conf_file .Fl e .Ar separator .Sh DESCRIPTION The .Nm utility creates new jails, or modifies or removes existing jails. It can also print a list of configured jails and their parameters. A jail .Pq or Dq prison is specified via parameters on the command line, or in the .Xr jail.conf 5 file. .Pp At least one of the options .Fl c , .Fl e , .Fl m or .Fl r must be specified. These options are used alone or in combination to describe the operation to perform: .Bl -tag -width indent .It Fl c Create a new jail. The jail .Va jid and .Va name parameters (if specified on the command line) must not refer to an existing jail. .It Fl e Ar separator Exhibit a list of all configured non-wildcard jails and their parameters. No jail creation, modification or removal performed if this option is used. The .Ar separator string is used to separate parameters. Use .Xr jls 8 utility to list running jails. .It Fl m Modify an existing jail. One of the .Va jid or .Va name parameters must exist and refer to an existing jail. Some parameters may not be changed on a running jail. .It Fl r Remove the .Ar jail specified by jid or name. All jailed processes are killed, and all jails that are children of this jail are also removed. .It Fl rc Restart an existing jail. The jail is first removed and then re-created, as if .Dq Nm Fl r and .Dq Nm Fl c were run in succession. .It Fl cm Create a jail if it does not exist, or modify the jail if it does exist. .It Fl mr Modify an existing jail. The jail may be restarted if necessary to modify parameters than could not otherwise be changed. .It Fl cmr Create a jail if it doesn't exist, or modify (and possibly restart) the jail if it does exist. .El .Pp Other available options are: .Bl -tag -width indent .It Fl d Allow making changes to a dying jail, equivalent to the .Va allow.dying parameter. .It Fl f Ar conf_file Use configuration file .Ar conf_file instead of the default .Pa /etc/jail.conf . .It Fl h Resolve the .Va host.hostname parameter (or .Va hostname ) and add all IP addresses returned by the resolver to the list of addresses for this jail. This is equivalent to the .Va ip_hostname parameter. .It Fl i Output (only) the jail identifier of the newly created jail(s). This implies the .Fl q option. .It Fl J Ar jid_file Write a .Ar jid_file file, containing the parameters used to start the jail. .It Fl l Run commands in a clean environment. This is deprecated and is equivalent to the exec.clean parameter. .It Fl n Ar jailname Set the jail's name. This is deprecated and is equivalent to the .Va name parameter. .It Fl p Ar limit Limit the number of commands from .Va exec.* that can run simultaneously. .It Fl q Suppress the message printed whenever a jail is created, modified or removed. Only error messages will be printed. .It Fl R A variation of the .Fl r option that removes an existing jail without using the configuration file. No removal-related parameters for this jail will be used \(em the jail will simply be removed. .It Fl s Ar securelevel Set the .Va kern.securelevel MIB entry to the specified value inside the newly created jail. This is deprecated and is equivalent to the .Va securelevel parameter. .It Fl u Ar username The user name from host environment as whom jailed commands should run. This is deprecated and is equivalent to the .Va exec.jail_user and .Va exec.system_jail_user parameters. .It Fl U Ar username The user name from the jailed environment as whom jailed commands should run. This is deprecated and is equivalent to the .Va exec.jail_user parameter. .It Fl v Print a message on every operation, such as running commands and mounting filesystems. .El .Pp If no arguments are given after the options, the operation (except remove) will be performed on all jails specified in the .Xr jail.conf 5 file. A single argument of a jail name will operate only on the specified jail. The .Fl r and .Fl R options can also remove running jails that aren't in the .Xr jail.conf 5 file, specified by name or jid. .Pp An argument of .Dq * is a wildcard that will operate on all jails, regardless of whether they appear in .Xr jail.conf 5 ; this is the surest way for .Fl r to remove all jails. If hierarchical jails exist, a partial-matching wildcard definition may be specified. For example, an argument of .Dq foo.* would apply to jails with names like .Dq foo.bar and .Dq foo.bar.baz . .Pp A jail may be specified with parameters directly on the command line. In this case, the .Xr jail.conf 5 file will not be used. For backward compatibility, the command line may also have four fixed parameters, without names: .Ar path , .Ar hostname , .Ar ip , and .Ar command . This mode will always create a new jail, and the .Fl c and .Fl m options do not apply (and must not be present). .Ss Jail Parameters Parameters in the .Xr jail.conf 5 file, or on the command line, are generally of the form .Dq name=value . Some parameters are boolean, and do not have a value but are set by the name alone with or without a .Dq no prefix, e.g. .Va persist or .Va nopersist . They can also be given the values .Dq true and .Dq false . Other parameters may have more than one value, specified as a comma-separated list or with .Dq += in the configuration file (see .Xr jail.conf 5 for details). .Pp The .Nm utility recognizes two classes of parameters. There are the true jail parameters that are passed to the kernel when the jail is created, which can be seen with .Xr jls 8 , and can (usually) be changed with .Dq Nm Fl m . Then there are pseudo-parameters that are only used by .Nm itself. .Pp Jails have a set of core parameters, and kernel modules can add their own jail parameters. The current set of available parameters can be retrieved via .Dq Nm sysctl Fl d Va security.jail.param . Any parameters not set will be given default values, often based on the current environment. The core parameters are: .Bl -tag -width indent .It Va jid The jail identifier. This will be assigned automatically to a new jail (or can be explicitly set), and can be used to identify the jail for later modification, or for such commands as .Xr jls 8 or .Xr jexec 8 . .It Va name The jail name. This is an arbitrary string that identifies a jail (except it may not contain a .Sq \&. ) . Like the .Va jid , it can be passed to later .Nm commands, or to .Xr jls 8 or .Xr jexec 8 . If no .Va name is supplied, a default is assumed that is the same as the .Va jid . The .Va name parameter is implied by the .Xr jail.conf 5 file format, and need not be explicitly set when using the configuration file. .It Va path The directory which is to be the root of the jail. Any commands run inside the jail, either by .Nm or from .Xr jexec 8 , are run from this directory. .It Va ip4.addr A list of IPv4 addresses assigned to the jail. If this is set, the jail is restricted to using only these addresses. Any attempts to use other addresses fail, and attempts to use wildcard addresses silently use the jailed address instead. For IPv4 the first address given will be used as the source address when source address selection on unbound sockets cannot find a better match. It is only possible to start multiple jails with the same IP address if none of the jails has more than this single overlapping IP address assigned to itself. .It Va ip4.saddrsel A boolean option to change the formerly mentioned behaviour and disable IPv4 source address selection for the jail in favour of the primary IPv4 address of the jail. Source address selection is enabled by default for all jails and the .Va ip4.nosaddrsel setting of a parent jail is not inherited for any child jails. .It Va ip4 Control the availability of IPv4 addresses. Possible values are .Dq inherit to allow unrestricted access to all system addresses, .Dq new to restrict addresses via .Va ip4.addr , and .Dq disable to stop the jail from using IPv4 entirely. Setting the .Va ip4.addr parameter implies a value of .Dq new . .It Va ip6.addr , Va ip6.saddrsel , Va ip6 A set of IPv6 options for the jail, the counterparts to .Va ip4.addr , .Va ip4.saddrsel and .Va ip4 above. .It Va vnet Create the jail with its own virtual network stack, with its own network interfaces, addresses, routing table, etc. The kernel must have been compiled with the .Sy VIMAGE option for this to be available. Possible values are .Dq inherit to use the system network stack, possibly with restricted IP addresses, and .Dq new to create a new network stack. .It Va host.hostname The hostname of the jail. Other similar parameters are .Va host.domainname , .Va host.hostuuid and .Va host.hostid . .It Va host Set the origin of hostname and related information. Possible values are .Dq inherit to use the system information and .Dq new for the jail to use the information from the above fields. Setting any of the above fields implies a value of .Dq new . .It Va securelevel The value of the jail's .Va kern.securelevel sysctl. A jail never has a lower securelevel than its parent system, but by setting this parameter it may have a higher one. If the system securelevel is changed, any jail securelevels will be at least as secure. .It Va devfs_ruleset The number of the devfs ruleset that is enforced for mounting devfs in this jail. A value of zero (default) means no ruleset is enforced. Descendant jails inherit the parent jail's devfs ruleset enforcement. Mounting devfs inside a jail is possible only if the .Va allow.mount and .Va allow.mount.devfs permissions are effective and .Va enforce_statfs is set to a value lower than 2. Devfs rules and rulesets cannot be viewed or modified from inside a jail. .Pp NOTE: It is important that only appropriate device nodes in devfs be exposed to a jail; access to disk devices in the jail may permit processes in the jail to bypass the jail sandboxing by modifying files outside of the jail. See .Xr devfs 8 for information on how to use devfs rules to limit access to entries in the per-jail devfs. A simple devfs ruleset for jails is available as ruleset #4 in .Pa /etc/defaults/devfs.rules . .It Va children.max The number of child jails allowed to be created by this jail (or by other jails under this jail). This limit is zero by default, indicating the jail is not allowed to create child jails. See the .Sx "Hierarchical Jails" section for more information. .It Va children.cur The number of descendants of this jail, including its own child jails and any jails created under them. .It Va enforce_statfs This determines what information processes in a jail are able to get about mount points. It affects the behaviour of the following syscalls: .Xr statfs 2 , .Xr fstatfs 2 , .Xr getfsstat 2 , and .Xr fhstatfs 2 (as well as similar compatibility syscalls). When set to 0, all mount points are available without any restrictions. When set to 1, only mount points below the jail's chroot directory are visible. In addition to that, the path to the jail's chroot directory is removed from the front of their pathnames. When set to 2 (default), above syscalls can operate only on a mount-point where the jail's chroot directory is located. .It Va persist Setting this boolean parameter allows a jail to exist without any processes. Normally, a command is run as part of jail creation, and then the jail is destroyed as its last process exits. A new jail must have either the .Va persist parameter or .Va exec.start or .Va command pseudo-parameter set. .It Va cpuset.id The ID of the cpuset associated with this jail (read-only). .It Va dying This is true if the jail is in the process of shutting down (read-only). .It Va parent The .Va jid of the parent of this jail, or zero if this is a top-level jail (read-only). .It Va osrelease The string for the jail's .Va kern.osrelease sysctl and uname -r. .It Va osreldate The number for the jail's .Va kern.osreldate and uname -K. .It Va allow.* Some restrictions of the jail environment may be set on a per-jail basis. With the exception of .Va allow.set_hostname and .Va allow.reserved_ports , these boolean parameters are off by default. .Bl -tag -width indent .It Va allow.set_hostname The jail's hostname may be changed via .Xr hostname 1 or .Xr sethostname 3 . .It Va allow.sysvipc A process within the jail has access to System V IPC primitives. This is deprecated in favor of the per-module parameters (see below). When this parameter is set, it is equivalent to setting .Va sysvmsg , .Va sysvsem , and .Va sysvshm all to .Dq inherit . .It Va allow.raw_sockets The jail root is allowed to create raw sockets. Setting this parameter allows utilities like .Xr ping 8 and .Xr traceroute 8 to operate inside the jail. If this is set, the source IP addresses are enforced to comply with the IP address bound to the jail, regardless of whether or not the .Dv IP_HDRINCL flag has been set on the socket. Since raw sockets can be used to configure and interact with various network subsystems, extra caution should be used where privileged access to jails is given out to untrusted parties. .It Va allow.chflags Normally, privileged users inside a jail are treated as unprivileged by .Xr chflags 2 . When this parameter is set, such users are treated as privileged, and may manipulate system file flags subject to the usual constraints on .Va kern.securelevel . .It Va allow.mount privileged users inside the jail will be able to mount and unmount file system types marked as jail-friendly. The .Xr lsvfs 1 command can be used to find file system types available for mount from within a jail. This permission is effective only if .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.devfs privileged users inside the jail will be able to mount and unmount the devfs file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. The devfs ruleset should be restricted from the default by using the .Va devfs_ruleset option. .It Va allow.quotas The jail root may administer quotas on the jail's filesystem(s). This includes filesystems that the jail may share with other jails or with non-jailed parts of the system. .It Va allow.read_msgbuf Jailed users may read the kernel message buffer. If the .Va security.bsd.unprivileged_read_msgbuf MIB entry is zero, this will be restricted to the root user. .It Va allow.socket_af Sockets within a jail are normally restricted to IPv4, IPv6, local (UNIX), and route. This allows access to other protocol stacks that have not had jail functionality added to them. .It Va allow.mlock Locking or unlocking physical pages in memory are normally not available within a jail. When this parameter is set, users may .Xr mlock 2 or .Xr munlock 2 memory subject to .Va security.bsd.unprivileged_mlock and resource limits. .It Va allow.reserved_ports The jail root may bind to ports lower than 1024. .It Va allow.unprivileged_proc_debug Unprivileged processes in the jail may use debugging facilities. .It Va allow.suser The value of the jail's .Va security.bsd.suser_enabled sysctl. The super-user will be disabled automatically if its parent system has it disabled. The super-user is enabled by default. .El .El .Pp Kernel modules may add their own parameters, which only exist when the module is loaded. These are typically headed under a parameter named after the module, with values of .Dq inherit to give the jail full use of the module, .Dq new to encapsulate the jail in some module-specific way, and .Dq disable to make the module unavailable to the jail. There also may be other parameters to define jail behavior within the module. Module-specific parameters include: .Bl -tag -width indent .It Va allow.mount.fdescfs privileged users inside the jail will be able to mount and unmount the fdescfs file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.fusefs privileged users inside the jail will be able to mount and unmount fuse-based file systems. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.nullfs privileged users inside the jail will be able to mount and unmount the nullfs file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.procfs privileged users inside the jail will be able to mount and unmount the procfs file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.linprocfs privileged users inside the jail will be able to mount and unmount the linprocfs file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.linsysfs privileged users inside the jail will be able to mount and unmount the linsysfs file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.tmpfs privileged users inside the jail will be able to mount and unmount the tmpfs file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.zfs privileged users inside the jail will be able to mount and unmount the ZFS file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. See .Xr zfs 8 for information on how to configure the ZFS filesystem to operate from within a jail. .It Va allow.vmm The jail may access .Xr vmm 4 . This flag is only available when the .Xr vmm 4 kernel module is loaded. .It Va linux Determine how a jail's Linux emulation environment appears. A value of .Dq inherit will keep the same environment, and .Dq new will give the jail its own environment (still originally inherited when the jail is created). .It Va linux.osname , linux.osrelease , linux.oss_version The Linux OS name, OS release, and OSS version associated with this jail. .It Va sysvmsg Allow access to SYSV IPC message primitives. If set to .Dq inherit , all IPC objects on the system are visible to this jail, whether they were created by the jail itself, the base system, or other jails. If set to .Dq new , the jail will have its own key namespace, and can only see the objects that it has created; the system (or parent jail) has access to the jail's objects, but not to its keys. If set to .Dq disable , the jail cannot perform any sysvmsg-related system calls. .It Va sysvsem, sysvshm Allow access to SYSV IPC semaphore and shared memory primitives, in the same manner as .Va sysvmsg. .El .Pp There are pseudo-parameters that are not passed to the kernel, but are used by .Nm to set up the jail environment, often by running specified commands when jails are created or removed. The .Va exec.* command parameters are .Xr sh 1 command lines that are run in either the system or jail environment. They may be given multiple values, which would run the specified commands in sequence. All commands must succeed (return a zero exit status), or the jail will not be created or removed, as appropriate. .Pp The pseudo-parameters are: .Bl -tag -width indent .It Va exec.prepare Command(s) to run in the system environment to prepare a jail for creation. These commands are executed before assigning IP addresses and mounting filesystems, so they may be used to create a new jail filesystem if it does not already exist. .It Va exec.prestart Command(s) to run in the system environment before a jail is created. .It Va exec.created Command(s) to run in the system environment right after a jail has been created, but before commands (or services) get executed in the jail. .It Va exec.start Command(s) to run in the jail environment when a jail is created. A typical command to run is .Dq sh /etc/rc . .It Va command A synonym for .Va exec.start for use when specifying a jail directly on the command line. Unlike other parameters whose value is a single string, .Va command uses the remainder of the .Nm command line as its own arguments. .It Va exec.poststart Command(s) to run in the system environment after a jail is created, and after any .Va exec.start commands have completed. .It Va exec.prestop Command(s) to run in the system environment before a jail is removed. .It Va exec.stop Command(s) to run in the jail environment before a jail is removed, and after any .Va exec.prestop commands have completed. A typical command to run is .Dq sh /etc/rc.shutdown jail . .It Va exec.poststop Command(s) to run in the system environment after a jail is removed. .It Va exec.release Command(s) to run in the system environment after all other actions are done. These commands are executed after unmounting filesystems and removing IP addresses, so they may be used to remove a jail filesystem if it is no longer needed. .It Va exec.clean Run commands in a clean environment. The environment is discarded except for .Ev HOME , SHELL , TERM and .Ev USER . .Ev HOME and .Ev SHELL are set to the target login's default values. .Ev USER is set to the target login. .Ev TERM is imported from the current environment. The environment variables from the login class capability database for the target login are also set. .It Va exec.jail_user The user to run commands as, when running in the jail environment. The default is to run the commands as the current user. .It Va exec.system_jail_user This boolean option looks for the .Va exec.jail_user in the system .Xr passwd 5 file, instead of in the jail's file. .It Va exec.system_user The user to run commands as, when running in the system environment. The default is to run the commands as the current user. .It Va exec.timeout The maximum amount of time to wait for a command to complete, in seconds. If a command is still running after this timeout has passed, the jail will not be created or removed, as appropriate. .It Va exec.consolelog A file to direct command output (stdout and stderr) to. .It Va exec.fib The FIB (routing table) to set when running commands inside the jail. .It Va stop.timeout The maximum amount of time to wait for a jail's processes to exit after sending them a .Dv SIGTERM signal (which happens after the .Va exec.stop commands have completed). After this many seconds have passed, the jail will be removed, which will kill any remaining processes. If this is set to zero, no .Dv SIGTERM is sent and the jail is immediately removed. The default is 10 seconds. .It Va interface A network interface to add the jail's IP addresses .Va ( ip4.addr and .Va ip6.addr ) to. An alias for each address will be added to the interface before the jail is created, and will be removed from the interface after the jail is removed. .It Va ip4.addr In addition to the IP addresses that are passed to the kernel, an interface, netmask and additional parameters (as supported by .Xr ifconfig 8 Ns ) may also be specified, in the form .Dq Ar interface Ns | Ns Ar ip-address Ns / Ns Ar netmask param ... . If an interface is given before the IP address, an alias for the address will be added to that interface, as it is with the .Va interface parameter. If a netmask in either dotted-quad or CIDR form is given after an IP address, it will be used when adding the IP alias. If additional parameters are specified then they will also be used when adding the IP alias. .It Va ip6.addr In addition to the IP addresses that are passed to the kernel, an interface, prefix and additional parameters (as supported by .Xr ifconfig 8 Ns ) may also be specified, in the form .Dq Ar interface Ns | Ns Ar ip-address Ns / Ns Ar prefix param ... . .It Va vnet.interface A network interface to give to a vnet-enabled jail after is it created. The interface will automatically be released when the jail is removed. .It Va ip_hostname Resolve the .Va host.hostname parameter and add all IP addresses returned by the resolver to the list of addresses .Po Va ip4.addr or .Va ip6.addr Pc for this jail. This may affect default address selection for outgoing IPv4 connections from jails. The address first returned by the resolver for each address family will be used as the primary address. .It Va mount A filesystem to mount before creating the jail (and to unmount after removing it), given as a single .Xr fstab 5 line. .It Va mount.fstab An .Xr fstab 5 format file containing filesystems to mount before creating a jail. .It Va mount.devfs Mount a .Xr devfs 5 filesystem on the chrooted .Pa /dev directory, and apply the ruleset in the .Va devfs_ruleset parameter (or a default of ruleset 4: devfsrules_jail) to restrict the devices visible inside the jail. .It Va mount.fdescfs Mount a .Xr fdescfs 5 filesystem on the chrooted .Pa /dev/fd directory. .It Va mount.procfs Mount a .Xr procfs 5 filesystem on the chrooted .Pa /proc directory. .It Va allow.dying Allow making changes to a .Va dying jail. .It Va depend Specify a jail (or jails) that this jail depends on. When this jail is to be created, any jail(s) it depends on must already exist. If not, they will be created automatically, up to the completion of the last .Va exec.poststart command, before any action will taken to create this jail. When jails are removed the opposite is true: this jail will be removed, up to the last .Va exec.poststop command, before any jail(s) it depends on are stopped. .El .Sh EXAMPLES Jails are typically set up using one of two philosophies: either to constrain a specific application (possibly running with privilege), or to create a .Dq "virtual system image" running a variety of daemons and services. In both cases, a fairly complete file system install of .Fx is required, so as to provide the necessary command line tools, daemons, libraries, application configuration files, etc. However, for a virtual server configuration, a fair amount of additional work is required so as to replace the .Dq boot process. This manual page documents the configuration steps necessary to support either of these steps, although the configuration steps may need to be refined based on local requirements. .Ss "Setting up a Jail Directory Tree" To set up a jail directory tree containing an entire .Fx distribution, the following .Xr sh 1 command script can be used: .Bd -literal D=/here/is/the/jail cd /usr/src mkdir -p $D make world DESTDIR=$D make distribution DESTDIR=$D .Ed .Pp In many cases this example would put far more in the jail than needed. In the other extreme case a jail might contain only one file: the executable to be run in the jail. .Pp We recommend experimentation, and caution that it is a lot easier to start with a .Dq fat jail and remove things until it stops working, than it is to start with a .Dq thin jail and add things until it works. .Ss "Setting Up a Jail" Do what was described in .Sx "Setting Up a Jail Directory Tree" to build the jail directory tree. For the sake of this example, we will assume you built it in .Pa /data/jail/testjail , for a jail named .Dq testjail . Substitute below as needed with your own directory, IP address, and hostname. .Ss "Setting up the Host Environment" First, set up the real system's environment to be .Dq jail-friendly . For consistency, we will refer to the parent box as the .Dq "host environment" , and to the jailed virtual machine as the .Dq "jail environment" . Since jails are implemented using IP aliases, one of the first things to do is to disable IP services on the host system that listen on all local IP addresses for a service. If a network service is present in the host environment that binds all available IP addresses rather than specific IP addresses, it may service requests sent to jail IP addresses if the jail did not bind the port. This means changing .Xr inetd 8 to only listen on the appropriate IP address, and so forth. Add the following to .Pa /etc/rc.conf in the host environment: .Bd -literal -offset indent sendmail_enable="NO" inetd_flags="-wW -a 192.0.2.23" rpcbind_enable="NO" .Ed .Pp .Li 192.0.2.23 is the native IP address for the host system, in this example. Daemons that run out of .Xr inetd 8 can be easily configured to use only the specified host IP address. Other daemons will need to be manually configured \(em for some this is possible through .Xr rc.conf 5 flags entries; for others it is necessary to modify per-application configuration files, or to recompile the application. The following frequently deployed services must have their individual configuration files modified to limit the application to listening to a specific IP address: .Pp To configure .Xr sshd 8 , it is necessary to modify .Pa /etc/ssh/sshd_config . .Pp To configure .Xr sendmail 8 , it is necessary to modify .Pa /etc/mail/sendmail.cf . .Pp -For -.Xr named 8 , -it is necessary to modify -.Pa /etc/namedb/named.conf . -.Pp In addition, a number of services must be recompiled in order to run them in the host environment. This includes most applications providing services using .Xr rpc 3 , such as .Xr rpcbind 8 , .Xr nfsd 8 , and .Xr mountd 8 . In general, applications for which it is not possible to specify which IP address to bind should not be run in the host environment unless they should also service requests sent to jail IP addresses. Attempting to serve NFS from the host environment may also cause confusion, and cannot be easily reconfigured to use only specific IPs, as some NFS services are hosted directly from the kernel. Any third-party network software running in the host environment should also be checked and configured so that it does not bind all IP addresses, which would result in those services also appearing to be offered by the jail environments. .Pp Once these daemons have been disabled or fixed in the host environment, it is best to reboot so that all daemons are in a known state, to reduce the potential for confusion later (such as finding that when you send mail to a jail, and its sendmail is down, the mail is delivered to the host, etc.). .Ss "Configuring the Jail" Start any jail for the first time without configuring the network interface so that you can clean it up a little and set up accounts. As with any machine (virtual or not), you will need to set a root password, time zone, etc. Some of these steps apply only if you intend to run a full virtual server inside the jail; others apply both for constraining a particular application or for running a virtual server. .Pp Start a shell in the jail: .Bd -literal -offset indent jail -c path=/data/jail/testjail mount.devfs \\ host.hostname=testhostname ip4.addr=192.0.2.100 \\ command=/bin/sh .Ed .Pp Assuming no errors, you will end up with a shell prompt within the jail. You can now run .Xr bsdconfig 8 and do the post-install configuration to set various configuration options, or perform these actions manually by editing .Pa /etc/rc.conf , etc. .Pp .Bl -bullet -offset indent -compact .It Configure .Pa /etc/resolv.conf so that name resolution within the jail will work correctly. .It Run .Xr newaliases 1 to quell .Xr sendmail 8 warnings. .It Set a root password, probably different from the real host system. .It Set the timezone. .It Add accounts for users in the jail environment. .It Install any packages the environment requires. .El .Pp You may also want to perform any package-specific configuration (web servers, SSH servers, etc), patch up .Pa /etc/syslog.conf so it logs as you would like, etc. If you are not using a virtual server, you may wish to modify .Xr syslogd 8 in the host environment to listen on the syslog socket in the jail environment; in this example, the syslog socket would be stored in .Pa /data/jail/testjail/var/run/log . .Pp Exit from the shell, and the jail will be shut down. .Ss "Starting the Jail" You are now ready to restart the jail and bring up the environment with all of its daemons and other programs. Create an entry for the jail in .Pa /etc/jail.conf : .Bd -literal -offset indent testjail { path = /tmp/jail/testjail; mount.devfs; host.hostname = testhostname; ip4.addr = 192.0.2.100; interface = em0; exec.start = "/bin/sh /etc/rc"; exec.stop = "/bin/sh /etc/rc.shutdown jail"; } .Ed .Pp To start a virtual server environment, .Pa /etc/rc is run to launch various daemons and services, and .Pa /etc/rc.shutdown is run to shut them down when the jail is removed. If you are running a single application in the jail, substitute the command used to start the application for .Dq /bin/sh /etc/rc ; there may be some script available to cleanly shut down the application, or it may be sufficient to go without a stop command, and have .Nm send .Dv SIGTERM to the application. .Pp Start the jail by running: .Bd -literal -offset indent jail -c testjail .Ed .Pp A few warnings may be produced; however, it should all work properly. You should be able to see .Xr inetd 8 , .Xr syslogd 8 , and other processes running within the jail using .Xr ps 1 , with the .Ql J flag appearing beside jailed processes. To see an active list of jails, use .Xr jls 8 . If .Xr sshd 8 is enabled in the jail environment, you should be able to .Xr ssh 1 to the hostname or IP address of the jailed environment, and log in using the accounts you created previously. .Pp It is possible to have jails started at boot time. Please refer to the .Dq jail_* variables in .Xr rc.conf 5 for more information. .Ss "Managing the Jail" Normal machine shutdown commands, such as .Xr halt 8 , .Xr reboot 8 , and .Xr shutdown 8 , cannot be used successfully within the jail. To kill all processes from within a jail, you may use one of the following commands, depending on what you want to accomplish: .Bd -literal -offset indent kill -TERM -1 kill -KILL -1 .Ed .Pp This will send the .Dv SIGTERM or .Dv SIGKILL signals to all processes in the jail \(em be careful not to run this from the host environment! Once all of the jail's processes have died, unless the jail was created with the .Va persist parameter, the jail will be removed. Depending on the intended use of the jail, you may also want to run .Pa /etc/rc.shutdown from within the jail. .Pp To shut down the jail from the outside, simply remove it with .Nm .Ar -r , which will run any commands specified by .Va exec.stop , and then send .Dv SIGTERM and eventually .Dv SIGKILL to any remaining jailed processes. .Pp The .Pa /proc/ Ns Ar pid Ns Pa /status file contains, as its last field, the name of the jail in which the process runs, or .Dq Li - to indicate that the process is not running within a jail. The .Xr ps 1 command also shows a .Ql J flag for processes in a jail. .Pp You can also list/kill processes based on their jail ID. To show processes and their jail ID, use the following command: .Pp .Dl "ps ax -o pid,jid,args" .Pp To show and then kill processes in jail number 3 use the following commands: .Bd -literal -offset indent pgrep -lfj 3 pkill -j 3 .Ed or: .Pp .Dl "killall -j 3" .Ss "Jails and File Systems" It is not possible to .Xr mount 8 or .Xr umount 8 any file system inside a jail unless the file system is marked jail-friendly, the jail's .Va allow.mount parameter is set, and the jail's .Va enforce_statfs parameter is lower than 2. .Pp Multiple jails sharing the same file system can influence each other. For example, a user in one jail can fill the file system, leaving no space for processes in the other jail. Trying to use .Xr quota 1 to prevent this will not work either, as the file system quotas are not aware of jails but only look at the user and group IDs. This means the same user ID in two jails share a single file system quota. One would need to use one file system per jail to make this work. .Ss "Sysctl MIB Entries" The read-only entry .Va security.jail.jailed can be used to determine if a process is running inside a jail (value is one) or not (value is zero). .Pp The variable .Va security.jail.max_af_ips determines how may address per address family a jail may have. The default is 255. .Pp Some MIB variables have per-jail settings. Changes to these variables by a jailed process do not affect the host environment, only the jail environment. These variables are .Va kern.securelevel , .Va security.bsd.suser_enabled , .Va kern.hostname , .Va kern.domainname , .Va kern.hostid , and .Va kern.hostuuid . .Ss "Hierarchical Jails" By setting a jail's .Va children.max parameter, processes within a jail may be able to create jails of their own. These child jails are kept in a hierarchy, with jails only able to see and/or modify the jails they created (or those jails' children). Each jail has a read-only .Va parent parameter, containing the .Va jid of the jail that created it; a .Va jid of 0 indicates the jail is a child of the current jail (or is a top-level jail if the current process isn't jailed). .Pp Jailed processes are not allowed to confer greater permissions than they themselves are given, e.g., if a jail is created with .Va allow.nomount , it is not able to create a jail with .Va allow.mount set. Similarly, such restrictions as .Va ip4.addr and .Va securelevel may not be bypassed in child jails. .Pp A child jail may in turn create its own child jails if its own .Va children.max parameter is set (remember it is zero by default). These jails are visible to and can be modified by their parent and all ancestors. .Pp Jail names reflect this hierarchy, with a full name being an MIB-type string separated by dots. For example, if a base system process creates a jail .Dq foo , and a process under that jail creates another jail .Dq bar , then the second jail will be seen as .Dq foo.bar in the base system (though it is only seen as .Dq bar to any processes inside jail .Dq foo ) . Jids on the other hand exist in a single space, and each jail must have a unique jid. .Pp Like the names, a child jail's .Va path appears relative to its creator's own .Va path . This is by virtue of the child jail being created in the chrooted environment of the first jail. .Sh SEE ALSO .Xr killall 1 , .Xr lsvfs 1 , .Xr newaliases 1 , .Xr pgrep 1 , .Xr pkill 1 , .Xr ps 1 , .Xr quota 1 , .Xr jail_set 2 , .Xr vmm 4 , .Xr devfs 5 , .Xr fdescfs 5 , .Xr jail.conf 5 , .Xr linprocfs 5 , .Xr linsysfs 5 , .Xr procfs 5 , .Xr rc.conf 5 , .Xr sysctl.conf 5 , .Xr bsdconfig 8 , .Xr chroot 8 , .Xr devfs 8 , .Xr halt 8 , .Xr ifconfig 8 , .Xr inetd 8 , .Xr jexec 8 , .Xr jls 8 , .Xr mount 8 , -.Xr named 8 , .Xr reboot 8 , .Xr rpcbind 8 , .Xr sendmail 8 , .Xr shutdown 8 , .Xr sysctl 8 , .Xr syslogd 8 , .Xr umount 8 .Sh HISTORY The .Nm utility appeared in .Fx 4.0 . Hierarchical/extensible jails were introduced in .Fx 8.0 . The configuration file was introduced in .Fx 9.1 . .Sh AUTHORS .An -nosplit The jail feature was written by .An Poul-Henning Kamp for R&D Associates who contributed it to .Fx . .Pp .An Robert Watson wrote the extended documentation, found a few bugs, added a few new features, and cleaned up the userland jail environment. .Pp .An Bjoern A. Zeeb added multi-IP jail support for IPv4 and IPv6 based on a patch originally done by .An Pawel Jakub Dawidek for IPv4. .Pp .An James Gritton added the extensible jail parameters, hierarchical jails, and the configuration file. .Sh BUGS It might be a good idea to add an address alias flag such that daemons listening on all IPs .Pq Dv INADDR_ANY will not bind on that address, which would facilitate building a safe host environment such that host daemons do not impose on services offered from within jails. Currently, the simplest answer is to minimize services offered on the host, possibly limiting it to services offered from .Xr inetd 8 which is easily configurable. .Sh NOTES Great care should be taken when managing directories visible within the jail. For example, if a jailed process has its current working directory set to a directory that is moved out of the jail's chroot, then the process may gain access to the file space outside of the jail. It is recommended that directories always be copied, rather than moved, out of a jail. .Pp In addition, there are several ways in which an unprivileged user outside the jail can cooperate with a privileged user inside the jail and thereby obtain elevated privileges in the host environment. Most of these attacks can be mitigated by ensuring that the jail root is not accessible to unprivileged users in the host environment. Regardless, as a general rule, untrusted users with privileged access to a jail should not be given access to the host environment. diff --git a/usr.sbin/ppp/ppp.8 b/usr.sbin/ppp/ppp.8 index 00470f6e5273..9bc73f9cd93c 100644 --- a/usr.sbin/ppp/ppp.8 +++ b/usr.sbin/ppp/ppp.8 @@ -1,6093 +1,6089 @@ .\" .\" Copyright (c) 2001 Brian Somers .\" 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. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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. .\" .\" $FreeBSD$ .\" .Dd May 20, 2021 .Dt PPP 8 .Os .Sh NAME .Nm ppp .Nd Point to Point Protocol (a.k.a. user-ppp) .Sh SYNOPSIS .Nm .Op Fl Va mode .Op Fl nat .Op Fl quiet .Op Fl unit Ns Ar N .Op Ar system ... .Sh DESCRIPTION This is a user process .Em PPP software package. Sometimes, .Em PPP is implemented as a part of the kernel (e.g., as managed by .Nm pppd ) and it is thus somewhat hard to debug and/or modify its behaviour. However, in this implementation .Em PPP is done as a user process with the help of the tunnel device driver (tun). .Pp The .Fl nat flag does the equivalent of a .Dq nat enable yes , enabling .Nm Ns No 's network address translation features. This allows .Nm to act as a NAT or masquerading engine for all machines on an internal LAN. Refer to .Xr libalias 3 for details on the technical side of the NAT engine. Refer to the .Sx NETWORK ADDRESS TRANSLATION (PACKET ALIASING) section of this manual page for details on how to configure NAT in .Nm . .Pp The .Fl quiet flag tells .Nm to be silent at startup rather than displaying the mode and interface to standard output. .Pp The .Fl unit flag tells .Nm to only attempt to open .Pa /dev/tun Ns Ar N . Normally, .Nm will start with a value of 0 for .Ar N , and keep trying to open a tunnel device by incrementing the value of .Ar N by one each time until it succeeds. If it fails three times in a row because the device file is missing, it gives up. .Pp The following .Va mode Ns No s are understood by .Nm : .Bl -tag -width XXX -offset XXX .It Fl auto .Nm opens the tun interface, configures it then goes into the background. The link is not brought up until outgoing data is detected on the tun interface at which point .Nm attempts to bring up the link. Packets received (including the first one) while .Nm is trying to bring the link up will remain queued for a default of 2 minutes. See the .Dq set choked command below. .Pp In .Fl auto mode, at least one .Dq system must be given on the command line (see below) and a .Dq set ifaddr must be done in the system profile that specifies a peer IP address to use when configuring the interface. Something like .Dq 10.0.0.1/0 is usually appropriate. See the .Dq pmdemand system in .Pa /usr/share/examples/ppp/ppp.conf.sample for an example. .It Fl background Here, .Nm attempts to establish a connection with the peer immediately. If it succeeds, .Nm goes into the background and the parent process returns an exit code of 0. If it fails, .Nm exits with a non-zero result. .It Fl foreground In foreground mode, .Nm attempts to establish a connection with the peer immediately, but never becomes a daemon. The link is created in background mode. This is useful if you wish to control .Nm Ns No 's invocation from another process. .It Fl direct This is used for communicating over an already established connection, usually when receiving incoming connections accepted by .Xr getty 8 . .Nm ignores the .Dq set device line and uses descriptor 0 as the link. .Nm will also ignore any configured chat scripts unless the .Dq force-scripts option has been enabled. .Pp If callback is configured, .Nm will use the .Dq set device information when dialing back. .Pp When run in .Fl direct mode, .Nm will behave slightly differently if descriptor 0 was created by .Xr pipe 2 . As pipes are not bi-directional, ppp will redirect all writes to descriptor 1 (standard output), leaving only reads acting on descriptor 0. No special action is taken if descriptor 0 was created by .Xr socketpair 2 . .It Fl dedicated This option is designed for machines connected with a dedicated wire. .Nm will always keep the device open and will ignore any configured chat scripts unless the .Dq force-scripts option has been enabled. .It Fl ddial This mode is equivalent to .Fl auto mode except that .Nm will bring the link back up any time it is dropped for any reason. .It Fl interactive This is a no-op, and gives the same behaviour as if none of the above modes have been specified. .Nm loads any sections specified on the command line then provides an interactive prompt. .El .Pp One or more configuration entries or systems (as specified in .Pa /etc/ppp/ppp.conf ) may also be specified on the command line. .Nm will read the .Dq default system from .Pa /etc/ppp/ppp.conf at startup, followed by each of the systems specified on the command line. .Sh Major Features .Bl -diag .It Provides an interactive user interface. Using its command mode, the user can easily enter commands to establish the connection with the remote end, check the status of connection and close the connection. All functions can also be optionally password protected for security. .It Supports both manual and automatic dialing. Interactive mode has a .Dq term command which enables you to talk to the device directly. When you are connected to the remote peer and it starts to talk .Em PPP , .Nm detects it and switches to packet mode automatically. Once you have determined the proper sequence for connecting with the remote host, you can write a chat script to {define} the necessary dialing and login procedure for later convenience. .It Supports on-demand dialup capability. By using .Fl auto mode, .Nm will act as a daemon and wait for a packet to be sent over the .Em PPP link. When this happens, the daemon automatically dials and establishes the connection. In almost the same manner .Fl ddial mode (direct-dial mode) also automatically dials and establishes the connection. However, it differs in that it will dial the remote site any time it detects the link is down, even if there are no packets to be sent. This mode is useful for full-time connections where we worry less about line charges and more about being connected full time. A third .Fl dedicated mode is also available. This mode is targeted at a dedicated link between two machines. .Nm will never voluntarily quit from dedicated mode - you must send it the .Dq quit all command via its diagnostic socket. A .Dv SIGHUP will force an LCP renegotiation, and a .Dv SIGTERM will force it to exit. .It Supports client callback. .Nm can use either the standard LCP callback protocol or the Microsoft CallBack Control Protocol (https://winprotocoldoc.blob.core.windows.net/productionwindowsarchives/MS-CBCP/[MS-CBCP].pdf). .It Supports NAT or packet aliasing. Packet aliasing (a.k.a.\& IP masquerading) allows computers on a private, unregistered network to access the Internet. The .Em PPP host acts as a masquerading gateway. IP addresses as well as TCP and UDP port numbers are NAT'd for outgoing packets and de-NAT'd for returning packets. .It Supports background PPP connections. In background mode, if .Nm successfully establishes the connection, it will become a daemon. Otherwise, it will exit with an error. This allows the setup of scripts that wish to execute certain commands only if the connection is successfully established. .It Supports server-side PPP connections. In direct mode, .Nm acts as server which accepts incoming .Em PPP connections on stdin/stdout. .It Supports PAP and CHAP (rfc 1994, 2433 and 2759) authentication. With PAP or CHAP, it is possible to skip the Unix style .Xr login 1 procedure, and use the .Em PPP protocol for authentication instead. If the peer requests Microsoft CHAP authentication and .Nm is compiled with DES support, an appropriate MD4/DES response will be made. .It Supports RADIUS (rfc 2138 & 2548) authentication. An extension to PAP and CHAP, .Em \&R Ns No emote .Em \&A Ns No ccess .Em \&D Ns No ial .Em \&I Ns No n .Em \&U Ns No ser .Em \&S Ns No ervice allows authentication information to be stored in a central or distributed database along with various per-user framed connection characteristics. If .Xr libradius 3 is available at compile time, .Nm will use it to make .Em RADIUS requests when configured to do so. .It Supports Proxy Arp. .Nm can be configured to make one or more proxy arp entries on behalf of the peer. This allows routing from the peer to the LAN without configuring each machine on that LAN. .It Supports packet filtering. User can {define} four kinds of filters: the .Em in filter for incoming packets, the .Em out filter for outgoing packets, the .Em dial filter to {define} a dialing trigger packet and the .Em alive filter for keeping a connection alive with the trigger packet. .It Tunnel driver supports bpf. The user can use .Xr tcpdump 1 to check the packet flow over the .Em PPP link. .It Supports PPP over TCP and PPP over UDP. If a device name is specified as .Em host Ns No : Ns Em port Ns .Xo .Op / Ns tcp|udp , .Xc .Nm will open a TCP or UDP connection for transporting data rather than using a conventional serial device. UDP connections force .Nm into synchronous mode. .It Supports PPP over Ethernet (rfc 2516). If .Nm is given a device specification of the format .No PPPoE: Ns Ar iface Ns Xo .Op \&: Ns Ar provider Ns .Xc and if .Xr netgraph 4 is available, .Nm will attempt talk .Em PPP over Ethernet to .Ar provider using the .Ar iface network interface. .Pp On systems that do not support .Xr netgraph 4 , an external program such as .Xr pppoed 8 may be used. .It "Supports IETF draft Predictor-1 (rfc 1978) and DEFLATE (rfc 1979) compression." .Nm supports not only VJ-compression but also Predictor-1 and DEFLATE compression. Normally, a modem has built-in compression (e.g., v42.bis) and the system may receive higher data rates from it as a result of such compression. While this is generally a good thing in most other situations, this higher speed data imposes a penalty on the system by increasing the number of serial interrupts the system has to process in talking to the modem and also increases latency. Unlike VJ-compression, Predictor-1 and DEFLATE compression pre-compresses .Em all network traffic flowing through the link, thus reducing overheads to a minimum. .It Supports Microsoft's IPCP extensions (rfc 1877). Name Server Addresses and NetBIOS Name Server Addresses can be negotiated with clients using the Microsoft .Em PPP stack (i.e., Win95, WinNT) .It Supports Multi-link PPP (rfc 1990) It is possible to configure .Nm to open more than one physical connection to the peer, combining the bandwidth of all links for better throughput. .It Supports MPPE (draft-ietf-pppext-mppe) MPPE is Microsoft Point to Point Encryption scheme. It is possible to configure .Nm to participate in Microsoft's Windows VPN. For now, .Nm can only get encryption keys from CHAP 81 authentication. .Nm must be compiled with DES for MPPE to operate. .It Supports IPV6CP (rfc 2023). An IPv6 connection can be made in addition to or instead of the normal IPv4 connection. .El .Sh PERMISSIONS .Nm is installed as user .Dv root and group .Dv network , with permissions .Dv 04554 . By default, .Nm will not run if the invoking user id is not zero. This may be overridden by using the .Dq allow users command in .Pa /etc/ppp/ppp.conf . When running as a normal user, .Nm switches to user id 0 in order to alter the system routing table, set up system lock files and read the ppp configuration files. All external commands (executed via the "shell" or "!bg" commands) are executed as the user id that invoked .Nm . Refer to the .Sq ID0 logging facility if you are interested in what exactly is done as user id zero. .Sh GETTING STARTED When you first run .Nm you may need to deal with some initial configuration details. .Bl -bullet .It Make sure that your system has a group named .Dq network in the .Pa /etc/group file and that the group contains the names of all users expected to use .Nm . Refer to the .Xr group 5 manual page for details. Each of these users must also be given access using the .Dq allow users command in .Pa /etc/ppp/ppp.conf . .It Create a log file. .Nm uses .Xr syslog 3 to log information. A common log file name is .Pa /var/log/ppp.log . To make output go to this file, put the following lines in the .Pa /etc/syslog.conf file: .Bd -literal -offset indent !ppp *.*/var/log/ppp.log .Ed .Pp It is possible to have more than one .Em PPP log file by creating a link to the .Nm executable: .Pp .Dl # cd /usr/sbin .Dl # ln ppp ppp0 .Pp and using .Bd -literal -offset indent !ppp0 *.*/var/log/ppp0.log .Ed .Pp in .Pa /etc/syslog.conf . Do not forget to send a .Dv HUP signal to .Xr syslogd 8 after altering .Pa /etc/syslog.conf . .It Although not strictly relevant to .Nm Ns No 's operation, you should configure your resolver so that it works correctly. -This can be done by configuring a local DNS -(using -.Xr named 8 ) -or by adding the correct +This can be done by configuring a local DNS resolver or by adding the correct .Sq nameserver lines to the file .Pa /etc/resolv.conf . Refer to the .Xr resolv.conf 5 manual page for details. .Pp Alternatively, if the peer supports it, .Nm can be configured to ask the peer for the nameserver address(es) and to update .Pa /etc/resolv.conf automatically. Refer to the .Dq enable dns and .Dq resolv commands below for details. .El .Sh MANUAL DIALING In the following examples, we assume that your machine name is .Dv awfulhak . when you invoke .Nm (see .Sx PERMISSIONS above) with no arguments, you are presented with a prompt: .Bd -literal -offset indent ppp ON awfulhak> .Ed .Pp The .Sq ON part of your prompt should always be in upper case. If it is in lower case, it means that you must supply a password using the .Dq passwd command. This only ever happens if you connect to a running version of .Nm and have not authenticated yourself using the correct password. .Pp You can start by specifying the device name and speed: .Bd -literal -offset indent ppp ON awfulhak> set device /dev/cuau0 ppp ON awfulhak> set speed 38400 .Ed .Pp Normally, hardware flow control (CTS/RTS) is used. However, under certain circumstances (as may happen when you are connected directly to certain PPP-capable terminal servers), this may result in .Nm hanging as soon as it tries to write data to your communications link as it is waiting for the CTS (clear to send) signal - which will never come. Thus, if you have a direct line and cannot seem to make a connection, try turning CTS/RTS off with .Dq set ctsrts off . If you need to do this, check the .Dq set accmap description below too - you will probably need to .Dq set accmap 000a0000 . .Pp Usually, parity is set to .Dq none , and this is .Nm Ns No 's default. Parity is a rather archaic error checking mechanism that is no longer used because modern modems do their own error checking, and most link-layer protocols (that is what .Nm is) use much more reliable checking mechanisms. Parity has a relatively huge overhead (a 12.5% increase in traffic) and as a result, it is always disabled (set to .Dq none ) when .Dv PPP is opened. However, some ISPs (Internet Service Providers) may use specific parity settings at connection time (before .Dv PPP is opened). Notably, Compuserve insist on even parity when logging in: .Bd -literal -offset indent ppp ON awfulhak> set parity even .Ed .Pp You can now see what your current device settings look like: .Bd -literal -offset indent ppp ON awfulhak> show physical Name: deflink State: closed Device: N/A Link Type: interactive Connect Count: 0 Queued Packets: 0 Phone Number: N/A Defaults: Device List: /dev/cuau0 Characteristics: 38400bps, cs8, even parity, CTS/RTS on Connect time: 0 secs 0 octets in, 0 octets out Overall 0 bytes/sec ppp ON awfulhak> .Ed .Pp The term command can now be used to talk directly to the device: .Bd -literal -offset indent ppp ON awfulhak> term at OK atdt123456 CONNECT login: myispusername Password: myisppassword Protocol: ppp .Ed .Pp When the peer starts to talk in .Em PPP , .Nm detects this automatically and returns to command mode. .Bd -literal -offset indent ppp ON awfulhak> # No link has been established Ppp ON awfulhak> # We've connected & finished LCP PPp ON awfulhak> # We've authenticated PPP ON awfulhak> # We've agreed IP numbers .Ed .Pp If it does not, it is probable that the peer is waiting for your end to start negotiating. To force .Nm to start sending .Em PPP configuration packets to the peer, use the .Dq ~p command to drop out of terminal mode and enter packet mode. .Pp If you never even receive a login prompt, it is quite likely that the peer wants to use PAP or CHAP authentication instead of using Unix-style login/password authentication. To set things up properly, drop back to the prompt and set your authentication name and key, then reconnect: .Bd -literal -offset indent ~. ppp ON awfulhak> set authname myispusername ppp ON awfulhak> set authkey myisppassword ppp ON awfulhak> term at OK atdt123456 CONNECT .Ed .Pp You may need to tell ppp to initiate negotiations with the peer here too: .Bd -literal -offset indent ~p ppp ON awfulhak> # No link has been established Ppp ON awfulhak> # We've connected & finished LCP PPp ON awfulhak> # We've authenticated PPP ON awfulhak> # We've agreed IP numbers .Ed .Pp You are now connected! Note that .Sq PPP in the prompt has changed to capital letters to indicate that you have a peer connection. If only some of the three Ps go uppercase, wait until either everything is uppercase or lowercase. If they revert to lowercase, it means that .Nm could not successfully negotiate with the peer. A good first step for troubleshooting at this point would be to .Bd -literal -offset indent ppp ON awfulhak> set log local phase lcp ipcp .Ed .Pp and try again. Refer to the .Dq set log command description below for further details. If things fail at this point, it is quite important that you turn logging on and try again. It is also important that you note any prompt changes and report them to anyone trying to help you. .Pp When the link is established, the show command can be used to see how things are going: .Bd -literal -offset indent PPP ON awfulhak> show physical * Modem related information is shown here * PPP ON awfulhak> show ccp * CCP (compression) related information is shown here * PPP ON awfulhak> show lcp * LCP (line control) related information is shown here * PPP ON awfulhak> show ipcp * IPCP (IP) related information is shown here * PPP ON awfulhak> show ipv6cp * IPV6CP (IPv6) related information is shown here * PPP ON awfulhak> show link * Link (high level) related information is shown here * PPP ON awfulhak> show bundle * Logical (high level) connection related information is shown here * .Ed .Pp At this point, your machine has a host route to the peer. This means that you can only make a connection with the host on the other side of the link. If you want to add a default route entry (telling your machine to send all packets without another routing entry to the other side of the .Em PPP link), enter the following command: .Bd -literal -offset indent PPP ON awfulhak> add default HISADDR .Ed .Pp The string .Sq HISADDR represents the IP address of the connected peer. If the .Dq add command fails due to an existing route, you can overwrite the existing route using: .Bd -literal -offset indent PPP ON awfulhak> add! default HISADDR .Ed .Pp This command can also be executed before actually making the connection. If a new IP address is negotiated at connection time, .Nm will update your default route accordingly. .Pp You can now use your network applications (ping, telnet, ftp, etc.) in other windows or terminals on your machine. If you wish to reuse the current terminal, you can put .Nm into the background using your standard shell suspend and background commands (usually .Dq ^Z followed by .Dq bg ) . .Pp Refer to the .Sx PPP COMMAND LIST section for details on all available commands. .Sh AUTOMATIC DIALING To use automatic dialing, you must prepare some Dial and Login chat scripts. See the example definitions in .Pa /usr/share/examples/ppp/ppp.conf.sample (the format of .Pa /etc/ppp/ppp.conf is pretty simple). Each line contains one comment, inclusion, label or command: .Bl -bullet .It A line starting with a .Pq Dq # character is treated as a comment line. Leading whitespace are ignored when identifying comment lines. .It An inclusion is a line beginning with the word .Sq {!include} . It must have one argument - the file to {include}. You may wish to .Dq {!include} ~/.ppp.conf for compatibility with older versions of .Nm . .It A label name starts in the first column and is followed by a colon .Pq Dq \&: . .It A command line must contain a space or tab in the first column. .It A string starting with the .Dq $ character is substituted with the value of the environment variable by the same name. Likewise, a string starting with the .Dq ~ character is substituted with the full path to the home directory of the user account by the same name, and the .Dq ~ character by itself is substituted with the full path to the home directory of the current user. If you want to include a literal .Dq $ or .Dq ~ character in a command or argument, enclose them in double quotes, e.g., .Bd -literal -offset indent set password "pa$ss~word" .Ed .El .Pp The .Pa /etc/ppp/ppp.conf file should consist of at least a .Dq default section. This section is always executed. It should also contain one or more sections, named according to their purpose, for example, .Dq MyISP would represent your ISP, and .Dq ppp-in would represent an incoming .Nm configuration. You can now specify the destination label name when you invoke .Nm . Commands associated with the .Dq default label are executed, followed by those associated with the destination label provided. When .Nm is started with no arguments, the .Dq default section is still executed. The load command can be used to manually load a section from the .Pa /etc/ppp/ppp.conf file: .Bd -literal -offset indent ppp ON awfulhak> load MyISP .Ed .Pp Note, no action is taken by .Nm after a section is loaded, whether it is the result of passing a label on the command line or using the .Dq load command. Only the commands specified for that label in the configuration file are executed. However, when invoking .Nm with the .Fl background , .Fl ddial , or .Fl dedicated switches, the link mode tells .Nm to establish a connection. Refer to the .Dq set mode command below for further details. .Pp Once the connection is made, the .Sq ppp portion of the prompt will change to .Sq PPP : .Bd -literal -offset indent # ppp MyISP \&... ppp ON awfulhak> dial Ppp ON awfulhak> PPp ON awfulhak> PPP ON awfulhak> .Ed .Pp The Ppp prompt indicates that .Nm has entered the authentication phase. The PPp prompt indicates that .Nm has entered the network phase. The PPP prompt indicates that .Nm has successfully negotiated a network layer protocol and is in a usable state. .Pp If the .Pa /etc/ppp/ppp.linkup file is available, its contents are executed when the .Em PPP connection is established. See the provided .Dq pmdemand example in .Pa /usr/share/examples/ppp/ppp.conf.sample which runs a script in the background after the connection is established (refer to the .Dq shell and .Dq bg commands below for a description of possible substitution strings). Similarly, when a connection is closed, the contents of the .Pa /etc/ppp/ppp.linkdown file are executed. Both of these files have the same format as .Pa /etc/ppp/ppp.conf . .Pp In previous versions of .Nm , it was necessary to re-add routes such as the default route in the .Pa ppp.linkup file. .Nm supports .Sq sticky routes , where all routes that contain the .Dv HISADDR , .Dv MYADDR , .Dv HISADDR6 or .Dv MYADDR6 literals will automatically be updated when the values of these variables change. .Sh BACKGROUND DIALING If you want to establish a connection using .Nm non-interactively (such as from a .Xr crontab 5 entry or an .Xr at 1 job) you should use the .Fl background option. When .Fl background is specified, .Nm attempts to establish the connection immediately. If multiple phone numbers are specified, each phone number will be tried once. If the attempt fails, .Nm exits immediately with a non-zero exit code. If it succeeds, then .Nm becomes a daemon, and returns an exit status of zero to its caller. The daemon exits automatically if the connection is dropped by the remote system, or it receives a .Dv TERM signal. .Sh DIAL ON DEMAND Demand dialing is enabled with the .Fl auto or .Fl ddial options. You must also specify the destination label in .Pa /etc/ppp/ppp.conf to use. It must contain the .Dq set ifaddr command to {define} the remote peers IP address. (refer to .Pa /usr/share/examples/ppp/ppp.conf.sample ) .Bd -literal -offset indent # ppp -auto pmdemand .Ed .Pp When .Fl auto or .Fl ddial is specified, .Nm runs as a daemon but you can still configure or examine its configuration by using the .Dq set server command in .Pa /etc/ppp/ppp.conf , (for example, .Dq Li "set server +3000 mypasswd" ) and connecting to the diagnostic port as follows: .Bd -literal -offset indent # pppctl 3000 (assuming tun0) Password: PPP ON awfulhak> show who tcp (127.0.0.1:1028) * .Ed .Pp The .Dq show who command lists users that are currently connected to .Nm itself. If the diagnostic socket is closed or changed to a different socket, all connections are immediately dropped. .Pp In .Fl auto mode, when an outgoing packet is detected, .Nm will perform the dialing action (chat script) and try to connect with the peer. In .Fl ddial mode, the dialing action is performed any time the line is found to be down. If the connect fails, the default behaviour is to wait 30 seconds and then attempt to connect when another outgoing packet is detected. This behaviour can be changed using the .Dq set redial command: .Pp .No set redial Ar secs Ns .Oo + Ns Ar inc Ns .Oo - Ns Ar max Ns Oc Oc Ns .Op . Ns Ar next .Op Ar attempts .Pp .Bl -tag -width attempts -compact .It Ar secs is the number of seconds to wait before attempting to connect again. If the argument is the literal string .Sq Li random , the delay period is a random value between 1 and 30 seconds inclusive. .It Ar inc is the number of seconds that .Ar secs should be incremented each time a new dial attempt is made. The timeout reverts to .Ar secs only after a successful connection is established. The default value for .Ar inc is zero. .It Ar max is the maximum number of times .Nm should increment .Ar secs . The default value for .Ar max is 10. .It Ar next is the number of seconds to wait before attempting to dial the next number in a list of numbers (see the .Dq set phone command). The default is 3 seconds. Again, if the argument is the literal string .Sq Li random , the delay period is a random value between 1 and 30 seconds. .It Ar attempts is the maximum number of times to try to connect for each outgoing packet that triggers a dial. The previous value is unchanged if this parameter is omitted. If a value of zero is specified for .Ar attempts , .Nm will keep trying until a connection is made. .El .Pp So, for example: .Bd -literal -offset indent set redial 10.3 4 .Ed .Pp will attempt to connect 4 times for each outgoing packet that causes a dial attempt with a 3 second delay between each number and a 10 second delay after all numbers have been tried. If multiple phone numbers are specified, the total number of attempts is still 4 (it does not attempt each number 4 times). .Pp Alternatively, .Bd -literal -offset indent set redial 10+10-5.3 20 .Ed .Pp tells .Nm to attempt to connect 20 times. After the first attempt, .Nm pauses for 10 seconds. After the next attempt it pauses for 20 seconds and so on until after the sixth attempt it pauses for 1 minute. The next 14 pauses will also have a duration of one minute. If .Nm connects, disconnects and fails to connect again, the timeout starts again at 10 seconds. .Pp Modifying the dial delay is very useful when running .Nm in .Fl auto mode on both ends of the link. If each end has the same timeout, both ends wind up calling each other at the same time if the link drops and both ends have packets queued. At some locations, the serial link may not be reliable, and carrier may be lost at inappropriate times. It is possible to have .Nm redial should carrier be unexpectedly lost during a session. .Bd -literal -offset indent set reconnect timeout ntries .Ed .Pp This command tells .Nm to re-establish the connection .Ar ntries times on loss of carrier with a pause of .Ar timeout seconds before each try. For example, .Bd -literal -offset indent set reconnect 3 5 .Ed .Pp tells .Nm that on an unexpected loss of carrier, it should wait .Ar 3 seconds before attempting to reconnect. This may happen up to .Ar 5 times before .Nm gives up. The default value of ntries is zero (no reconnect). Care should be taken with this option. If the local timeout is slightly longer than the remote timeout, the reconnect feature will always be triggered (up to the given number of times) after the remote side times out and hangs up. NOTE: In this context, losing too many LQRs constitutes a loss of carrier and will trigger a reconnect. If the .Fl background flag is specified, all phone numbers are dialed at most once until a connection is made. The next number redial period specified with the .Dq set redial command is honoured, as is the reconnect tries value. If your redial value is less than the number of phone numbers specified, not all the specified numbers will be tried. To terminate the program, type .Bd -literal -offset indent PPP ON awfulhak> close ppp ON awfulhak> quit all .Ed .Pp A simple .Dq quit command will terminate the .Xr pppctl 8 or .Xr telnet 1 connection but not the .Nm program itself. You must use .Dq quit all to terminate .Nm as well. .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 1) To handle an incoming .Em PPP connection request, follow these steps: .Bl -enum .It Make sure the modem and (optionally) .Pa /etc/rc.serial is configured correctly. .Bl -bullet -compact .It Use Hardware Handshake (CTS/RTS) for flow control. .It Modem should be set to NO echo back (ATE0) and NO results string (ATQ1). .El .It Edit .Pa /etc/ttys to enable a .Xr getty 8 on the port where the modem is attached. For example: .Pp .Dl ttyd1 Qo /usr/libexec/getty std.38400 Qc dialup on secure .Pp Do not forget to send a .Dv HUP signal to the .Xr init 8 process to start the .Xr getty 8 : .Pp .Dl # kill -HUP 1 .Pp It is usually also necessary to train your modem to the same DTR speed as the getty: .Bd -literal -offset indent # ppp ppp ON awfulhak> set device /dev/cuau1 ppp ON awfulhak> set speed 38400 ppp ON awfulhak> term deflink: Entering terminal mode on /dev/cuau1 Type `~?' for help at OK at OK atz OK at OK ~. ppp ON awfulhak> quit .Ed .It Create a .Pa /usr/local/bin/ppplogin file with the following contents: .Bd -literal -offset indent #! /bin/sh exec /usr/sbin/ppp -direct incoming .Ed .Pp Direct mode .Pq Fl direct lets .Nm work with stdin and stdout. You can also use .Xr pppctl 8 to connect to a configured diagnostic port, in the same manner as with client-side .Nm . .Pp Here, the .Ar incoming section must be set up in .Pa /etc/ppp/ppp.conf . .Pp Make sure that the .Ar incoming section contains the .Dq allow users command as appropriate. .It Prepare an account for the incoming user. .Bd -literal ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin .Ed .Pp Refer to the manual entries for .Xr adduser 8 and .Xr vipw 8 for details. .It Support for IPCP Domain Name Server and NetBIOS Name Server negotiation can be enabled using the .Dq accept dns and .Dq set nbns commands. Refer to their descriptions below. .El .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 2) This method differs in that we use .Nm to authenticate the connection rather than .Xr login 1 : .Bl -enum .It Configure your default section in .Pa /etc/gettytab with automatic ppp recognition by specifying the .Dq pp capability: .Bd -literal default:\\ :pp=/usr/local/bin/ppplogin:\\ ..... .Ed .It Configure your serial device(s), enable a .Xr getty 8 and create .Pa /usr/local/bin/ppplogin as in the first three steps for method 1 above. .It Add either .Dq enable chap or .Dq enable pap (or both) to .Pa /etc/ppp/ppp.conf under the .Sq incoming label (or whatever label .Pa ppplogin uses). .It Create an entry in .Pa /etc/ppp/ppp.secret for each incoming user: .Bd -literal Pfredxxxx Pgeorgeyyyy .Ed .El .Pp Now, as soon as .Xr getty 8 detects a ppp connection (by recognising the HDLC frame headers), it runs .Dq /usr/local/bin/ppplogin . .Pp It is .Em VITAL that either PAP or CHAP are enabled as above. If they are not, you are allowing anybody to establish a ppp session with your machine .Em without a password, opening yourself up to all sorts of potential attacks. .Sh AUTHENTICATING INCOMING CONNECTIONS Normally, the receiver of a connection requires that the peer authenticates itself. This may be done using .Xr login 1 , but alternatively, you can use PAP or CHAP. CHAP is the more secure of the two, but some clients may not support it. Once you decide which you wish to use, add the command .Sq enable chap or .Sq enable pap to the relevant section of .Pa ppp.conf . .Pp You must then configure the .Pa /etc/ppp/ppp.secret file. This file contains one line per possible client, each line containing up to five fields: .Pp .Ar name Ar key Oo .Ar hisaddr Op Ar label Op Ar callback-number .Oc .Pp The .Ar name and .Ar key specify the client username and password. If .Ar key is .Dq \&* and PAP is being used, .Nm will look up the password database .Pq Xr passwd 5 when authenticating. If the client does not offer a suitable response based on any .Ar name Ns No / Ns Ar key combination in .Pa ppp.secret , authentication fails. .Pp If authentication is successful, .Ar hisaddr (if specified) is used when negotiating IP numbers. See the .Dq set ifaddr command for details. .Pp If authentication is successful and .Ar label is specified, the current system label is changed to match the given .Ar label . This will change the subsequent parsing of the .Pa ppp.linkup and .Pa ppp.linkdown files. .Pp If authentication is successful and .Ar callback-number is specified and .Dq set callback has been used in .Pa ppp.conf , the client will be called back on the given number. If CBCP is being used, .Ar callback-number may also contain a list of numbers or a .Dq \&* , as if passed to the .Dq set cbcp command. The value will be used in .Nm Ns No 's subsequent CBCP phase. .Sh PPP OVER TCP and UDP (a.k.a Tunnelling) Instead of running .Nm over a serial link, it is possible to use a TCP connection instead by specifying the host, port and protocol as the device: .Pp .Dl set device ui-gate:6669/tcp .Pp Instead of opening a serial device, .Nm will open a TCP connection to the given machine on the given socket. It should be noted however that .Nm does not use the telnet protocol and will be unable to negotiate with a telnet server. You should set up a port for receiving this .Em PPP connection on the receiving machine (ui-gate). This is done by first updating .Pa /etc/services to name the service: .Pp .Dl ppp-in 6669/tcp # Incoming PPP connections over TCP .Pp and updating .Pa /etc/inetd.conf to tell .Xr inetd 8 how to deal with incoming connections on that port: .Pp .Dl ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in .Pp Do not forget to send a .Dv HUP signal to .Xr inetd 8 after you have updated .Pa /etc/inetd.conf . Here, we use a label named .Dq ppp-in . The entry in .Pa /etc/ppp/ppp.conf on ui-gate (the receiver) should contain the following: .Bd -literal -offset indent ppp-in: set timeout 0 set ifaddr 10.0.4.1 10.0.4.2 .Ed .Pp and the entry in .Pa /etc/ppp/ppp.linkup should contain: .Bd -literal -offset indent ppp-in: add 10.0.1.0/24 HISADDR .Ed .Pp It is necessary to put the .Dq add command in .Pa ppp.linkup to ensure that the route is only added after .Nm has negotiated and assigned addresses to its interface. .Pp You may also want to enable PAP or CHAP for security. To enable PAP, add the following line: .Bd -literal -offset indent enable PAP .Ed .Pp You will also need to create the following entry in .Pa /etc/ppp/ppp.secret : .Bd -literal -offset indent MyAuthName MyAuthPasswd .Ed .Pp If .Ar MyAuthPasswd is a .Dq * , the password is looked up in the .Xr passwd 5 database. .Pp The entry in .Pa /etc/ppp/ppp.conf on awfulhak (the initiator) should contain the following: .Bd -literal -offset indent ui-gate: set escape 0xff set device ui-gate:ppp-in/tcp set dial set timeout 30 set log Phase Chat Connect hdlc LCP IPCP IPV6CP CCP tun set ifaddr 10.0.4.2 10.0.4.1 .Ed .Pp with the route setup in .Pa /etc/ppp/ppp.linkup : .Bd -literal -offset indent ui-gate: add 10.0.2.0/24 HISADDR .Ed .Pp Again, if you are enabling PAP, you will also need this in the .Pa /etc/ppp/ppp.conf profile: .Bd -literal -offset indent set authname MyAuthName set authkey MyAuthKey .Ed .Pp We are assigning the address of 10.0.4.1 to ui-gate, and the address 10.0.4.2 to awfulhak. To open the connection, just type .Pp .Dl awfulhak # ppp -background ui-gate .Pp The result will be an additional "route" on awfulhak to the 10.0.2.0/24 network via the TCP connection, and an additional "route" on ui-gate to the 10.0.1.0/24 network. The networks are effectively bridged - the underlying TCP connection may be across a public network (such as the Internet), and the .Em PPP traffic is conceptually encapsulated (although not packet by packet) inside the TCP stream between the two gateways. .Pp The major disadvantage of this mechanism is that there are two "guaranteed delivery" mechanisms in place - the underlying TCP stream and whatever protocol is used over the .Em PPP link - probably TCP again. If packets are lost, both levels will get in each others way trying to negotiate sending of the missing packet. .Pp To avoid this overhead, it is also possible to do all this using UDP instead of TCP as the transport by simply changing the protocol from "tcp" to "udp". When using UDP as a transport, .Nm will operate in synchronous mode. This is another gain as the incoming data does not have to be rearranged into packets. .Pp Care should be taken when adding a default route through a tunneled setup like this. It is quite common for the default route (added in .Pa /etc/ppp/ppp.linkup ) to end up routing the link's TCP connection through the tunnel, effectively garrotting the connection. To avoid this, make sure you add a static route for the benefit of the link: .Bd -literal -offset indent ui-gate: set escape 0xff set device ui-gate:ppp-in/tcp add ui-gate x.x.x.x ..... .Ed .Pp where .Dq x.x.x.x is the IP number that your route to .Dq ui-gate would normally use. .Pp When routing your connection across a public network such as the Internet, it is preferable to encrypt the data. This can be done with the help of the MPPE protocol, although currently this means that you will not be able to also compress the traffic as MPPE is implemented as a compression layer (thank Microsoft for this). To enable MPPE encryption, add the following lines to .Pa /etc/ppp/ppp.conf on the server: .Bd -literal -offset indent enable MSCHAPv2 disable deflate pred1 deny deflate pred1 .Ed .Pp ensuring that you have put the requisite entry in .Pa /etc/ppp/ppp.secret (MSCHAPv2 is challenge based, so .Xr passwd 5 cannot be used) .Pp MSCHAPv2 and MPPE are accepted by default, so the client end should work without any additional changes (although ensure you have .Dq set authname and .Dq set authkey in your profile). .Sh NETWORK ADDRESS TRANSLATION (PACKET ALIASING) The .Fl nat command line option enables network address translation (a.k.a.\& packet aliasing). This allows the .Nm host to act as a masquerading gateway for other computers over a local area network. Outgoing IP packets are NAT'd so that they appear to come from the .Nm host, and incoming packets are de-NAT'd so that they are routed to the correct machine on the local area network. NAT allows computers on private, unregistered subnets to have Internet access, although they are invisible from the outside world. In general, correct .Nm operation should first be verified with network address translation disabled. Then, the .Fl nat option should be switched on, and network applications (web browser, .Xr telnet 1 , .Xr ftp 1 , .Xr ping 8 , .Xr traceroute 8 ) should be checked on the .Nm host. Finally, the same or similar applications should be checked on other computers in the LAN. If network applications work correctly on the .Nm host, but not on other machines in the LAN, then the masquerading software is working properly, but the host is either not forwarding or possibly receiving IP packets. Check that IP forwarding is enabled in .Pa /etc/rc.conf and that other machines have designated the .Nm host as the gateway for the LAN. When starting .Nm with the provided rc script, the default is to enable NAT; see .Va ppp_nat in .Xr rc.conf 5 and .Pa /etc/defaults/rc.conf . .Sh PACKET FILTERING This implementation supports packet filtering. There are four kinds of filters: the .Em in filter, the .Em out filter, the .Em dial filter and the .Em alive filter. Here are the basics: .Bl -bullet .It A filter definition has the following syntax: .Pp set filter .Ar name .Ar rule-no .Ar action .Op !\& .Oo .Op host .Ar src_addr Ns Op / Ns Ar width .Op Ar dst_addr Ns Op / Ns Ar width .Oc .Ar [ proto Op src Ar cmp port .Op dst Ar cmp port .Op estab .Op syn .Op finrst .Op timeout Ar secs ] .Bl -enum .It .Ar Name should be one of .Sq in , .Sq out , .Sq dial or .Sq alive . .It .Ar Rule-no is a numeric value between .Sq 0 and .Sq 39 specifying the rule number. Rules are specified in numeric order according to .Ar rule-no , but only if rule .Sq 0 is defined. .It .Ar Action may be specified as .Sq permit or .Sq deny , in which case, if a given packet matches the rule, the associated action is taken immediately. .Ar Action can also be specified as .Sq clear to clear the action associated with that particular rule, or as a new rule number greater than the current rule. In this case, if a given packet matches the current rule, the packet will next be matched against the new rule number (rather than the next rule number). .Pp The .Ar action may optionally be followed with an exclamation mark .Pq Dq !\& , telling .Nm to reverse the sense of the following match. .It .Op Ar src_addr Ns Op / Ns Ar width and .Op Ar dst_addr Ns Op / Ns Ar width are the source and destination IP number specifications. If .Op / Ns Ar width is specified, it gives the number of relevant netmask bits, allowing the specification of an address range. .Pp Either .Ar src_addr or .Ar dst_addr may be given the values .Dv MYADDR , .Dv HISADDR , .Dv MYADDR6 or .Dv HISADDR6 (refer to the description of the .Dq bg command for a description of these values). When these values are used, the filters will be updated any time the values change. This is similar to the behaviour of the .Dq add command below. .It .Ar Proto may be any protocol from .Xr protocols 5 . .It .Ar Cmp is one of .Sq \< , .Sq \&eq or .Sq \> , meaning less-than, equal and greater-than respectively. .Ar Port can be specified as a numeric port or by service name from .Pa /etc/services . .It The .Sq estab , .Sq syn , and .Sq finrst flags are only allowed when .Ar proto is set to .Sq tcp , and represent the TH_ACK, TH_SYN and TH_FIN or TH_RST TCP flags respectively. .It The timeout value adjusts the current idle timeout to at least .Ar secs seconds. If a timeout is given in the alive filter as well as in the in/out filter, the in/out value is used. If no timeout is given, the default timeout (set using .Ic set timeout and defaulting to 180 seconds) is used. .El .It Each filter can hold up to 40 rules, starting from rule 0. The entire rule set is not effective until rule 0 is defined, i.e., the default is to allow everything through. .It If no rule in a defined set of rules matches a packet, that packet will be discarded (blocked). If there are no rules in a given filter, the packet will be permitted. .It It is possible to filter based on the payload of UDP frames where those frames contain a .Em PROTO_IP .Em PPP frame header. See the .Ar filter-decapsulation option below for further details. .It Use .Dq set filter Ar name No -1 to flush all rules. .El .Pp See .Pa /usr/share/examples/ppp/ppp.conf.sample . .Sh SETTING THE IDLE TIMER To check/set the idle timer, use the .Dq show bundle and .Dq set timeout commands: .Bd -literal -offset indent ppp ON awfulhak> set timeout 600 .Ed .Pp The timeout period is measured in seconds, the default value for which is 180 seconds (or 3 min). To disable the idle timer function, use the command .Bd -literal -offset indent ppp ON awfulhak> set timeout 0 .Ed .Pp In .Fl ddial and .Fl dedicated modes, the idle timeout is ignored. In .Fl auto mode, when the idle timeout causes the .Em PPP session to be closed, the .Nm program itself remains running. Another trigger packet will cause it to attempt to re-establish the link. .Sh PREDICTOR-1 and DEFLATE COMPRESSION .Nm supports both Predictor type 1 and deflate compression. By default, .Nm will attempt to use (or be willing to accept) both compression protocols when the peer agrees (or requests them). The deflate protocol is preferred by .Nm . Refer to the .Dq disable and .Dq deny commands if you wish to disable this functionality. .Pp It is possible to use a different compression algorithm in each direction by using only one of .Dq disable deflate and .Dq deny deflate (assuming that the peer supports both algorithms). .Pp By default, when negotiating DEFLATE, .Nm will use a window size of 15. Refer to the .Dq set deflate command if you wish to change this behaviour. .Pp A special algorithm called DEFLATE24 is also available, and is disabled and denied by default. This is exactly the same as DEFLATE except that it uses CCP ID 24 to negotiate. This allows .Nm to successfully negotiate DEFLATE with .Nm pppd version 2.3.*. .Sh CONTROLLING IP ADDRESS For IPv4, .Nm uses IPCP to negotiate IP addresses. Each side of the connection specifies the IP address that it is willing to use, and if the requested IP address is acceptable then .Nm returns an ACK to the requester. Otherwise, .Nm returns NAK to suggest that the peer use a different IP address. When both sides of the connection agree to accept the received request (and send an ACK), IPCP is set to the open state and a network level connection is established. To control this IPCP behaviour, this implementation has the .Dq set ifaddr command for defining the local and remote IP address: .Bd -ragged -offset indent .No set ifaddr Oo Ar src_addr Ns .Op / Ns Ar \&nn .Oo Ar dst_addr Ns Op / Ns Ar \&nn .Oo Ar netmask .Op Ar trigger_addr .Oc .Oc .Oc .Ed .Pp where, .Sq src_addr is the IP address that the local side is willing to use, .Sq dst_addr is the IP address which the remote side should use and .Sq netmask is the netmask that should be used. .Sq Src_addr defaults to the current .Xr hostname 1 , .Sq dst_addr defaults to 0.0.0.0, and .Sq netmask defaults to whatever mask is appropriate for .Sq src_addr . It is only possible to make .Sq netmask smaller than the default. The usual value is 255.255.255.255, as most kernels ignore the netmask of a POINTOPOINT interface. .Pp Some incorrect .Em PPP implementations require that the peer negotiates a specific IP address instead of .Sq src_addr . If this is the case, .Sq trigger_addr may be used to specify this IP number. This will not affect the routing table unless the other side agrees with this proposed number. .Bd -literal -offset indent set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0 .Ed .Pp The above specification means: .Pp .Bl -bullet -compact .It I will first suggest that my IP address should be 0.0.0.0, but I will only accept an address of 192.244.177.38. .It I strongly insist that the peer uses 192.244.177.2 as his own address and will not permit the use of any IP address but 192.244.177.2. When the peer requests another IP address, I will always suggest that it uses 192.244.177.2. .It The routing table entry will have a netmask of 0xffffffff. .El .Pp This is all fine when each side has a pre-determined IP address, however it is often the case that one side is acting as a server which controls all IP addresses and the other side should go along with it. In order to allow more flexible behaviour, the .Dq set ifaddr command allows the user to specify IP addresses more loosely: .Pp .Dl set ifaddr 192.244.177.38/24 192.244.177.2/20 .Pp A number followed by a slash .Pq Dq / represents the number of bits significant in the IP address. The above example means: .Pp .Bl -bullet -compact .It I would like to use 192.244.177.38 as my address if it is possible, but I will also accept any IP address between 192.244.177.0 and 192.244.177.255. .It I would like to make him use 192.244.177.2 as his own address, but I will also permit him to use any IP address between 192.244.176.0 and 192.244.191.255. .It As you may have already noticed, 192.244.177.2 is equivalent to saying 192.244.177.2/32. .It As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no preferred IP address and will obey the remote peers selection. When using zero, no routing table entries will be made until a connection is established. .It 192.244.177.2/0 means that I will accept/permit any IP address but I will suggest that 192.244.177.2 be used first. .El .Pp When negotiating IPv6 addresses, no control is given to the user. IPV6CP negotiation is fully automatic. .Sh CONNECTING WITH YOUR INTERNET SERVICE PROVIDER The following steps should be taken when connecting to your ISP: .Bl -enum .It Describe your providers phone number(s) in the dial script using the .Dq set phone command. This command allows you to set multiple phone numbers for dialing and redialing separated by either a pipe .Pq Dq \&| or a colon .Pq Dq \&: : .Bd -ragged -offset indent .No set phone Ar telno Ns .Oo \&| Ns Ar backupnumber Oc Ns ... Ns Oo : Ns Ar nextnumber Oc Ns ... .Ed .Pp Numbers after the first in a pipe-separated list are only used if the previous number was used in a failed dial or login script. Numbers separated by a colon are used sequentially, irrespective of what happened as a result of using the previous number. For example: .Bd -literal -offset indent set phone "1234567|2345678:3456789|4567890" .Ed .Pp Here, the 1234567 number is attempted. If the dial or login script fails, the 2345678 number is used next time, but *only* if the dial or login script fails. On the dial after this, the 3456789 number is used. The 4567890 number is only used if the dial or login script using the 3456789 fails. If the login script of the 2345678 number fails, the next number is still the 3456789 number. As many pipes and colons can be used as are necessary (although a given site would usually prefer to use either the pipe or the colon, but not both). The next number redial timeout is used between all numbers. When the end of the list is reached, the normal redial period is used before starting at the beginning again. The selected phone number is substituted for the \\\\T string in the .Dq set dial command (see below). .It Set up your redial requirements using .Dq set redial . For example, if you have a bad telephone line or your provider is usually engaged (not so common these days), you may want to specify the following: .Bd -literal -offset indent set redial 10 4 .Ed .Pp This says that up to 4 phone calls should be attempted with a pause of 10 seconds before dialing the first number again. .It Describe your login procedure using the .Dq set dial and .Dq set login commands. The .Dq set dial command is used to talk to your modem and establish a link with your ISP, for example: .Bd -literal -offset indent set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 4 \\"\\" \e ATZ OK-ATZ-OK ATDT\\\\T TIMEOUT 60 CONNECT" .Ed .Pp This modem "chat" string means: .Bl -bullet .It Abort if the string "BUSY" or "NO CARRIER" are received. .It Set the timeout to 4 seconds. .It Expect nothing. .It Send ATZ. .It Expect OK. If that is not received within the 4 second timeout, send ATZ and expect OK. .It Send ATDTxxxxxxx where xxxxxxx is the next number in the phone list from above. .It Set the timeout to 60. .It Wait for the CONNECT string. .El .Pp Once the connection is established, the login script is executed. This script is written in the same style as the dial script, but care should be taken to avoid having your password logged: .Bd -literal -offset indent set authkey MySecret set login "TIMEOUT 15 login:-\\\\r-login: awfulhak \e word: \\\\P ocol: PPP HELLO" .Ed .Pp This login "chat" string means: .Bl -bullet .It Set the timeout to 15 seconds. .It Expect "login:". If it is not received, send a carriage return and expect "login:" again. .It Send "awfulhak" .It Expect "word:" (the tail end of a "Password:" prompt). .It Send whatever our current .Ar authkey value is set to. .It Expect "ocol:" (the tail end of a "Protocol:" prompt). .It Send "PPP". .It Expect "HELLO". .El .Pp The .Dq set authkey command is logged specially. When .Ar command or .Ar chat logging is enabled, the actual password is not logged; .Sq ******** is logged instead. .Pp Login scripts vary greatly between ISPs. If you are setting one up for the first time, .Em ENABLE CHAT LOGGING so that you can see if your script is behaving as you expect. .It Use .Dq set device and .Dq set speed to specify your serial line and speed, for example: .Bd -literal -offset indent set device /dev/cuau0 set speed 115200 .Ed .Pp Cuad0 is the first serial port on .Fx . If you are running .Nm on .Ox , cua00 is the first. A speed of 115200 should be specified if you have a modem capable of bit rates of 28800 or more. In general, the serial speed should be about four times the modem speed. .It Use the .Dq set ifaddr command to {define} the IP address. .Bl -bullet .It If you know what IP address your provider uses, then use it as the remote address (dst_addr), otherwise choose something like 10.0.0.2/0 (see below). .It If your provider has assigned a particular IP address to you, then use it as your address (src_addr). .It If your provider assigns your address dynamically, choose a suitably unobtrusive and unspecific IP number as your address. 10.0.0.1/0 would be appropriate. The bit after the / specifies how many bits of the address you consider to be important, so if you wanted to insist on something in the class C network 1.2.3.0, you could specify 1.2.3.1/24. .It If you find that your ISP accepts the first IP number that you suggest, specify third and forth arguments of .Dq 0.0.0.0 . This will force your ISP to assign a number. (The third argument will be ignored as it is less restrictive than the default mask for your .Sq src_addr ) . .El .Pp An example for a connection where you do not know your IP number or your ISPs IP number would be: .Bd -literal -offset indent set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0 .Ed .It In most cases, your ISP will also be your default router. If this is the case, add the line .Bd -literal -offset indent add default HISADDR .Ed .Pp to .Pa /etc/ppp/ppp.conf (or to .Pa /etc/ppp/ppp.linkup for setups that do not use .Fl auto mode). .Pp This tells .Nm to add a default route to whatever the peer address is (10.0.0.2 in this example). This route is .Sq sticky , meaning that should the value of .Dv HISADDR change, the route will be updated accordingly. .It If your provider requests that you use PAP/CHAP authentication methods, add the next lines to your .Pa /etc/ppp/ppp.conf file: .Bd -literal -offset indent set authname MyName set authkey MyPassword .Ed .Pp Both are accepted by default, so .Nm will provide whatever your ISP requires. .Pp It should be noted that a login script is rarely (if ever) required when PAP or CHAP are in use. .It Ask your ISP to authenticate your nameserver address(es) with the line .Bd -literal -offset indent enable dns .Ed .Pp Do .Em NOT do this if you are running a local DNS unless you also either use .Dq resolv readonly or have .Dq resolv restore in .Pa /etc/ppp/ppp.linkdown , as .Nm will simply circumvent its use by entering some nameserver lines in .Pa /etc/resolv.conf . .El .Pp Please refer to .Pa /usr/share/examples/ppp/ppp.conf.sample and .Pa /usr/share/examples/ppp/ppp.linkup.sample for some real examples. The pmdemand label should be appropriate for most ISPs. .Sh LOGGING FACILITY .Nm is able to generate the following log info either via .Xr syslog 3 or directly to the screen: .Pp .Bl -tag -width XXXXXXXXX -offset XXX -compact .It Li All Enable all logging facilities. This generates a lot of log. The most common use of 'all' is as a basis, where you remove some facilities after enabling 'all' ('debug' and 'timer' are usually best disabled.) .It Li Async Dump async level packet in hex. .It Li CBCP Generate CBCP (CallBack Control Protocol) logs. .It Li CCP Generate a CCP packet trace. .It Li Chat Generate .Sq dial , .Sq login , .Sq logout and .Sq hangup chat script trace logs. .It Li Command Log commands executed either from the command line or any of the configuration files. .It Li Connect Log Chat lines containing the string "CONNECT". .It Li Debug Log debug information. .It Li DNS Log DNS QUERY packets. .It Li Filter Log packets permitted by the dial filter and denied by any filter. .It Li HDLC Dump HDLC packet in hex. .It Li ID0 Log all function calls specifically made as user id 0. .It Li IPCP Generate an IPCP packet trace. .It Li LCP Generate an LCP packet trace. .It Li LQM Generate LQR reports. .It Li Phase Phase transition log output. .It Li Physical Dump physical level packet in hex. .It Li Radius Dump RADIUS information. RADIUS information resulting from the link coming up or down is logged at .Dq Phase level unless .Dq Radius logging is enabled. This log level is most useful for monitoring RADIUS alive information. .It Li Sync Dump sync level packet in hex. .It Li TCP/IP Dump all TCP/IP packets. .It Li Timer Log timer manipulation. .It Li TUN Include the tun device on each log line. .It Li Warning Output to the terminal device. If there is currently no terminal, output is sent to the log file using syslogs .Dv LOG_WARNING . .It Li Error Output to both the terminal device and the log file using syslogs .Dv LOG_ERROR . .It Li Alert Output to the log file using .Dv LOG_ALERT . .El .Pp The .Dq set log command allows you to set the logging output level. Multiple levels can be specified on a single command line. The default is equivalent to .Dq set log Phase . .Pp It is also possible to log directly to the screen. The syntax is the same except that the word .Dq local should immediately follow .Dq set log . The default is .Dq set log local (i.e., only the un-maskable warning, error and alert output). .Pp If The first argument to .Dq set log Op local begins with a .Sq + or a .Sq - character, the current log levels are not cleared, for example: .Bd -literal -offset indent PPP ON awfulhak> set log phase PPP ON awfulhak> show log Log: Phase Warning Error Alert Local: Warning Error Alert PPP ON awfulhak> set log +tcp/ip -warning PPP ON awfulhak> set log local +command PPP ON awfulhak> show log Log: Phase TCP/IP Warning Error Alert Local: Command Warning Error Alert .Ed .Pp Log messages of level Warning, Error and Alert are not controllable using .Dq set log Op local . .Pp The .Ar Warning level is special in that it will not be logged if it can be displayed locally. .Sh SIGNAL HANDLING .Nm deals with the following signals: .Bl -tag -width "USR2" .It INT Receipt of this signal causes the termination of the current connection (if any). This will cause .Nm to exit unless it is in .Fl auto or .Fl ddial mode. .It HUP, TERM & QUIT These signals tell .Nm to exit. .It USR1 This signal, tells .Nm to re-open any existing server socket, dropping all existing diagnostic connections. Sockets that could not previously be opened will be retried. .It USR2 This signal, tells .Nm to close any existing server socket, dropping all existing diagnostic connections. .Dv SIGUSR1 can still be used to re-open the socket. .El .Sh MULTI-LINK PPP If you wish to use more than one physical link to connect to a .Em PPP peer, that peer must also understand the .Em MULTI-LINK PPP protocol. Refer to RFC 1990 for specification details. .Pp The peer is identified using a combination of his .Dq endpoint discriminator and his .Dq authentication id . Either or both of these may be specified. It is recommended that at least one is specified, otherwise there is no way of ensuring that all links are actually connected to the same peer program, and some confusing lock-ups may result. Locally, these identification variables are specified using the .Dq set enddisc and .Dq set authname commands. The .Sq authname (and .Sq authkey ) must be agreed in advance with the peer. .Pp Multi-link capabilities are enabled using the .Dq set mrru command (set maximum reconstructed receive unit). Once multi-link is enabled, .Nm will attempt to negotiate a multi-link connection with the peer. .Pp By default, only one .Sq link is available (called .Sq deflink ) . To create more links, the .Dq clone command is used. This command will clone existing links, where all characteristics are the same except: .Bl -enum .It The new link has its own name as specified on the .Dq clone command line. .It The new link is an .Sq interactive link. Its mode may subsequently be changed using the .Dq set mode command. .It The new link is in a .Sq closed state. .El .Pp A summary of all available links can be seen using the .Dq show links command. .Pp Once a new link has been created, command usage varies. All link specific commands must be prefixed with the .Dq link Ar name command, specifying on which link the command is to be applied. When only a single link is available, .Nm is smart enough not to require the .Dq link Ar name prefix. .Pp Some commands can still be used without specifying a link - resulting in an operation at the .Sq bundle level. For example, once two or more links are available, the command .Dq show ccp will show CCP configuration and statistics at the multi-link level, and .Dq link deflink show ccp will show the same information at the .Dq deflink link level. .Pp Armed with this information, the following configuration might be used: .Bd -literal -offset indent mp: set timeout 0 set log phase chat set device /dev/cuau0 /dev/cuau1 /dev/cuau2 set phone "123456789" set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \\"\\" ATZ \e OK-AT-OK \\\\dATDT\\\\T TIMEOUT 45 CONNECT" set login set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0 set authname ppp set authkey ppppassword set mrru 1500 clone 1,2,3 # Create 3 new links - duplicates of the default link deflink remove # Delete the default link (called ``deflink'') .Ed .Pp Note how all cloning is done at the end of the configuration. Usually, the link will be configured first, then cloned. If you wish all links to be up all the time, you can add the following line to the end of your configuration. .Bd -literal -offset indent link 1,2,3 set mode ddial .Ed .Pp If you want the links to dial on demand, this command could be used: .Bd -literal -offset indent link * set mode auto .Ed .Pp Links may be tied to specific names by removing the .Dq set device line above, and specifying the following after the .Dq clone command: .Bd -literal -offset indent link 1 set device /dev/cuau0 link 2 set device /dev/cuau1 link 3 set device /dev/cuau2 .Ed .Pp Use the .Dq help command to see which commands require context (using the .Dq link command), which have optional context and which should not have any context. .Pp When .Nm has negotiated .Em MULTI-LINK mode with the peer, it creates a local domain socket in the .Pa /var/run directory. This socket is used to pass link information (including the actual link file descriptor) between different .Nm invocations. This facilitates .Nm Ns No 's ability to be run from a .Xr getty 8 or directly from .Pa /etc/gettydefs (using the .Sq pp= capability), without needing to have initial control of the serial line. Once .Nm negotiates multi-link mode, it will pass its open link to any already running process. If there is no already running process, .Nm will act as the master, creating the socket and listening for new connections. .Sh PPP COMMAND LIST This section lists the available commands and their effect. They are usable either from an interactive .Nm session, from a configuration file or from a .Xr pppctl 8 or .Xr telnet 1 session. .Bl -tag -width 2n .It accept|deny|enable|disable Ar option.... These directives tell .Nm how to negotiate the initial connection with the peer. Each .Dq option has a default of either accept or deny and enable or disable. .Dq Accept means that the option will be ACK'd if the peer asks for it. .Dq Deny means that the option will be NAK'd if the peer asks for it. .Dq Enable means that the option will be requested by us. .Dq Disable means that the option will not be requested by us. .Pp .Dq Option may be one of the following: .Bl -tag -width 2n .It acfcomp Default: Enabled and Accepted. ACFComp stands for Address and Control Field Compression. Non LCP packets will usually have an address field of 0xff (the All-Stations address) and a control field of 0x03 (the Unnumbered Information command). If this option is negotiated, these two bytes are simply not sent, thus minimising traffic. .Pp See .Pa rfc1662 for details. .It chap Ns Op \&05 Default: Disabled and Accepted. CHAP stands for Challenge Handshake Authentication Protocol. Only one of CHAP and PAP (below) may be negotiated. With CHAP, the authenticator sends a "challenge" message to its peer. The peer uses a one-way hash function to encrypt the challenge and sends the result back. The authenticator does the same, and compares the results. The advantage of this mechanism is that no passwords are sent across the connection. A challenge is made when the connection is first made. Subsequent challenges may occur. If you want to have your peer authenticate itself, you must .Dq enable chap . in .Pa /etc/ppp/ppp.conf , and have an entry in .Pa /etc/ppp/ppp.secret for the peer. .Pp When using CHAP as the client, you need only specify .Dq AuthName and .Dq AuthKey in .Pa /etc/ppp/ppp.conf . CHAP is accepted by default. Some .Em PPP implementations use "MS-CHAP" rather than MD5 when encrypting the challenge. MS-CHAP is a combination of MD4 and DES. If .Nm was built on a machine with DES libraries available, it will respond to MS-CHAP authentication requests, but will never request them. .It deflate Default: Enabled and Accepted. This option decides if deflate compression will be used by the Compression Control Protocol (CCP). This is the same algorithm as used by the .Xr gzip 1 program. Note: There is a problem negotiating .Ar deflate capabilities with .Nm pppd - a .Em PPP implementation available under many operating systems. .Nm pppd (version 2.3.1) incorrectly attempts to negotiate .Ar deflate compression using type .Em 24 as the CCP configuration type rather than type .Em 26 as specified in .Pa rfc1979 . Type .Ar 24 is actually specified as .Dq PPP Magna-link Variable Resource Compression in .Pa rfc1975 ! .Nm is capable of negotiating with .Nm pppd , but only if .Dq deflate24 is .Ar enable Ns No d and .Ar accept Ns No ed . .It deflate24 Default: Disabled and Denied. This is a variance of the .Ar deflate option, allowing negotiation with the .Nm pppd program. Refer to the .Ar deflate section above for details. It is disabled by default as it violates .Pa rfc1975 . .It dns Default: Disabled and Denied. This option allows DNS negotiation. .Pp If .Dq enable Ns No d, .Nm will request that the peer confirms the entries in .Pa /etc/resolv.conf . If the peer NAKs our request (suggesting new IP numbers), .Pa /etc/resolv.conf is updated and another request is sent to confirm the new entries. .Pp If .Dq accept Ns No ed, .Nm will answer any DNS queries requested by the peer rather than rejecting them. The answer is taken from .Pa /etc/resolv.conf unless the .Dq set dns command is used as an override. .It enddisc Default: Enabled and Accepted. This option allows control over whether we negotiate an endpoint discriminator. We only send our discriminator if .Dq set enddisc is used and .Ar enddisc is enabled. We reject the peers discriminator if .Ar enddisc is denied. .It LANMan|chap80lm Default: Disabled and Accepted. The use of this authentication protocol is discouraged as it partially violates the authentication protocol by implementing two different mechanisms (LANMan & NT) under the guise of a single CHAP type (0x80). .Dq LANMan uses a simple DES encryption mechanism and is the least secure of the CHAP alternatives (although is still more secure than PAP). .Pp Refer to the .Dq MSChap description below for more details. .It lqr Default: Disabled and Accepted. This option decides if Link Quality Requests will be sent or accepted. LQR is a protocol that allows .Nm to determine that the link is down without relying on the modems carrier detect. When LQR is enabled, .Nm sends the .Em QUALPROTO option (see .Dq set lqrperiod below) as part of the LCP request. If the peer agrees, both sides will exchange LQR packets at the agreed frequency, allowing detailed link quality monitoring by enabling LQM logging. If the peer does not agree, and if the .Dq echo option is enabled, .Nm will send .Em LCP ECHO requests instead. These packets pass no information of interest, but they .Em MUST be replied to by the peer. .Pp Whether using .Em LQR or .Em LCP ECHO , .Nm will abruptly drop the connection if 5 unacknowledged packets have been sent rather than sending a 6th. A message is logged at the .Em PHASE level, and any appropriate .Dq reconnect values are honoured as if the peer were responsible for dropping the connection. .Pp Refer to the .Dq enable echo command description for differences in behaviour prior to .Nm version 3.4.2. .It mppe Default: Enabled and Accepted. This is Microsoft Point to Point Encryption scheme. MPPE key size can be 40-, 56- and 128-bits. Refer to .Dq set mppe command. .It MSChapV2|chap81 Default: Disabled and Accepted. It is very similar to standard CHAP (type 0x05) except that it issues challenges of a fixed 16 bytes in length and uses a combination of MD4, SHA-1 and DES to encrypt the challenge rather than using the standard MD5 mechanism. .It MSChap|chap80nt Default: Disabled and Accepted. The use of this authentication protocol is discouraged as it partially violates the authentication protocol by implementing two different mechanisms (LANMan & NT) under the guise of a single CHAP type (0x80). It is very similar to standard CHAP (type 0x05) except that it issues challenges of a fixed 8 bytes in length and uses a combination of MD4 and DES to encrypt the challenge rather than using the standard MD5 mechanism. CHAP type 0x80 for LANMan is also supported - see .Dq enable LANMan for details. .Pp Because both .Dq LANMan and .Dq NT use CHAP type 0x80, when acting as authenticator with both .Dq enable Ns No d , .Nm will rechallenge the peer up to three times if it responds using the wrong one of the two protocols. This gives the peer a chance to attempt using both protocols. .Pp Conversely, when .Nm acts as the authenticatee with both protocols .Dq accept Ns No ed , the protocols are used alternately in response to challenges. .Pp Note: If only LANMan is enabled, .Nm pppd (version 2.3.5) misbehaves when acting as authenticatee. It provides both the NT and the LANMan answers, but also suggests that only the NT answer should be used. .It pap Default: Disabled and Accepted. PAP stands for Password Authentication Protocol. Only one of PAP and CHAP (above) may be negotiated. With PAP, the ID and Password are sent repeatedly to the peer until authentication is acknowledged or the connection is terminated. This is a rather poor security mechanism. It is only performed when the connection is first established. If you want to have your peer authenticate itself, you must .Dq enable pap . in .Pa /etc/ppp/ppp.conf , and have an entry in .Pa /etc/ppp/ppp.secret for the peer (although see the .Dq passwdauth and .Dq set radius options below). .Pp When using PAP as the client, you need only specify .Dq AuthName and .Dq AuthKey in .Pa /etc/ppp/ppp.conf . PAP is accepted by default. .It pred1 Default: Enabled and Accepted. This option decides if Predictor 1 compression will be used by the Compression Control Protocol (CCP). .It protocomp Default: Enabled and Accepted. This option is used to negotiate PFC (Protocol Field Compression), a mechanism where the protocol field number is reduced to one octet rather than two. .It shortseq Default: Enabled and Accepted. This option determines if .Nm will request and accept requests for short (12 bit) sequence numbers when negotiating multi-link mode. This is only applicable if our MRRU is set (thus enabling multi-link). .It vjcomp Default: Enabled and Accepted. This option determines if Van Jacobson header compression will be used. .El .Pp The following options are not actually negotiated with the peer. Therefore, accepting or denying them makes no sense. .Bl -tag -width 2n .It echo Default: Disabled. When this option is enabled, .Nm will send .Em LCP ECHO requests to the peer at the frequency defined by .Dq echoperiod . Note, .Em LQR requests will supersede .Em LCP ECHO requests if enabled and negotiated. See .Dq set lqrperiod below for details. .Pp Prior to .Nm version 3.4.2, .Dq echo was considered enabled if lqr was enabled and negotiated, otherwise it was considered disabled. For the same behaviour, it is now necessary to .Dq enable lqr echo rather than just .Dq enable lqr . .It filter-decapsulation Default: Disabled. When this option is enabled, .Nm will examine UDP frames to see if they actually contain a .Em PPP frame as their payload. If this is the case, all filters will operate on the payload rather than the actual packet. .Pp This is useful if you want to send PPPoUDP traffic over a .Em PPP link, but want that link to do smart things with the real data rather than the UDP wrapper. .Pp The UDP frame payload must not be compressed in any way, otherwise .Nm will not be able to interpret it. It is therefore recommended that you .Ic disable vj pred1 deflate and .Ic deny vj pred1 deflate in the configuration for the .Nm invocation with the udp link. .It force-scripts Default: Disabled. Forces execution of the configured chat scripts in .Dv direct and .Dv dedicated modes. .It idcheck Default: Enabled. When .Nm exchanges low-level LCP, CCP and IPCP configuration traffic, the .Em Identifier field of any replies is expected to be the same as that of the request. By default, .Nm drops any reply packets that do not contain the expected identifier field, reporting the fact at the respective log level. If .Ar idcheck is disabled, .Nm will ignore the identifier field. .It iface-alias Default: Enabled if .Fl nat is specified. This option simply tells .Nm to add new interface addresses to the interface rather than replacing them. The option can only be enabled if network address translation is enabled .Pq Dq nat enable yes . .Pp With this option enabled, .Nm will pass traffic for old interface addresses through the NAT engine (see .Xr libalias 3 ) , resulting in the ability (in .Fl auto mode) to properly connect the process that caused the PPP link to come up in the first place. .Pp Disabling NAT with .Dq nat enable no will also disable .Sq iface-alias . .It ipcp Default: Enabled. This option allows .Nm to attempt to negotiate IP control protocol capabilities and if successful to exchange IP datagrams with the peer. .It ipv6cp Default: Enabled. This option allows .Nm to attempt to negotiate IPv6 control protocol capabilities and if successful to exchange IPv6 datagrams with the peer. .It keep-session Default: Disabled. When .Nm runs as a Multi-link server, a different .Nm instance initially receives each connection. After determining that the link belongs to an already existing bundle (controlled by another .Nm invocation), .Nm will transfer the link to that process. .Pp If the link is a tty device or if this option is enabled, .Nm will not exit, but will change its process name to .Dq session owner and wait for the controlling .Nm to finish with the link and deliver a signal back to the idle process. This prevents the confusion that results from .Nm Ns No 's parent considering the link resource available again. .Pp For tty devices that have entries in .Pa /etc/ttys , this is necessary to prevent another .Xr getty 8 from being started, and for program links such as .Xr sshd 8 , it prevents .Xr sshd 8 from exiting due to the death of its child. As .Nm cannot determine its parents requirements (except for the tty case), this option must be enabled manually depending on the circumstances. .It loopback Default: Enabled. When .Ar loopback is enabled, .Nm will automatically loop back packets being sent out with a destination address equal to that of the .Em PPP interface. If disabled, .Nm will send the packet, probably resulting in an ICMP redirect from the other end. It is convenient to have this option enabled when the interface is also the default route as it avoids the necessity of a loopback route. .It NAS-IP-Address Default: Enabled. This option controls whether .Nm sends the .Dq NAS-IP-Address attribute to the RADIUS server when RADIUS is in use .Pq see Dq set radius . .Pp Note, at least one of .Dq NAS-IP-Address and .Dq NAS-Identifier must be enabled. .Pp Versions of .Nm prior to version 3.4.1 did not send the .Dq NAS-IP-Address attribute as it was reported to break the Radiator RADIUS server. As the latest rfc (2865) no longer hints that only one of .Dq NAS-IP-Address and .Dq NAS-Identifier should be sent (as rfc 2138 did), .Nm now sends both and leaves it up to the administrator that chooses to use bad RADIUS implementations to .Dq disable NAS-IP-Address . .It NAS-Identifier Default: Enabled. This option controls whether .Nm sends the .Dq NAS-Identifier attribute to the RADIUS server when RADIUS is in use .Pq see Dq set radius . .Pp Note, at least one of .Dq NAS-IP-Address and .Dq NAS-Identifier must be enabled. .It passwdauth Default: Disabled. Enabling this option will tell the PAP authentication code to use the password database (see .Xr passwd 5 ) to authenticate the caller if they cannot be found in the .Pa /etc/ppp/ppp.secret file. .Pa /etc/ppp/ppp.secret is always checked first. If you wish to use passwords from .Xr passwd 5 , but also to specify an IP number or label for a given client, use .Dq \&* as the client password in .Pa /etc/ppp/ppp.secret . .It proxy Default: Disabled. Enabling this option will tell .Nm to proxy ARP for the peer. This means that .Nm will make an entry in the ARP table using .Dv HISADDR and the .Dv MAC address of the local network in which .Dv HISADDR appears. This allows other machines connecteed to the LAN to talk to the peer as if the peer itself was connected to the LAN. The proxy entry cannot be made unless .Dv HISADDR is an address from a LAN. .It proxyall Default: Disabled. Enabling this will tell .Nm to add proxy arp entries for every IP address in all class C or smaller subnets routed via the tun interface. .Pp Proxy arp entries are only made for sticky routes that are added using the .Dq add command. No proxy arp entries are made for the interface address itself (as created by the .Dq set ifaddr command). .It sroutes Default: Enabled. When the .Dq add command is used with the .Dv HISADDR , .Dv MYADDR , .Dv HISADDR6 or .Dv MYADDR6 values, entries are stored in the .Sq sticky route list. Each time these variables change, this list is re-applied to the routing table. .Pp Disabling this option will prevent the re-application of sticky routes, although the .Sq stick route list will still be maintained. .It Oo tcp Oc Ns No mssfixup Default: Enabled. This option tells .Nm to adjust TCP SYN packets so that the maximum receive segment size is not greater than the amount allowed by the interface MTU. .It throughput Default: Enabled. This option tells .Nm to gather throughput statistics. Input and output is sampled over a rolling 5 second window, and current, best and total figures are retained. This data is output when the relevant .Em PPP layer shuts down, and is also available using the .Dq show command. Throughput statistics are available at the .Dq IPCP and .Dq physical levels. .It utmp Default: Enabled. Normally, when a user is authenticated using PAP or CHAP, and when .Nm is running in .Fl direct mode, an entry is made in the utmp and wtmp files for that user. Disabling this option will tell .Nm not to make any utmp or wtmp entries. This is usually only necessary if you require the user to both login and authenticate themselves. .El .It add Ns Xo .Op !\& .Ar dest Ns Op / Ns Ar nn .Op Ar mask .Op Ar gateway .Xc .Ar Dest is the destination IP address. The netmask is specified either as a number of bits with .Ar /nn or as an IP number using .Ar mask . .Ar 0 0 or simply .Ar 0 with no mask refers to the default route. It is also possible to use the literal name .Sq default instead of .Ar 0 . .Ar Gateway is the next hop gateway to get to the given .Ar dest machine/network. Refer to the .Xr route 8 command for further details. .Pp It is possible to use the symbolic names .Sq MYADDR , .Sq HISADDR , .Sq MYADDR6 or .Sq HISADDR6 as the destination, and .Sq HISADDR or .Sq HISADDR6 as the .Ar gateway . .Sq MYADDR is replaced with the interface IP address, .Sq HISADDR is replaced with the interface IP destination (peer) address, .Sq MYADDR6 is replaced with the interface IPv6 address, and .Sq HISADDR6 is replaced with the interface IPv6 destination address, .Pp If the .Ar add!\& command is used (note the trailing .Dq !\& ) , then if the route already exists, it will be updated as with the .Sq route change command (see .Xr route 8 for further details). .Pp Routes that contain the .Dq HISADDR , .Dq MYADDR , .Dq HISADDR6 , .Dq MYADDR6 , .Dq DNS0 , or .Dq DNS1 constants are considered .Sq sticky . They are stored in a list (use .Dq show ncp to see the list), and each time the value of one of these variables changes, the appropriate routing table entries are updated. This facility may be disabled using .Dq disable sroutes . .It allow Ar command Op Ar args This command controls access to .Nm and its configuration files. It is possible to allow user-level access, depending on the configuration file label and on the mode that .Nm is being run in. For example, you may wish to configure .Nm so that only user .Sq fred may access label .Sq fredlabel in .Fl background mode. .Pp User id 0 is immune to these commands. .Bl -tag -width 2n .It allow user Ns Xo .Op s .Ar logname Ns No ... .Xc By default, only user id 0 is allowed access to .Nm . If this command is used, all of the listed users are allowed access to the section in which the .Dq allow users command is found. The .Sq default section is always checked first (even though it is only ever automatically loaded at startup). .Dq allow users commands are cumulative in a given section, but users allowed in any given section override users allowed in the default section, so it is possible to allow users access to everything except a given label by specifying default users in the .Sq default section, and then specifying a new user list for that label. .Pp If user .Sq * is specified, access is allowed to all users. .It allow mode Ns Xo .Op s .Ar mode Ns No ... .Xc By default, access using any .Nm mode is possible. If this command is used, it restricts the access .Ar modes allowed to load the label under which this command is specified. Again, as with the .Dq allow users command, each .Dq allow modes command overrides any previous settings, and the .Sq default section is always checked first. .Pp Possible modes are: .Sq interactive , .Sq auto , .Sq direct , .Sq dedicated , .Sq ddial , .Sq background and .Sq * . .Pp When running in multi-link mode, a section can be loaded if it allows .Em any of the currently existing line modes. .El .It nat Ar command Op Ar args This command allows the control of the network address translation (also known as masquerading or IP aliasing) facilities that are built into .Nm . NAT is done on the external interface only, and is unlikely to make sense if used with the .Fl direct flag. .Pp If nat is enabled on your system (it may be omitted at compile time), the following commands are possible: .Bl -tag -width 2n .It nat enable yes|no This command either switches network address translation on or turns it off. The .Fl nat command line flag is synonymous with .Dq nat enable yes . .It nat addr Op Ar addr_local addr_alias This command allows data for .Ar addr_alias to be redirected to .Ar addr_local . It is useful if you own a small number of real IP numbers that you wish to map to specific machines behind your gateway. .It nat deny_incoming yes|no If set to yes, this command will refuse all incoming packets where an aliasing link does not already exist. Refer to the .Sx CONCEPTUAL BACKGROUND section of .Xr libalias 3 for a description of what an .Dq aliasing link is. .Pp It should be noted under what circumstances an aliasing link is created by .Xr libalias 3 . It may be necessary to further protect your network from outside connections using the .Dq set filter or .Dq nat target commands. .It nat help|? This command gives a summary of available nat commands. .It nat log yes|no This option causes various NAT statistics and information to be logged to the file .Pa /var/log/alias.log . .It nat port Ar proto Ar targetIP Ns Xo .No : Ns Ar targetPort Ns .Oo .No - Ns Ar targetPort .Oc Ar aliasPort Ns .Oo .No - Ns Ar aliasPort .Oc Oo Ar remoteIP : Ns .Ar remotePort Ns .Oo .No - Ns Ar remotePort .Oc .Oc .Xc This command causes incoming .Ar proto connections to .Ar aliasPort to be redirected to .Ar targetPort on .Ar targetIP . .Ar proto is either .Dq tcp or .Dq udp . .Pp A range of port numbers may be specified as shown above. The ranges must be of the same size. .Pp If .Ar remoteIP is specified, only data coming from that IP number is redirected. .Ar remotePort must either be .Dq 0 (indicating any source port) or a range of ports the same size as the other ranges. .Pp This option is useful if you wish to run things like Internet phone on machines behind your gateway, but is limited in that connections to only one interior machine per source machine and target port are possible. .It nat proto Ar proto localIP Oo .Ar publicIP Op Ar remoteIP .Oc This command tells .Nm to redirect packets of protocol type .Ar proto (see .Xr protocols 5 ) to the internal address .Ar localIP . .Pp If .Ar publicIP is specified, only packets destined for that address are matched, otherwise the default alias address is used. .Pp If .Ar remoteIP is specified, only packets matching that source address are matched, .Pp This command is useful for redirecting tunnel endpoints to an internal machine, for example: .Pp .Dl nat proto ipencap 10.0.0.1 .It "nat proxy cmd" Ar arg Ns No ... This command tells .Nm to proxy certain connections, redirecting them to a given server. Refer to the description of .Fn PacketAliasProxyRule in .Xr libalias 3 for details of the available commands. .It nat punch_fw Op Ar base count This command tells .Nm to punch holes in the firewall for FTP or IRC DCC connections. This is done dynamically by installing temporary firewall rules which allow a particular connection (and only that connection) to go through the firewall. The rules are removed once the corresponding connection terminates. .Pp A maximum of .Ar count rules starting from rule number .Ar base will be used for punching firewall holes. The range will be cleared when the .Dq nat punch_fw command is run. .Pp If no arguments are given, firewall punching is disabled. .It nat skinny_port Op Ar port This command tells .Nm which TCP port is used by the Skinny Station protocol. Skinny is used by Cisco IP phones to communicate with Cisco Call Managers to setup voice over IP calls. The typical port used by Skinny is 2000. .Pp If no argument is given, skinny aliasing is disabled. .It nat same_ports yes|no When enabled, this command will tell the network address translation engine to attempt to avoid changing the port number on outgoing packets. This is useful if you want to support protocols such as RPC and LPD which require connections to come from a well known port. .It nat target Op Ar address Set the given target address or clear it if no address is given. The target address is used by libalias to specify how to NAT incoming packets by default. If a target address is not set or if .Dq default is given, packets are not altered and are allowed to route to the internal network. .Pp The target address may be set to .Dq MYADDR , in which case libalias will redirect all packets to the interface address. .It nat use_sockets yes|no When enabled, this option tells the network address translation engine to create a socket so that it can guarantee a correct incoming ftp data or IRC connection. .It nat unregistered_only yes|no Only alter outgoing packets with an unregistered source address. According to RFC 1918, unregistered source addresses are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16. .El .Pp These commands are also discussed in the file .Pa README.nat which comes with the source distribution. .It Oo !\& Oc Ns Xo .No bg Ar command .Xc The given .Ar command is executed in the background with the following words replaced: .Bl -tag -width COMPILATIONDATE .It Li AUTHNAME This is replaced with the local .Ar authname value. See the .Dq set authname command below. .It Li COMPILATIONDATE In previous software revisions, this was replaced with the date on which .Nm was compiled. This is no longer supported as it breaks the ability to recompile the same code to produce an exact duplicate of a previous compilation. .It Li DNS0 & DNS1 These are replaced with the primary and secondary nameserver IP numbers. If nameservers are negotiated by IPCP, the values of these macros will change. .It Li ENDDISC This is replaced with the local endpoint discriminator value. See the .Dq set enddisc command below. .It Li HISADDR This is replaced with the peers IP number. .It Li HISADDR6 This is replaced with the peers IPv6 number. .It Li INTERFACE This is replaced with the name of the interface that is in use. .It Li IPOCTETSIN This is replaced with the number of IP bytes received since the connection was established. .It Li IPOCTETSOUT This is replaced with the number of IP bytes sent since the connection was established. .It Li IPPACKETSIN This is replaced with the number of IP packets received since the connection was established. .It Li IPPACKETSOUT This is replaced with the number of IP packets sent since the connection was established. .It Li IPV6OCTETSIN This is replaced with the number of IPv6 bytes received since the connection was established. .It Li IPV6OCTETSOUT This is replaced with the number of IPv6 bytes sent since the connection was established. .It Li IPV6PACKETSIN This is replaced with the number of IPv6 packets received since the connection was established. .It Li IPV6PACKETSOUT This is replaced with the number of IPv6 packets sent since the connection was established. .It Li LABEL This is replaced with the last label name used. A label may be specified on the .Nm command line, via the .Dq load or .Dq dial commands and in the .Pa ppp.secret file. .It Li MYADDR This is replaced with the IP number assigned to the local interface. .It Li MYADDR6 This is replaced with the IPv6 number assigned to the local interface. .It Li OCTETSIN This is replaced with the number of bytes received since the connection was established. .It Li OCTETSOUT This is replaced with the number of bytes sent since the connection was established. .It Li PACKETSIN This is replaced with the number of packets received since the connection was established. .It Li PACKETSOUT This is replaced with the number of packets sent since the connection was established. .It Li PEER_ENDDISC This is replaced with the value of the peers endpoint discriminator. .It Li PROCESSID This is replaced with the current process id. .It Li SOCKNAME This is replaced with the name of the diagnostic socket. .It Li UPTIME This is replaced with the bundle uptime in HH:MM:SS format. .It Li USER This is replaced with the username that has been authenticated with PAP or CHAP. Normally, this variable is assigned only in -direct mode. This value is available irrespective of whether utmp logging is enabled. .It Li VERSION This is replaced with the current version number of .Nm . .El .Pp These substitutions are also done by the .Dq set proctitle , .Dq ident and .Dq log commands. .Pp If you wish to pause .Nm while the command executes, use the .Dq shell command instead. .It clear physical|ipcp|ipv6 Op current|overall|peak... Clear the specified throughput values at either the .Dq physical , .Dq ipcp or .Dq ipv6cp level. If .Dq physical is specified, context must be given (see the .Dq link command below). If no second argument is given, all values are cleared. .It clone Ar name Ns Xo .Op \&, Ns Ar name Ns .No ... .Xc Clone the specified link, creating one or more new links according to the .Ar name argument(s). This command must be used from the .Dq link command below unless you have only got a single link (in which case that link becomes the default). Links may be removed using the .Dq remove command below. .Pp The default link name is .Dq deflink . .It close Op lcp|ccp Ns Op !\& If no arguments are given, the relevant protocol layers will be brought down and the link will be closed. If .Dq lcp is specified, the LCP layer is brought down, but .Nm will not bring the link offline. It is subsequently possible to use .Dq term (see below) to talk to the peer machine if, for example, something like .Dq slirp is being used. If .Dq ccp is specified, only the relevant compression layer is closed. If the .Dq !\& is used, the compression layer will remain in the closed state, otherwise it will re-enter the STOPPED state, waiting for the peer to initiate further CCP negotiation. In any event, this command does not disconnect the user from .Nm or exit .Nm . See the .Dq quit command below. .It delete Ns Xo .Op !\& .Ar dest .Xc This command deletes the route with the given .Ar dest IP address. If .Ar dest is specified as .Sq ALL , all non-direct entries in the routing table for the current interface, and all .Sq sticky route entries are deleted. If .Ar dest is specified as .Sq default , the default route is deleted. .Pp If the .Ar delete!\& command is used (note the trailing .Dq !\& ) , .Nm will not complain if the route does not already exist. .It dial|call Oo Ar label Oc Ns Xo .No ... .Xc This command is the equivalent of .Dq load label followed by .Dq open , and is provided for backwards compatibility. .It down Op Ar lcp|ccp Bring the relevant layer down ungracefully, as if the underlying layer had become unavailable. It is not considered polite to use this command on a Finite State Machine that is in the OPEN state. If no arguments are supplied, the entire link is closed (or if no context is given, all links are terminated). If .Sq lcp is specified, the .Em LCP layer is terminated but the device is not brought offline and the link is not closed. If .Sq ccp is specified, only the relevant compression layer(s) are terminated. .It help|? Op Ar command Show a list of available commands. If .Ar command is specified, show the usage string for that command. .It ident Op Ar text Ns No ... Identify the link to the peer using .Ar text . If .Ar text is empty, link identification is disabled. It is possible to use any of the words described for the .Ic bg command above. Refer to the .Ic sendident command for details of when .Nm identifies itself to the peer. .It iface Ar command Op args This command is used to control the interface used by .Nm . .Ar Command may be one of the following: .Bl -tag -width 2n .It iface add Ns Xo .Op !\& .Ar addr Ns Op / Ns Ar bits .Op Ar peer .Xc .It iface add Ns Xo .Op !\& .Ar addr .Ar mask .Ar peer .Xc Add the given .Ar addr mask peer combination to the interface. Instead of specifying .Ar mask , .Ar /bits can be used (with no space between it and .Ar addr ) . If the given address already exists, the command fails unless the .Dq !\& is used - in which case the previous interface address entry is overwritten with the new one, allowing a change of netmask or peer address. .Pp If only .Ar addr is specified, .Ar bits defaults to .Dq 32 and .Ar peer defaults to .Dq 255.255.255.255 . This address (the broadcast address) is the only duplicate peer address that .Nm allows. .It iface clear Op INET | INET6 If this command is used while .Nm is in the OPENED state or while in .Fl auto mode, all addresses except for the NCP negotiated address are deleted from the interface. If .Nm is not in the OPENED state and is not in .Fl auto mode, all interface addresses are deleted. .Pp If the INET or INET6 arguments are used, only addresses for that address family are cleared. .It iface delete Ns Xo .Op !\& Ns .No |rm Ns Op !\& .Ar addr .Xc This command deletes the given .Ar addr from the interface. If the .Dq !\& is used, no error is given if the address is not currently assigned to the interface (and no deletion takes place). .It iface name Ar name Renames the interface to .Ar name . .It iface description Ar description Sets the interface description to .Ar description . Useful if you have many interfaces on your system. .It iface show Shows the current state and current addresses for the interface. It is much the same as running .Dq ifconfig INTERFACE . .It iface help Op Ar sub-command This command, when invoked without .Ar sub-command , will show a list of possible .Dq iface sub-commands and a brief synopsis for each. When invoked with .Ar sub-command , only the synopsis for the given sub-command is shown. .El .It Oo data Oc Ns Xo .No link .Ar name Ns Oo , Ns Ar name Oc Ns ... Ar command Op Ar args .Xc This command may prefix any other command if the user wishes to specify which link the command should affect. This is only applicable after multiple links have been created in Multi-link mode using the .Dq clone command. .Pp .Ar Name specifies the name of an existing link. If .Ar name is a comma separated list, .Ar command is executed on each link. If .Ar name is .Dq * , .Ar command is executed on all links. .It load Oo Ar label Oc Ns Xo .No ... .Xc Load the given .Ar label Ns No (s) from the .Pa ppp.conf file. If .Ar label is not given, the .Ar default label is used. .Pp Unless the .Ar label section uses the .Dq set mode , .Dq open or .Dq dial commands, .Nm will not attempt to make an immediate connection. .It log Ar word Ns No ... Send the given word(s) to the log file with the prefix .Dq LOG: . Word substitutions are done as explained under the .Dq !bg command above. .It open Op lcp|ccp|ipcp This is the opposite of the .Dq close command. All closed links are immediately brought up apart from second and subsequent .Ar demand-dial links - these will come up based on the .Dq set autoload command that has been used. .Pp If the .Dq lcp argument is used while the LCP layer is already open, LCP will be renegotiated. This allows various LCP options to be changed, after which .Dq open lcp can be used to put them into effect. After renegotiating LCP, any agreed authentication will also take place. .Pp If the .Dq ccp argument is used, the relevant compression layer is opened. Again, if it is already open, it will be renegotiated. .Pp If the .Dq ipcp argument is used, the link will be brought up as normal, but if IPCP is already open, it will be renegotiated and the network interface will be reconfigured. .Pp It is probably not good practice to re-open the PPP state machines like this as it is possible that the peer will not behave correctly. It .Em is however useful as a way of forcing the CCP or VJ dictionaries to be reset. .It passwd Ar pass Specify the password required for access to the full .Nm command set. This password is required when connecting to the diagnostic port (see the .Dq set server command). .Ar Pass is specified on the .Dq set server command line. The value of .Ar pass is not logged when .Ar command logging is active, instead, the literal string .Sq ******** is logged. .It quit|bye Op all If .Dq quit is executed from the controlling connection or from a command file, ppp will exit after closing all connections. Otherwise, if the user is connected to a diagnostic socket, the connection is simply dropped. .Pp If the .Ar all argument is given, .Nm will exit despite the source of the command after closing all existing connections. .It remove|rm This command removes the given link. It is only really useful in multi-link mode. A link must be in the .Dv CLOSED state before it is removed. .It rename|mv Ar name This command renames the given link to .Ar name . It will fail if .Ar name is already used by another link. .Pp The default link name is .Sq deflink . Renaming it to .Sq modem , .Sq cuau0 or .Sq USR may make the log file more readable. .It resolv Ar command This command controls .Nm Ns No 's manipulation of the .Xr resolv.conf 5 file. When .Nm starts up, it loads the contents of this file into memory and retains this image for future use. .Ar command is one of the following: .Bl -tag -width readonly .It Em readonly Treat .Pa /etc/resolv.conf as read only. If .Dq dns is enabled, .Nm will still attempt to negotiate nameservers with the peer, making the results available via the .Dv DNS0 and .Dv DNS1 macros. This is the opposite of the .Dq resolv writable command. .It Em reload Reload .Pa /etc/resolv.conf into memory. This may be necessary if for example a DHCP client overwrote .Pa /etc/resolv.conf . .It Em restore Replace .Pa /etc/resolv.conf with the version originally read at startup or with the last .Dq resolv reload command. This is sometimes a useful command to put in the .Pa /etc/ppp/ppp.linkdown file. .It Em rewrite Rewrite the .Pa /etc/resolv.conf file. This command will work even if the .Dq resolv readonly command has been used. It may be useful as a command in the .Pa /etc/ppp/ppp.linkup file if you wish to defer updating .Pa /etc/resolv.conf until after other commands have finished. .It Em writable Allow .Nm to update .Pa /etc/resolv.conf if .Dq dns is enabled and .Nm successfully negotiates a DNS. This is the opposite of the .Dq resolv readonly command. .El .It save This option is not (yet) implemented. .It sendident This command tells .Nm to identify itself to the peer. The link must be in LCP state or higher. If no identity has been set (via the .Ic ident command), .Ic sendident will fail. .Pp When an identity has been set, .Nm will automatically identify itself when it sends or receives a configure reject, when negotiation fails or when LCP reaches the opened state. .Pp Received identification packets are logged to the LCP log (see .Ic set log for details) and are never responded to. .It set Ns Xo .Op up .Ar var value .Xc This option allows the setting of any of the following variables: .Bl -tag -width 2n .It set accmap Ar hex-value ACCMap stands for Asynchronous Control Character Map. This is always negotiated with the peer, and defaults to a value of 00000000 in hex. This protocol is required to defeat hardware that depends on passing certain characters from end to end (such as XON/XOFF etc). .Pp For the XON/XOFF scenario, use .Dq set accmap 000a0000 . .It set Oo auth Oc Ns Xo .No key Ar value .Xc This sets the authentication key (or password) used in client mode PAP or CHAP negotiation to the given value. It also specifies the password to be used in the dial or login scripts in place of the .Sq \eP sequence, preventing the actual password from being logged. If .Ar command or .Ar chat logging is in effect, .Ar value is logged as .Sq ******** for security reasons. .Pp If the first character of .Ar value is an exclamation mark .Pq Dq !\& , .Nm treats the remainder of the string as a program that must be executed to determine the .Dq authname and .Dq authkey values. .Pp If the .Dq !\& is doubled up (to .Dq !! ) , it is treated as a single literal .Dq !\& , otherwise, ignoring the .Dq !\& , .Ar value is parsed as a program to execute in the same was as the .Dq !bg command above, substituting special names in the same manner. Once executed, .Nm will feed the program three lines of input, each terminated by a newline character: .Bl -bullet .It The host name as sent in the CHAP challenge. .It The challenge string as sent in the CHAP challenge. .It The locally defined .Dq authname . .El .Pp Two lines of output are expected: .Bl -bullet .It The .Dq authname to be sent with the CHAP response. .It The .Dq authkey , which is encrypted with the challenge and request id, the answer being sent in the CHAP response packet. .El .Pp When configuring .Nm in this manner, it is expected that the host challenge is a series of ASCII digits or characters. An encryption device or Secure ID card is usually required to calculate the secret appropriate for the given challenge. .It set authname Ar id This sets the authentication id used in client mode PAP or CHAP negotiation. .Pp If used in .Fl direct mode with CHAP enabled, .Ar id is used in the initial authentication challenge and should normally be set to the local machine name. .It set autoload Xo .Ar min-percent max-percent period .Xc These settings apply only in multi-link mode and default to zero, zero and five respectively. When more than one .Ar demand-dial (also known as .Fl auto ) mode link is available, only the first link is made active when .Nm first reads data from the tun device. The next .Ar demand-dial link will be opened only when the current bundle throughput is at least .Ar max-percent percent of the total bundle bandwidth for .Ar period seconds. When the current bundle throughput decreases to .Ar min-percent percent or less of the total bundle bandwidth for .Ar period seconds, a .Ar demand-dial link will be brought down as long as it is not the last active link. .Pp Bundle throughput is measured as the maximum of inbound and outbound traffic. .Pp The default values cause .Ar demand-dial links to simply come up one at a time. .Pp Certain devices cannot determine their physical bandwidth, so it is sometimes necessary to use the .Dq set bandwidth command (described below) to make .Dq set autoload work correctly. .It set bandwidth Ar value This command sets the connection bandwidth in bits per second. .Ar value must be greater than zero. It is currently only used by the .Dq set autoload command above. .It set callback Ar option Ns No ... If no arguments are given, callback is disabled, otherwise, .Nm will request (or in .Fl direct mode, will accept) one of the given .Ar option Ns No s . In client mode, if an .Ar option is NAK'd .Nm will request a different .Ar option , until no options remain at which point .Nm will terminate negotiations (unless .Dq none is one of the specified .Ar option ) . In server mode, .Nm will accept any of the given protocols - but the client .Em must request one of them. If you wish callback to be optional, you must {include} .Ar none as an option. .Pp The .Ar option Ns No s are as follows (in this order of preference): .Bl -tag -width Ds .It auth The callee is expected to decide the callback number based on authentication. If .Nm is the callee, the number should be specified as the fifth field of the peers entry in .Pa /etc/ppp/ppp.secret . .It cbcp Microsoft's callback control protocol is used. See .Dq set cbcp below. .Pp If you wish to negotiate .Ar cbcp in client mode but also wish to allow the server to request no callback at CBCP negotiation time, you must specify both .Ar cbcp and .Ar none as callback options. .It E.164 *| Ns Xo .Ar number Ns Op , Ns Ar number Ns .No ... .Xc The caller specifies the .Ar number . If .Nm is the callee, .Ar number should be either a comma separated list of allowable numbers or a .Dq \&* , meaning any number is permitted. If .Nm is the caller, only a single number should be specified. .Pp Note, this option is very unsafe when used with a .Dq \&* as a malicious caller can tell .Nm to call any (possibly international) number without first authenticating themselves. .It none If the peer does not wish to do callback at all, .Nm will accept the fact and continue without callback rather than terminating the connection. This is required (in addition to one or more other callback options) if you wish callback to be optional. .El .It set cbcp Oo .No *| Ns Ar number Ns Oo .No , Ns Ar number Ns ...\& Oc .Op Ar delay Op Ar retry .Oc If no arguments are given, CBCP (Microsoft's CallBack Control Protocol) is disabled - ie, configuring CBCP in the .Dq set callback command will result in .Nm requesting no callback in the CBCP phase. Otherwise, .Nm attempts to use the given phone .Ar number Ns No (s). .Pp In server mode .Pq Fl direct , .Nm will insist that the client uses one of these numbers, unless .Dq \&* is used in which case the client is expected to specify the number. .Pp In client mode, .Nm will attempt to use one of the given numbers (whichever it finds to be agreeable with the peer), or if .Dq \&* is specified, .Nm will expect the peer to specify the number. .It set cd Oo .No off| Ns Ar seconds Ns Op !\& .Oc Normally, .Nm checks for the existence of carrier depending on the type of device that has been opened: .Bl -tag -width XXX -offset XXX .It Terminal Devices Carrier is checked one second after the login script is complete. If it is not set, .Nm assumes that this is because the device does not support carrier (which is true for most .Dq laplink NULL-modem cables), logs the fact and stops checking for carrier. .Pp As ptys do not support the TIOCMGET ioctl, the tty device will switch all carrier detection off when it detects that the device is a pty. .It PPPoE (netgraph) Devices Carrier is checked once per second for 5 seconds. If it is not set after the fifth second, the connection attempt is considered to have failed and the device is closed. Carrier is always required for PPPoE devices. .El .Pp All other device types do not support carrier. Setting a carrier value will result in a warning when the device is opened. .Pp Some modems take more than one second after connecting to assert the carrier signal. If this delay is not increased, this will result in .Nm Ns No 's inability to detect when the link is dropped, as .Nm assumes that the device is not asserting carrier. .Pp The .Dq set cd command overrides the default carrier behaviour. .Ar seconds specifies the maximum number of seconds that .Nm should wait after the dial script has finished before deciding if carrier is available or not. .Pp If .Dq off is specified, .Nm will not check for carrier on the device, otherwise .Nm will not proceed to the login script until either carrier is detected or until .Ar seconds has elapsed, at which point .Nm assumes that the device will not set carrier. .Pp If no arguments are given, carrier settings will go back to their default values. .Pp If .Ar seconds is followed immediately by an exclamation mark .Pq Dq !\& , .Nm will .Em require carrier. If carrier is not detected after .Ar seconds seconds, the link will be disconnected. .It set choked Op Ar timeout This sets the number of seconds that .Nm will keep a choked output queue before dropping all pending output packets. If .Ar timeout is less than or equal to zero or if .Ar timeout is not specified, it is set to the default value of .Em 120 seconds . .Pp A choked output queue occurs when .Nm has read a certain number of packets from the local network for transmission, but cannot send the data due to link failure (the peer is busy etc.). .Nm will not read packets indefinitely. Instead, it reads up to .Em 30 packets (or .Em 30 No + .Em nlinks No * .Em 2 packets in multi-link mode), then stops reading the network interface until either .Ar timeout seconds have passed or at least one packet has been sent. .Pp If .Ar timeout seconds pass, all pending output packets are dropped. .It set ctsrts|crtscts on|off This sets hardware flow control. Hardware flow control is .Ar on by default. .It set deflate Ar out-winsize Op Ar in-winsize This sets the DEFLATE algorithms default outgoing and incoming window sizes. Both .Ar out-winsize and .Ar in-winsize must be values between .Em 8 and .Em 15 . If .Ar in-winsize is specified, .Nm will insist that this window size is used and will not accept any other values from the peer. .It set dns Op Ar primary Op Ar secondary This command specifies DNS overrides for the .Dq accept dns command. Refer to the .Dq accept command description above for details. This command does not affect the IP numbers requested using .Dq enable dns . .It set device|line Xo .Ar value Ns No ... .Xc This sets the device(s) to which .Nm will talk to the given .Dq value . .Pp All serial device names are expected to begin with .Pa /dev/ . Serial devices are usually called .Pa cuaXX . .Pp If .Dq value does not begin with .Pa /dev/ , it must either begin with an exclamation mark .Pq Dq !\& , be of the format .No PPPoE: Ns Ar iface Ns Xo .Op \&: Ns Ar provider Ns .Xc (on .Xr netgraph 4 enabled systems), or be of the format .Sm off .Ar host : port Op /tcp|udp . .Sm on .Pp If it begins with an exclamation mark, the rest of the device name is treated as a program name, and that program is executed when the device is opened. Standard input, output and error are fed back to .Nm and are read and written as if they were a regular device. .Pp If a .No PPPoE: Ns Ar iface Ns Xo .Op \&: Ns Ar provider Ns .Xc specification is given, .Nm will attempt to create a .Em PPP over Ethernet connection using the given .Ar iface interface by using .Xr netgraph 4 . If .Xr netgraph 4 is not available, .Nm will attempt to load it using .Xr kldload 2 . If this fails, an external program must be used such as the .Xr pppoed 8 program available under .Ox . The given .Ar provider is passed as the service name in the PPPoE Discovery Initiation (PADI) packet. If no provider is given, an empty value will be used. .Pp When a PPPoE connection is established, .Nm will place the name of the Access Concentrator in the environment variable .Ev ACNAME . .Pp Refer to .Xr netgraph 4 and .Xr ng_pppoe 4 for further details. .Pp If a .Ar host Ns No : Ns Ar port Ns Oo .No /tcp|udp .Oc specification is given, .Nm will attempt to connect to the given .Ar host on the given .Ar port . If a .Dq /tcp or .Dq /udp suffix is not provided, the default is .Dq /tcp . Refer to the section on .Em PPP OVER TCP and UDP above for further details. .Pp If multiple .Dq values are specified, .Nm will attempt to open each one in turn until it succeeds or runs out of devices. .It set dial Ar chat-script This specifies the chat script that will be used to dial the other side. See also the .Dq set login command below. Refer to .Xr chat 8 and to the example configuration files for details of the chat script format. It is possible to specify some special .Sq values in your chat script as follows: .Bl -tag -width 2n .It Li \ec When used as the last character in a .Sq send string, this indicates that a newline should not be appended. .It Li \ed When the chat script encounters this sequence, it delays two seconds. .It Li \ep When the chat script encounters this sequence, it delays for one quarter of a second. .It Li \en This is replaced with a newline character. .It Li \er This is replaced with a carriage return character. .It Li \es This is replaced with a space character. .It Li \et This is replaced with a tab character. .It Li \eT This is replaced by the current phone number (see .Dq set phone below). .It Li \eP This is replaced by the current .Ar authkey value (see .Dq set authkey above). .It Li \eU This is replaced by the current .Ar authname value (see .Dq set authname above). .El .Pp Note that two parsers will examine these escape sequences, so in order to have the .Sq chat parser see the escape character, it is necessary to escape it from the .Sq command parser . This means that in practice you should use two escapes, for example: .Bd -literal -offset indent set dial "... ATDT\\\\T CONNECT" .Ed .Pp It is also possible to execute external commands from the chat script. To do this, the first character of the expect or send string is an exclamation mark .Pq Dq !\& . If a literal exclamation mark is required, double it up to .Dq !!\& and it will be treated as a single literal .Dq !\& . When the command is executed, standard input and standard output are directed to the open device (see the .Dq set device command), and standard error is read by .Nm and substituted as the expect or send string. If .Nm is running in interactive mode, file descriptor 3 is attached to .Pa /dev/tty . .Pp For example (wrapped for readability): .Bd -literal -offset indent set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e word: ppp \\"!sh \\\\-c \\\\\\"echo \\\\-n label: >&2\\\\\\"\\" \e \\"!/bin/echo in\\" HELLO" .Ed .Pp would result in the following chat sequence (output using the .Sq set log local chat command before dialing): .Bd -literal -offset indent Dial attempt 1 of 1 dial OK! Chat: Expecting: Chat: Sending: Chat: Expecting: login:--login: Chat: Wait for (5): login: Chat: Sending: ppp Chat: Expecting: word: Chat: Wait for (5): word: Chat: Sending: ppp Chat: Expecting: !sh \\-c "echo \\-n label: >&2" Chat: Exec: sh -c "echo -n label: >&2" Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label: Chat: Exec: /bin/echo in Chat: Sending: Chat: Expecting: HELLO Chat: Wait for (5): HELLO login OK! .Ed .Pp Note (again) the use of the escape character, allowing many levels of nesting. Here, there are four parsers at work. The first parses the original line, reading it as three arguments. The second parses the third argument, reading it as 11 arguments. At this point, it is important that the .Dq \&- signs are escaped, otherwise this parser will see them as constituting an expect-send-expect sequence. When the .Dq !\& character is seen, the execution parser reads the first command as three arguments, and then .Xr sh 1 itself expands the argument after the .Fl c . As we wish to send the output back to the modem, in the first example we redirect our output to file descriptor 2 (stderr) so that .Nm itself sends and logs it, and in the second example, we just output to stdout, which is attached directly to the modem. .Pp This, of course means that it is possible to execute an entirely external .Dq chat command rather than using the internal one. See .Xr chat 8 for a good alternative. .Pp The external command that is executed is subjected to the same special word expansions as the .Dq !bg command. .It set enddisc Op label|IP|MAC|magic|psn value This command sets our local endpoint discriminator. If set prior to LCP negotiation, and if no .Dq disable enddisc command has been used, .Nm will send the information to the peer using the LCP endpoint discriminator option. The following discriminators may be set: .Bl -tag -width indent .It Li label The current label is used. .It Li IP Our local IP number is used. As LCP is negotiated prior to IPCP, it is possible that the IPCP layer will subsequently change this value. If it does, the endpoint discriminator stays at the old value unless manually reset. .It Li MAC This is similar to the .Ar IP option above, except that the MAC address associated with the local IP number is used. If the local IP number is not resident on any Ethernet interface, the command will fail. .Pp As the local IP number defaults to whatever the machine host name is, .Dq set enddisc mac is usually done prior to any .Dq set ifaddr commands. .It Li magic A 20 digit random number is used. Care should be taken when using magic numbers as restarting .Nm or creating a link using a different .Nm invocation will also use a different magic number and will therefore not be recognised by the peer as belonging to the same bundle. This makes it unsuitable for .Fl direct connections. .It Li psn Ar value The given .Ar value is used. .Ar Value should be set to an absolute public switched network number with the country code first. .El .Pp If no arguments are given, the endpoint discriminator is reset. .It set escape Ar value... This option is similar to the .Dq set accmap option above. It allows the user to specify a set of characters that will be .Sq escaped as they travel across the link. .It set filter dial|alive|in|out Ar rule-no Xo .No permit|deny|clear| Ns Ar rule-no .Op !\& .Oo Op host .Ar src_addr Ns Op / Ns Ar width .Op Ar dst_addr Ns Op / Ns Ar width .Oc [ Ns Ar proto .Op src lt|eq|gt Ar port .Op dst lt|eq|gt Ar port .Op estab .Op syn .Op finrst .Op timeout Ar secs ] .Xc .Nm supports four filter sets. The .Em alive filter specifies packets that keep the connection alive - resetting the idle timer. The .Em dial filter specifies packets that cause .Nm to dial when in .Fl auto mode. The .Em in filter specifies packets that are allowed to travel into the machine and the .Em out filter specifies packets that are allowed out of the machine. .Pp Filtering is done prior to any IP alterations that might be done by the NAT engine on outgoing packets and after any IP alterations that might be done by the NAT engine on incoming packets. By default all empty filter sets allow all packets to pass. Rules are processed in order according to .Ar rule-no (unless skipped by specifying a rule number as the .Ar action ) . Up to 40 rules may be given for each set. If a packet does not match any of the rules in a given set, it is discarded. In the case of .Em in and .Em out filters, this means that the packet is dropped. In the case of .Em alive filters it means that the packet will not reset the idle timer (even if the .Ar in Ns No / Ns Ar out filter has a .Dq timeout value) and in the case of .Em dial filters it means that the packet will not trigger a dial. A packet failing to trigger a dial will be dropped rather than queued. Refer to the section on .Sx PACKET FILTERING above for further details. .It set hangup Ar chat-script This specifies the chat script that will be used to reset the device before it is closed. It should not normally be necessary, but can be used for devices that fail to reset themselves properly on close. .It set help|? Op Ar command This command gives a summary of available set commands, or if .Ar command is specified, the command usage is shown. .It set ifaddr Oo Ar myaddr Ns .Op / Ns Ar \&nn .Oo Ar hisaddr Ns Op / Ns Ar \&nn .Oo Ar netmask .Op Ar triggeraddr .Oc Oc .Oc This command specifies the IP addresses that will be used during IPCP negotiation. Addresses are specified using the format .Pp .Dl a.b.c.d/nn .Pp Where .Dq a.b.c.d is the preferred IP, but .Ar nn specifies how many bits of the address we will insist on. If .No / Ns Ar nn is omitted, it defaults to .Dq /32 unless the IP address is 0.0.0.0 in which case it defaults to .Dq /0 . .Pp If you wish to assign a dynamic IP number to the peer, .Ar hisaddr may also be specified as a range of IP numbers in the format .Bd -ragged -offset indent .Ar \&IP Ns Oo \&- Ns Ar \&IP Ns Oc Ns Oo , Ns Ar \&IP Ns .Oo \&- Ns Ar \&IP Ns Oc Oc Ns ... .Ed .Pp for example: .Pp .Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20 .Pp will only negotiate .Dq 10.0.0.1 as the local IP number, but may assign any of the given 10 IP numbers to the peer. If the peer requests one of these numbers, and that number is not already in use, .Nm will grant the peers request. This is useful if the peer wants to re-establish a link using the same IP number as was previously allocated (thus maintaining any existing tcp or udp connections). .Pp If the peer requests an IP number that is either outside of this range or is already in use, .Nm will suggest a random unused IP number from the range. .Pp If .Ar triggeraddr is specified, it is used in place of .Ar myaddr in the initial IPCP negotiation. However, only an address in the .Ar myaddr range will be accepted. This is useful when negotiating with some .Dv PPP implementations that will not assign an IP number unless their peer requests .Dq 0.0.0.0 . .Pp It should be noted that in .Fl auto mode, .Nm will configure the interface immediately upon reading the .Dq set ifaddr line in the config file. In any other mode, these values are just used for IPCP negotiations, and the interface is not configured until the IPCP layer is up. .Pp Note that the .Ar HISADDR argument may be overridden by the third field in the .Pa ppp.secret file once the client has authenticated itself (if PAP or CHAP are .Dq enabled ) . Refer to the .Sx AUTHENTICATING INCOMING CONNECTIONS section for details. .Pp In all cases, if the interface is already configured, .Nm will try to maintain the interface IP numbers so that any existing bound sockets will remain valid. .It set ifqueue Ar packets Set the maximum number of packets that .Nm will read from the tunnel interface while data cannot be sent to any of the available links. This queue limit is necessary to flow control outgoing data as the tunnel interface is likely to be far faster than the combined links available to .Nm . .Pp If .Ar packets is set to a value less than the number of links, .Nm will read up to that value regardless. This prevents any possible latency problems. .Pp The default value for .Ar packets is .Dq 30 . .It set ccpretry|ccpretries Oo Ar timeout .Op Ar reqtries Op Ar trmtries .Oc .It set chapretry|chapretries Oo Ar timeout .Op Ar reqtries .Oc .It set ipcpretry|ipcpretries Oo Ar timeout .Op Ar reqtries Op Ar trmtries .Oc .It set ipv6cpretry|ipv6cpretries Oo Ar timeout .Op Ar reqtries Op Ar trmtries .Oc .It set lcpretry|lcpretries Oo Ar timeout .Op Ar reqtries Op Ar trmtries .Oc .It set papretry|papretries Oo Ar timeout .Op Ar reqtries .Oc These commands set the number of seconds that .Nm will wait before resending Finite State Machine (FSM) Request packets. The default .Ar timeout for all FSMs is 3 seconds (which should suffice in most cases). .Pp If .Ar reqtries is specified, it tells .Nm how many configuration request attempts it should make while receiving no reply from the peer before giving up. The default is 5 attempts for CCP, LCP and IPCP and 3 attempts for PAP and CHAP. .Pp If .Ar trmtries is specified, it tells .Nm how many terminate requests should be sent before giving up waiting for the peers response. The default is 3 attempts. Authentication protocols are not terminated and it is therefore invalid to specify .Ar trmtries for PAP or CHAP. .Pp In order to avoid negotiations with the peer that will never converge, .Nm will only send at most 3 times the configured number of .Ar reqtries in any given negotiation session before giving up and closing that layer. .It set log Xo .Op local .Op +|- Ns .Ar value Ns No ... .Xc This command allows the adjustment of the current log level. Refer to the Logging Facility section for further details. .It set login Ar chat-script This .Ar chat-script compliments the dial-script. If both are specified, the login script will be executed after the dial script. Escape sequences available in the dial script are also available here. .It set logout Ar chat-script This specifies the chat script that will be used to logout before the hangup script is called. It should not normally be necessary. .It set lqrperiod|echoperiod Ar frequency This command sets the .Ar frequency in seconds at which .Em LQR or .Em LCP ECHO packets are sent. The default is 30 seconds. You must also use the .Dq enable lqr and/or .Dq enable echo commands if you wish to send .Em LQR or .Em LCP ECHO requests to the peer. .It set mode Ar interactive|auto|ddial|background This command allows you to change the .Sq mode of the specified link. This is normally only useful in multi-link mode, but may also be used in uni-link mode. .Pp It is not possible to change a link that is .Sq direct or .Sq dedicated . .Pp Note: If you issue the command .Dq set mode auto , and have network address translation enabled, it may be useful to .Dq enable iface-alias afterwards. This will allow .Nm to do the necessary address translations to enable the process that triggers the connection to connect once the link is up despite the peer assigning us a new (dynamic) IP address. .It set mppe Op 40|56|128|* Op stateless|stateful|* This option selects the encryption parameters used when negotiation MPPE. MPPE can be disabled entirely with the .Dq disable mppe command. If no arguments are given, .Nm will attempt to negotiate a stateful link with a 128 bit key, but will agree to whatever the peer requests (including no encryption at all). .Pp If any arguments are given, .Nm will .Em insist on using MPPE and will close the link if it is rejected by the peer (Note; this behaviour can be overridden by a configured RADIUS server). .Pp The first argument specifies the number of bits that .Nm should insist on during negotiations and the second specifies whether .Nm should insist on stateful or stateless mode. In stateless mode, the encryption dictionary is re-initialised with every packet according to an encryption key that is changed with every packet. In stateful mode, the encryption dictionary is re-initialised every 256 packets or after the loss of any data and the key is changed every 256 packets. Stateless mode is less efficient but is better for unreliable transport layers. .It set mrru Op Ar value Setting this option enables Multi-link PPP negotiations, also known as Multi-link Protocol or MP. There is no default MRRU (Maximum Reconstructed Receive Unit) value. If no argument is given, multi-link mode is disabled. .It set mru Xo .Op max Ns Op imum .Op Ar value .Xc The default MRU (Maximum Receive Unit) is 1500. If it is increased, the other side *may* increase its MTU. In theory there is no point in decreasing the MRU to below the default as the .Em PPP protocol says implementations *must* be able to accept packets of at least 1500 octets. .Pp If the .Dq maximum keyword is used, .Nm will refuse to negotiate a higher value. The maximum MRU can be set to 2048 at most. Setting a maximum of less than 1500 violates the .Em PPP rfc, but may sometimes be necessary. For example, .Em PPPoE imposes a maximum of 1492 due to hardware limitations. .Pp If no argument is given, 1500 is assumed. A value must be given when .Dq maximum is specified. .It set mtu Xo .Op max Ns Op imum .Op Ar value .Xc The default MTU is 1500. At negotiation time, .Nm will accept whatever MRU the peer requests (assuming it is not less than 296 bytes or greater than the assigned maximum). If the MTU is set, .Nm will not accept MRU values less than .Ar value . When negotiations are complete, the MTU is used when writing to the interface, even if the peer requested a higher value MRU. This can be useful for limiting your packet size (giving better bandwidth sharing at the expense of more header data). .Pp If the .Dq maximum keyword is used, .Nm will refuse to negotiate a higher value. The maximum MTU can be set to 2048 at most. Note, it is necessary to use the .Dq maximum keyword to limit the MTU when using PPPoE. .Pp If no .Ar value is given, 1500, or whatever the peer asks for is used. A value must be given when .Dq maximum is specified. .It set nbns Op Ar x.x.x.x Op Ar y.y.y.y This option allows the setting of the Microsoft NetBIOS name server values to be returned at the peers request. If no values are given, .Nm will reject any such requests. .It set openmode active|passive Op Ar delay By default, .Ar openmode is always .Ar active with a one second .Ar delay . That is, .Nm will always initiate LCP/IPCP/CCP negotiation one second after the line comes up. If you want to wait for the peer to initiate negotiations, you can use the value .Ar passive . If you want to initiate negotiations immediately or after more than one second, the appropriate .Ar delay may be specified here in seconds. .It set parity odd|even|none|mark This allows the line parity to be set. The default value is .Ar none . .It set phone Ar telno Ns Xo .Oo \&| Ns Ar backupnumber Oc Ns ... Ns Oo : Ns Ar nextnumber Oc Ns ... Xc This allows the specification of the phone number to be used in place of the \\\\T string in the dial and login chat scripts. Multiple phone numbers may be given separated either by a pipe .Pq Dq \&| or a colon .Pq Dq \&: . .Pp Numbers after the pipe are only dialed if the dial or login script for the previous number failed. .Pp Numbers after the colon are tried sequentially, irrespective of the reason the line was dropped. .Pp If multiple numbers are given, .Nm will dial them according to these rules until a connection is made, retrying the maximum number of times specified by .Dq set redial below. In .Fl background mode, each number is attempted at most once. .It set pppoe Op standard|3Com This option configures the underlying .Xr ng_pppoe 4 node to either standard RFC2516 PPPoE or proprietary 3Com mode. If not set the system default will be used. .It set Oo proc Oc Ns Xo .No title Op Ar value .Xc The current process title as displayed by .Xr ps 1 is changed according to .Ar value . If .Ar value is not specified, the original process title is restored. All the word replacements done by the shell commands (see the .Dq bg command above) are done here too. .Pp Note, if USER is required in the process title, the .Dq set proctitle command must appear in .Pa ppp.linkup , as it is not known when the commands in .Pa ppp.conf are executed. .It set radius Op Ar config-file This command enables RADIUS support (if it is compiled in). .Ar config-file refers to the radius client configuration file as described in .Xr radius.conf 5 . If PAP, CHAP, MSCHAP or MSCHAPv2 are .Dq enable Ns No d , .Nm behaves as a .Em \&N Ns No etwork .Em \&A Ns No ccess .Em \&S Ns No erver and uses the configured RADIUS server to authenticate rather than authenticating from the .Pa ppp.secret file or from the passwd database. .Pp If none of PAP, CHAP, MSCHAP or MSCHAPv2 are enabled, .Dq set radius will do nothing. .Pp .Nm uses the following attributes from the RADIUS reply: .Bl -tag -width XXX -offset XXX .It RAD_FRAMED_IP_ADDRESS The peer IP address is set to the given value. .It RAD_FRAMED_IP_NETMASK The tun interface netmask is set to the given value. .It RAD_FRAMED_MTU If the given MTU is less than the peers MRU as agreed during LCP negotiation, *and* it is less that any configured MTU (see the .Dq set mru command), the tun interface MTU is set to the given value. .It RAD_FRAMED_COMPRESSION If the received compression type is .Dq 1 , .Nm will request VJ compression during IPCP negotiations despite any .Dq disable vj configuration command. .It RAD_FILTER_ID If this attribute is supplied, .Nm will attempt to use it as an additional label to load from the .Pa ppp.linkup and .Pa ppp.linkdown files. The load will be attempted before (and in addition to) the normal label search. If the label does not exist, no action is taken and .Nm proceeds to the normal load using the current label. .It RAD_FRAMED_ROUTE The received string is expected to be in the format .Ar dest Ns Op / Ns Ar bits .Ar gw .Op Ar metrics . Any specified metrics are ignored. .Dv MYADDR and .Dv HISADDR are understood as valid values for .Ar dest and .Ar gw , .Dq default can be used for .Ar dest to specify the default route, and .Dq 0.0.0.0 is understood to be the same as .Dq default for .Ar dest and .Dv HISADDR for .Ar gw . .Pp For example, a returned value of .Dq 1.2.3.4/24 0.0.0.0 1 2 -1 3 400 would result in a routing table entry to the 1.2.3.0/24 network via .Dv HISADDR and a returned value of .Dq 0.0.0.0 0.0.0.0 or .Dq default HISADDR would result in a default route to .Dv HISADDR . .Pp All RADIUS routes are applied after any sticky routes are applied, making RADIUS routes override configured routes. This also applies for RADIUS routes that do not {include} the .Dv MYADDR or .Dv HISADDR keywords. .It RAD_FRAMED_IPV6_PREFIX If this attribute is supplied, the value is substituted for IPV6PREFIX in a command. You may pass it to an upper layer protocol such as DHCPv6 for delegating an IPv6 prefix to a peer. .It RAD_FRAMED_IPV6_ROUTE The received string is expected to be in the format .Ar dest Ns Op / Ns Ar bits .Ar gw .Op Ar metrics . Any specified metrics are ignored. .Dv MYADDR6 and .Dv HISADDR6 are understood as valid values for .Ar dest and .Ar gw , .Dq default can be used for .Ar dest to specify the default route, and .Dq :: is understood to be the same as .Dq default for .Ar dest and .Dv HISADDR6 for .Ar gw . .Pp For example, a returned value of .Dq 3ffe:505:abcd::/48 :: would result in a routing table entry to the 3ffe:505:abcd::/48 network via .Dv HISADDR6 and a returned value of .Dq :: :: or .Dq default HISADDR6 would result in a default route to .Dv HISADDR6 . .Pp All RADIUS IPv6 routes are applied after any sticky routes are applied, making RADIUS IPv6 routes override configured routes. This also applies for RADIUS IPv6 routes that do not {include} the .Dv MYADDR6 or .Dv HISADDR6 keywords. .It RAD_SESSION_TIMEOUT If supplied, the client connection is closed after the given number of seconds. .It RAD_REPLY_MESSAGE If supplied, this message is passed back to the peer as the authentication SUCCESS text. .It RAD_MICROSOFT_MS_CHAP_ERROR If this .Dv RAD_VENDOR_MICROSOFT vendor specific attribute is supplied, it is passed back to the peer as the authentication FAILURE text. .It RAD_MICROSOFT_MS_CHAP2_SUCCESS If this .Dv RAD_VENDOR_MICROSOFT vendor specific attribute is supplied and if MS-CHAPv2 authentication is being used, it is passed back to the peer as the authentication SUCCESS text. .It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY If this .Dv RAD_VENDOR_MICROSOFT vendor specific attribute is supplied and has a value of 2 (Required), .Nm will insist that MPPE encryption is used (even if no .Dq set mppe configuration command has been given with arguments). If it is supplied with a value of 1 (Allowed), encryption is made optional (despite any .Dq set mppe configuration commands with arguments). .It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES If this .Dv RAD_VENDOR_MICROSOFT vendor specific attribute is supplied, bits 1 and 2 are examined. If either or both are set, 40 bit and/or 128 bit (respectively) encryption options are set, overriding any given first argument to the .Dq set mppe command. Note, it is not currently possible for the RADIUS server to specify 56 bit encryption. .It RAD_MICROSOFT_MS_MPPE_RECV_KEY If this .Dv RAD_VENDOR_MICROSOFT vendor specific attribute is supplied, it is value is used as the master key for decryption of incoming data. When clients are authenticated using MSCHAPv2, the RADIUS server MUST provide this attribute if inbound MPPE is to function. .It RAD_MICROSOFT_MS_MPPE_SEND_KEY If this .Dv RAD_VENDOR_MICROSOFT vendor specific attribute is supplied, it is value is used as the master key for encryption of outgoing data. When clients are authenticated using MSCHAPv2, the RADIUS server MUST provide this attribute if outbound MPPE is to function. .El .Pp Values received from the RADIUS server may be viewed using .Dq show bundle . .It set rad_alive Ar timeout When RADIUS is configured, setting .Dq rad_alive to a non-zero .Ar timeout value will tell .Nm to sent RADIUS accounting information to the RADIUS server every .Ar timeout seconds. .It set rad_port_id Ar option When RADIUS is configured, setting the .Dq rad_port_id value specifies what should be sent to the RADIUS server as NAS-Port-Id. The .Ar option Ns No s are as follows: .Bl -tag -width Ds .It pid PID of the corresponding tunnel. .It tunnum .Xr tun 4 interface number. .It ifnum index of the interface as returned by .Xr if_nametoindex 3 . .It default keeps the default behavior. .El .It set reconnect Ar timeout ntries Should the line drop unexpectedly (due to loss of CD or LQR failure), a connection will be re-established after the given .Ar timeout . The line will be re-connected at most .Ar ntries times. .Ar Ntries defaults to zero. A value of .Ar random for .Ar timeout will result in a variable pause, somewhere between 1 and 30 seconds. .It set recvpipe Op Ar value This sets the routing table RECVPIPE value. The optimum value is just over twice the MTU value. If .Ar value is unspecified or zero, the default kernel controlled value is used. .It set redial Ar secs Ns Xo .Oo + Ns Ar inc Ns .Oo - Ns Ar max Ns Oc Oc Ns .Op . Ns Ar next .Op Ar attempts .Xc .Nm can be instructed to attempt to redial .Ar attempts times. If more than one phone number is specified (see .Dq set phone above), a pause of .Ar next is taken before dialing each number. A pause of .Ar secs is taken before starting at the first number again. A literal value of .Dq Li random may be used here in place of .Ar secs and .Ar next , causing a random delay of between 1 and 30 seconds. .Pp If .Ar inc is specified, its value is added onto .Ar secs each time .Nm tries a new number. .Ar secs will only be incremented at most .Ar max times. .Ar max defaults to 10. .Pp Note, the .Ar secs delay will be effective, even after .Ar attempts has been exceeded, so an immediate manual dial may appear to have done nothing. If an immediate dial is required, a .Dq !\& should immediately follow the .Dq open keyword. See the .Dq open description above for further details. .It set sendpipe Op Ar value This sets the routing table SENDPIPE value. The optimum value is just over twice the MTU value. If .Ar value is unspecified or zero, the default kernel controlled value is used. .It "set server|socket" Ar TcpPort Ns No \&| Ns Xo .Ar LocalName Ns No |none|open|closed .Op password Op Ar mask .Xc This command tells .Nm to listen on the given socket or .Sq diagnostic port for incoming command connections. .Pp The word .Dq none instructs .Nm to close any existing socket and clear the socket configuration. The word .Dq open instructs .Nm to attempt to re-open the port. The word .Dq closed instructs .Nm to close the open port. .Pp If you wish to specify a local domain socket, .Ar LocalName must be specified as an absolute file name, otherwise it is assumed to be the name or number of a TCP port. You may specify the octal umask to be used with a local domain socket. Refer to .Xr umask 2 for umask details. Refer to .Xr services 5 for details of how to translate TCP port names. .Pp You must also specify the password that must be entered by the client (using the .Dq passwd variable above) when connecting to this socket. If the password is specified as an empty string, no password is required for connecting clients. .Pp When specifying a local domain socket, the first .Dq %d sequence found in the socket name will be replaced with the current interface unit number. This is useful when you wish to use the same profile for more than one connection. .Pp In a similar manner TCP sockets may be prefixed with the .Dq + character, in which case the current interface unit number is added to the port number. .Pp When using .Nm with a server socket, the .Xr pppctl 8 command is the preferred mechanism of communications. Currently, .Xr telnet 1 can also be used, but link encryption may be implemented in the future, so .Xr telnet 1 should be avoided. .Pp Note; .Dv SIGUSR1 and .Dv SIGUSR2 interact with the diagnostic socket. .It set speed Ar value This sets the speed of the serial device. If speed is specified as .Dq sync , .Nm treats the device as a synchronous device. .Pp Certain device types will know whether they should be specified as synchronous or asynchronous. These devices will override incorrect settings and log a warning to this effect. .It set stopped Op Ar LCPseconds Op Ar CCPseconds If this option is set, .Nm will time out after the given FSM (Finite State Machine) has been in the stopped state for the given number of .Dq seconds . This option may be useful if the peer sends a terminate request, but never actually closes the connection despite our sending a terminate acknowledgement. This is also useful if you wish to .Dq set openmode passive and time out if the peer does not send a Configure Request within the given time. Use .Dq set log +lcp +ccp to make .Nm log the appropriate state transitions. .Pp The default value is zero, where .Nm does not time out in the stopped state. .Pp This value should not be set to less than the openmode delay (see .Dq set openmode above). .It set timeout Ar idleseconds Op Ar mintimeout This command allows the setting of the idle timer. Refer to the section titled .Sx SETTING THE IDLE TIMER for further details. .Pp If .Ar mintimeout is specified, .Nm will never idle out before the link has been up for at least that number of seconds. .It set urgent Xo .Op tcp|udp|none .Oo Op +|- Ns .Ar port .Oc No ... .Xc This command controls the ports that .Nm prioritizes when transmitting data. The default priority TCP ports are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell), 543 (klogin) and 544 (kshell). There are no priority UDP ports by default. See .Xr services 5 for details. .Pp If neither .Dq tcp or .Dq udp are specified, .Dq tcp is assumed. .Pp If no .Ar port Ns No s are given, the priority port lists are cleared (although if .Dq tcp or .Dq udp is specified, only that list is cleared). If the first .Ar port argument is prefixed with a plus .Pq Dq \&+ or a minus .Pq Dq \&- , the current list is adjusted, otherwise the list is reassigned. .Ar port Ns No s prefixed with a plus or not prefixed at all are added to the list and .Ar port Ns No s prefixed with a minus are removed from the list. .Pp If .Dq none is specified, all priority port lists are disabled and even .Dv IPTOS_LOWDELAY packets are not prioritised. .It set urgent length Ar length This command tells ppp to prioritize small packets up to .Ar length bytes. If .Ar length is not specified, or 0, this feature is disabled. .It set vj slotcomp on|off This command tells .Nm whether it should attempt to negotiate VJ slot compression. By default, slot compression is turned .Ar on . .It set vj slots Ar nslots This command sets the initial number of slots that .Nm will try to negotiate with the peer when VJ compression is enabled (see the .Sq enable command above). It defaults to a value of 16. .Ar Nslots must be between .Ar 4 and .Ar 16 inclusive. .El .It shell|! Op Ar command If .Ar command is not specified a shell is invoked according to the .Dv SHELL environment variable. Otherwise, the given .Ar command is executed. Word replacement is done in the same way as for the .Dq !bg command as described above. .Pp Use of the !\& character requires a following space as with any of the other commands. You should note that this command is executed in the foreground; .Nm will not continue running until this process has exited. Use the .Dv bg command if you wish processing to happen in the background. .It show Ar var This command allows the user to examine the following: .Bl -tag -width 2n .It show bundle Show the current bundle settings. .It show ccp Show the current CCP compression statistics. .It show compress Show the current VJ compression statistics. .It show escape Show the current escape characters. .It show filter Op Ar name List the current rules for the given filter. If .Ar name is not specified, all filters are shown. .It show hdlc Show the current HDLC statistics. .It show help|? Give a summary of available show commands. .It show iface Show the current interface information (the same as .Dq iface show ) . .It show ipcp Show the current IPCP statistics. .It show layers Show the protocol layers currently in use. .It show lcp Show the current LCP statistics. .It show Oo data Oc Ns Xo .No link .Xc Show high level link information. .It show links Show a list of available logical links. .It show log Show the current log values. .It show mem Show current memory statistics. .It show ncp Show the current NCP statistics. .It show physical Show low level link information. .It show mp Show Multi-link information. .It show proto Show current protocol totals. .It show route Show the current routing tables. .It show stopped Show the current stopped timeouts. .It show timer Show the active alarm timers. .It show version Show the current version number of .Nm . .El .It term Go into terminal mode. Characters typed at the keyboard are sent to the device. Characters read from the device are displayed on the screen. When a remote .Em PPP peer is detected, .Nm automatically enables Packet Mode and goes back into command mode. .El .Sh MORE DETAILS .Bl -bullet .It Read the example configuration files. They are a good source of information. .It Use .Dq help , .Dq nat \&? , .Dq enable \&? , .Dq set ?\& and .Dq show ?\& to get online information about what is available. .It The following URL contains useful information: .Bl -bullet -compact .It https://docs.freebsd.org/en/books/handbook/ppp-and-slip/ .El .El .Sh FILES .Nm refers to four files: .Pa ppp.conf , .Pa ppp.linkup , .Pa ppp.linkdown and .Pa ppp.secret . These files are placed in the .Pa /etc/ppp directory. .Bl -tag -width 2n .It Pa /etc/ppp/ppp.conf System default configuration file. .It Pa /etc/ppp/ppp.secret An authorisation file for each system. .It Pa /etc/ppp/ppp.linkup A file to check when .Nm establishes a network level connection. .It Pa /etc/ppp/ppp.linkdown A file to check when .Nm closes a network level connection. .It Pa /var/log/ppp.log Logging and debugging information file. Note, this name is specified in .Pa /etc/syslog.conf . See .Xr syslog.conf 5 for further details. .It Pa /var/spool/lock/LCK..* tty port locking file. Refer to .Xr uucplock 3 for further details. .It Pa /var/run/tunN.pid The process id (pid) of the .Nm program connected to the tunN device, where .Sq N is the number of the device. .It Pa /var/run/ttyXX.if The tun interface used by this port. Again, this file is only created in .Fl background , .Fl auto and .Fl ddial modes. .It Pa /etc/services Get port number if port number is using service name. .It Pa /var/run/ppp-authname-class-value In multi-link mode, local domain sockets are created using the peer authentication name .Pq Sq authname , the peer endpoint discriminator class .Pq Sq class and the peer endpoint discriminator value .Pq Sq value . As the endpoint discriminator value may be a binary value, it is turned to HEX to determine the actual file name. .Pp This socket is used to pass links between different instances of .Nm . .El .Sh SEE ALSO .Xr at 1 , .Xr ftp 1 , .Xr gzip 1 , .Xr hostname 1 , .Xr login 1 , .Xr tcpdump 1 , .Xr telnet 1 , .Xr kldload 2 , .Xr pipe 2 , .Xr socketpair 2 , .Xr libalias 3 , .Xr libradius 3 , .Xr syslog 3 , .Xr uucplock 3 , .Xr netgraph 4 , .Xr ng_pppoe 4 , .Xr crontab 5 , .Xr group 5 , .Xr passwd 5 , .Xr protocols 5 , .Xr radius.conf 5 , .Xr resolv.conf 5 , .Xr syslog.conf 5 , .Xr adduser 8 , .Xr chat 8 , .Xr getty 8 , .Xr inetd 8 , .Xr init 8 , -.Xr named 8 , .Xr ping 8 , .Xr pppctl 8 , .Xr pppoed 8 , .Xr route 8 , .Xr sshd 8 , .Xr syslogd 8 , .Xr traceroute 8 , .Xr vipw 8 .Sh HISTORY This program was originally written by .An Toshiharu OHNO Aq Mt tony-o@iij.ad.jp , and was submitted to .Fx 2.0.5 by .An Atsushi Murai Aq Mt amurai@spec.co.jp . .Pp It was substantially modified during 1997 by .An Brian Somers Aq Mt brian@Awfulhak.org , and was ported to .Ox in November that year (just after the 2.2 release). .Pp Most of the code was rewritten by .An Brian Somers in early 1998 when multi-link ppp support was added.