Index: stable/4/lib/libc/sys/setresuid.2 =================================================================== --- stable/4/lib/libc/sys/setresuid.2 (revision 78135) +++ stable/4/lib/libc/sys/setresuid.2 (revision 78136) @@ -1,84 +1,84 @@ .\" Copyright (c) 2000 .\" Sheldon Hearn. 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 .\" .\" $FreeBSD$ .\" .Dd January 17, 2000 .Dt SETRESUID 2 .Os .Sh NAME .Nm setresgid , .Nm setresuid .Nd set real, effective and saved user or group ID .Sh LIBRARY .Lb libc .Sh SYNOPSIS .Fd #include .Fd #include .Ft int .Fn setresgid "gid_t rgid" "gid_t egid" "gid_t sgid" .Ft int .Fn setresuid "uid_t ruid" "uid_t euid" "uid_t suid" .Sh DESCRIPTION The .Fn setresuid system call sets the real, effective and saved user IDs of the current process. The analogous .Fn setresgid sets the real, effective and saved group IDs. .Pp Privileged processes may set these IDs to arbitrary values. Unprivileged processes are restricted in that each of the new IDs must match one of the current IDs. .Pp Passing -1 as an argument causes the corresponding value to remain unchanged. .Sh RETURN VALUES These functions return the value 0 if successful; otherwise the value -1 is returned and the global variable .Va errno is set to indicate the error. .Sh ERRORS .Bl -tag -width Er .It Bq Er EPERM The calling process was not privileged and tried to change one or more IDs to a value which was not the current real ID, the current effective ID nor the current saved ID. .El .Sh SEE ALSO .Xr getegid 2 , .Xr geteuid 2 , .Xr getgid 2 , .Xr getuid 2 , -.Xr isssetugid 2 , +.Xr issetugid 2 , .Xr setgid 2 , .Xr setregid 2 , .Xr setreuid 2 , .Xr setuid 2 , .Sh STANDARDS These system calls are not available on many platforms. They exist in .Fx to support Linux binaries linked against GNU libc2. .Sh HISTORY These system calls first appeared in HP-UX. Index: stable/4/lib/libnetgraph/netgraph.3 =================================================================== --- stable/4/lib/libnetgraph/netgraph.3 (revision 78135) +++ stable/4/lib/libnetgraph/netgraph.3 (revision 78136) @@ -1,298 +1,298 @@ .\" Copyright (c) 1996-1999 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $FreeBSD$ .\" $Whistle: netgraph.3,v 1.7 1999/01/25 07:14:06 archie Exp $ .\" .Dd January 19, 1999 .Dt NETGRAPH 3 .Os FreeBSD .Sh NAME .Nm NgMkSockNode , .Nm NgNameNode , .Nm NgSendMsg , .Nm NgRecvMsg , .Nm NgSendData , .Nm NgRecvData , .Nm NgSetDebug , .Nm NgSetErrLog .Nd netgraph user library .Sh LIBRARY .Lb libnetgraph .Sh SYNOPSIS .Fd #include .Ft int .Fn NgMkSockNode "const char *name" "int *csp" "int *dsp" .Ft int .Fn NgNameNode "int cs" "const char *path" "const char *fmt" "..." .Ft int .Fn NgSendMsg "int cs" "const char *path" "int cookie" "int cmd" "const void *arg" "size_t arglen" .Ft int .Fn NgSendAsciiMsg "int cs" "const char *path" "const char *fmt" "..." .Ft int .Fn NgSendMsgReply "int cs" "const char *path" "struct ng_mesg *msg" "const void *arg" "size_t arglen" .Ft int .Fn NgRecvMsg "int cs" "struct ng_mesg *rep" "size_t replen" "char *path" .Ft int .Fn NgRecvAsciiMsg "int cs" "struct ng_mesg *rep" "size_t replen" "char *path" .Ft int .Fn NgSendData "int ds" "const char *hook" "const u_char *buf" "size_t len" .Ft int .Fn NgRecvData "int ds" "u_char *buf" "size_t len" "char *hook" .Ft int .Fn NgSetDebug "int level" .Ft void .Fn NgSetErrLog "void (*log)(const char *fmt, ...)" "void (*logx)(const char *fmt, ...)" .Sh DESCRIPTION These functions facilitate user-mode program participation in the kernel .Xr netgraph 4 graph-based networking system, by utilizing the netgraph .Em socket node type (see -.Xr ng_socket 8 ) . +.Xr ng_socket 4 ) . .Pp .Fn NgMkSockNode should be called first, to create a new .Em socket type netgraph node with associated control and data sockets. If .Fa name is non-NULL, the node will have that global name assigned to it. .Fa "*csp" and .Fa "*dsp" will be set to the newly opened control and data sockets associated with the node; either .Fa "csp" or .Fa "dsp" may be NULL if only one socket is desired. .Fn NgMkSockNode loads the socket node type KLD if it's not already loaded. .Pp .Fn NgNameNode assigns a global name to the node addressed by .Fa path . .Pp .Fn NgSendMsg sends a binary control message from the socket node associated with control socket .Fa cs to the node addressed by .Fa path . The .Fa cookie indicates how to interpret .Fa cmd , which indicates a specific command. Extra argument data (if any) is specified by .Fa arg and .Fa arglen . The .Fa cookie , .Fa cmd , and argument data are defined by the header file corresponding to the type of the node being addressed. The unique, non-negative token value chosen for use in the message header is returned. This value is typically used to associate replies. .Pp Use .Fn NgSendMsgReply to send reply to a previously received control message. The original message header should be pointed to by .Fa msg . .Pp .Fn NgSendAsciiMsg performs the same function as .Fn NgSendMsg , but adds support for .Tn ASCII encoding of control messages. .Fn NgSendAsciiMsg formats its input a la .Xr printf 3 and then sends the resulting .Tn ASCII string to the node in a .Dv NGM_ASCII2BINARY control message. The node returns a binary version of the message, which is then sent back to the node just as with .Fn NgSendMsg . As with .Fn NgSendMsg , the message token value is returned. Note that .Tn ASCII conversion may not be supported by all node types. .Pp .Fn NgRecvMsg reads the next control message received by the node associated with control socket .Fa cs . The message and any extra argument data must fit in .Fa replen bytes. If .Fa "path" is non-NULL, it must point to a buffer of at least .Dv "NG_PATHLEN + 1" bytes, which will be filled in (and NUL terminated) with the path to the node from which the message was received. .Pp .Fn NgRecvAsciiMsg works exactly like .Fn NgRecvMsg , except that after the message is received, any binary arguments are converted to .Tn ASCII by sending a .Dv NGM_BINARY2ASCII request back to the originating node. The result is the same as .Fn NgRecvAsciiMsg , with the exception that the reply arguments field will contain a NUL-terminated .Tn ASCII version of the arguments (and the reply header argument length field will be adjusted). .Pp .Fn NgSendData writes a data packet out on the specified hook of the node corresponding to data socket .Fa ds . The node must already be connected to some other node via that hook. .Pp .Fn NgRecvData reads the next data packet (of up to .Fa len bytes) received by the node corresponding to data socket .Fa ds and stores it in .Fa buf , which must be large enough to hold the entire packet. If .Fa "hook" is non-NULL, it must point to a buffer of at least .Dv "NG_HOOKLEN + 1" bytes, which will be filled in (and NUL terminated) with the name of the hook on which the data was received. .Pp .Fn NgSetDebug and .Fn NgSetErrLog are used for debugging. .Fn NgSetDebug sets the debug level (if non-negative), and returns the old setting. Higher debug levels result in more verbosity. The default is zero. All debug and error messages are logged via the functions specified in the most recent call to .Fn NgSetErrLog . The default logging functions are .Xr vwarn 3 and .Xr vwarnx 3 . .Pp At debug level 3, the library attempts to display control message arguments in .Tn ASCII format; however, this results in additional messages being sent which may interfere with debugging. At even higher levels, even these additional messagages will be displayed, etc. .Pp Note that .Xr select 2 can be used on the data and the control sockets to detect the presence of incoming data and control messages, respectively. Data and control packets are always written and read atomically, i.e., in one whole piece. .Pp User mode programs must be linked with the .Dv -lnetgraph flag to link in this library. .Sh INITIALIZATION To enable Netgraph in your kernel, either your kernel must be compiled with .Dq options NETGRAPH in the kernel configuration file, or else the .Xr netgraph 4 and -.Xr ng_socket 8 +.Xr ng_socket 4 KLD modules must have been loaded via .Xr kldload 8 . .Sh DIAGNOSTICS All functions except .Fn NgSetDebug and .Fn NgSetErrLog return -1 if there was an error and set errno accordingly. .Pp For .Fn NgSendAsciiMsg and .Fn NgRecvAsciiMsg , the following additional errors are possible: .Bl -tag -width Er .It Bq Er ENOSYS The node type does not know how to encode or decode the control message. .It Bq Er ERANGE The encoded or decoded arguments were too long for the supplied buffer. .It Bq Er ENOENT An unknown structure field was seen in an .Tn ASCII control message. .It Bq Er EALREADY The same structure field was specified twice in an .Tn ASCII control message. .It Bq Er EINVAL .Tn ASCII control message parse error or illegal value. .It Bq Er E2BIG ASCII control message array or fixed width string buffer overflow. .El .Sh SEE ALSO .Xr socket 2 , .Xr select 2 , .Xr warnx 3 , .Xr netgraph 4 , .Xr ng_socket 4 , .Xr kld 4 .Sh HISTORY The .Nm netgraph system was designed and first implemented at Whistle Communications, Inc. in a version of .Fx 2.2 customized for the Whistle InterJet. .Sh AUTHORS .An Archie Cobbs Aq archie@whistle.com Index: stable/4/libexec/pppoed/pppoed.8 =================================================================== --- stable/4/libexec/pppoed/pppoed.8 (revision 78135) +++ stable/4/libexec/pppoed/pppoed.8 (revision 78136) @@ -1,189 +1,189 @@ .\"- .\" Copyright (c) 1999 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 November 8, 1999 .Dt PPPOED 8 .Os FreeBSD .Sh NAME .Nm pppoed .Nd handle incoming PPP over Ethernet connections .Sh SYNOPSIS .Nm .Op Fl Fd\& .Op Fl P Ar pidfile .Op Fl a Ar name .Op Fl e Ar exec .Op Fl n Ar ngdebug .Op Fl p Ar provider .Ar interface .Sh DESCRIPTION The .Nm program listens to the given .Ar interface for PPP over Ethernet (PPPoE) service request packets, and actions them by negotiating a session then envoking a .Em PPP program. The negotiation is implemented by the .Dq pppoe netgraph node. See -.Xr ng_pppoe 8 +.Xr ng_pppoe 4 for details. .Pp .Nm will only offer services to clients requesting services from the given .Ar provider , which is taken as an empty name if not provided. If a provider name of .Dq \&* is given, any PPPoE requests will be offered service. .Pp The supplied .Ar name will be given as the access concentrator name when establishing the connection. If no .Ar name is given, the current base hostname is used. .Pp After receiving a request (PADI) from the PPPoE netgraph node, .Nm .Xr fork 2 Ns No s a child process and returns to service further requests. The child process offers service .Pq using Ar name and waits for a .Dv SUCCESS indication from the PPPoE node. On receipt of the SUCCESS indication, .Nm will execute .Pp .D1 Ic exec /usr/sbin/ppp -direct Ar provider .Pp as a shell sub-process. It is possible to specify another command using the .Ar exec argument. This is mandatory if .Ar provider is not given. The child process will have standard input and standard output attached to the same .Xr netgraph 4 data socket -.Pq see Xr ng_socket 8 +.Pq see Xr ng_socket 4 when started. .Pp Upon invocation, .Nm will attach a .Dq pppoe netgraph node to the relevant .Dq ether node using .Dq Ar interface Ns No \&: as the node name, and then connect that .Dq pppoe node to a local .Dq socket node. If the .Fl F flag has not been given, .Nm will then go into the background and disassociate itself from the controlling terminal. When the .Fl F flag is given, .Nm stays in the foreground. .Pp If the .Fl d flag is given, additional diagnostics are provided (see the .Sx DIAGNOSTICS section below). If the .Fl n flag is given, .Fn NgSetDebug is called with an argument of .Ar ngdebug . .Pp If .Ar pidfile is given, .Nm will write its process ID to this file on startup. .Sh DIAGNOSTICS After creating the necessary .Xr netgraph 4 nodes as described above, .Nm uses .Xr syslogd 8 to report all incoming connections. If the .Fl d flag is given, .Nm will report on the child processes creation of a new netgraph socket, it's service offer and the invocation of the .Em PPP program. If the .Fl n option is given, netgraph diagnostic messages are also redirected to .Xr syslogd 8 . .Pp It is sometimes useful to add the following to .Pa /etc/syslog.conf : .Pp .Dl !pppoed .Dl "*.* /var/log/pppoed.log .Pp and the following to .Pa /etc/newsyslog.conf : .Pp .Dl "/var/log/pppoed.log 640 3 100 * Z .Pp .Sh SEE ALSO .Xr NgSetDebug 3 , .Xr netgraph 4 , .Xr syslog.conf 5 , -.Xr ng_ether 8 , -.Xr ng_pppoe 8 , -.Xr ng_socket 8 , +.Xr ng_ether 4 , +.Xr ng_pppoe 4 , +.Xr ng_socket 4 , .Xr ppp 8 , .Xr syslogd 8 .Sh BUGS If another netgraph node is using the given interface, .Nm will fail to start. This is because .Xr netgraph 4 does not currently allow node chaining. This may change in the future. .Sh HISTORY The .Nm program was written by .An Brian Somers Aq brian@Awfulhak.org and first appeared in .Fx 3.4 . Index: stable/4/share/man/man4/bpf.4 =================================================================== --- stable/4/share/man/man4/bpf.4 (revision 78135) +++ stable/4/share/man/man4/bpf.4 (revision 78136) @@ -1,749 +1,749 @@ .\" Copyright (c) 1990 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: (1) source code distributions .\" retain the above copyright notice and this paragraph in its entirety, (2) .\" distributions including binary code include the above copyright notice and .\" this paragraph in its entirety in the documentation or other materials .\" provided with the distribution, and (3) all advertising materials mentioning .\" features or use of this software display the following acknowledgement: .\" ``This product includes software developed by the University of California, .\" Lawrence Berkeley Laboratory and its contributors.'' 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 ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" .\" This document is derived in part from the enet man page (enet.4) .\" distributed with 4.3BSD Unix. .\" .\" $FreeBSD$ .\" .Dd January 16, 1996 .Dt BPF 4 .Os BSD 4.4 .Sh NAME .Nm bpf .Nd Berkeley Packet Filter .Sh SYNOPSIS .Cd pseudo-device bpf .Sh DESCRIPTION The Berkeley Packet Filter provides a raw interface to data link layers in a protocol independent fashion. All packets on the network, even those destined for other hosts, are accessible through this mechanism. .Pp The packet filter appears as a character special device, .Pa /dev/bpf0 , .Pa /dev/bpf1 , etc. After opening the device, the file descriptor must be bound to a specific network interface with the .Dv BIOCSETIF ioctl. A given interface can be shared be multiple listeners, and the filter underlying each descriptor will see an identical packet stream. The total number of open files is limited to the value given in the kernel configuration; the example given in the .Sx SYNOPSIS above sets the limit to 16. .Pp A separate device file is required for each minor device. If a file is in use, the open will fail and .Va errno will be set to .Er EBUSY . .Pp Associated with each open instance of a .Nm file is a user-settable packet filter. Whenever a packet is received by an interface, all file descriptors listening on that interface apply their filter. Each descriptor that accepts the packet receives its own copy. .Pp Reads from these files return the next group of packets that have matched the filter. To improve performance, the buffer passed to read must be the same size as the buffers used internally by .Nm . This size is returned by the .Dv BIOCGBLEN ioctl (see below), and can be set with .Dv BIOCSBLEN . Note that an individual packet larger than this size is necessarily truncated. .Pp The packet filter will support any link level protocol that has fixed length headers. Currently, only Ethernet, .Tn SLIP , and .Tn PPP drivers have been modified to interact with .Nm . .Pp Since packet data is in network byte order, applications should use the .Xr byteorder 3 macros to extract multi-byte values. .Pp A packet can be sent out on the network by writing to a .Nm file descriptor. The writes are unbuffered, meaning only one packet can be processed per write. Currently, only writes to Ethernets and .Tn SLIP links are supported. .Sh IOCTLS The .Xr ioctl 2 command codes below are defined in .Aq Pa net/bpf.h . All commands require these includes: .Bd -literal #include #include #include #include .Ed .Pp Additionally, .Dv BIOCGETIF and .Dv BIOCSETIF require .Aq Pa sys/socket.h and .Aq Pa net/if.h . .Pp In addition to .Dv FIONREAD and .Dv SIOCGIFADDR , the following commands may be applied to any open .Nm file. The (third) argument to .Xr ioctl 2 should be a pointer to the type indicated. .Bl -tag -width BIOCGRTIMEOUT .It Dv BIOCGBLEN .Pq Li u_int Returns the required buffer length for reads on .Nm files. .It Dv BIOCSBLEN .Pq Li u_int Sets the buffer length for reads on .Nm files. The buffer must be set before the file is attached to an interface with .Dv BIOCSETIF . If the requested buffer size cannot be accommodated, the closest allowable size will be set and returned in the argument. A read call will result in .Er EIO if it is passed a buffer that is not this size. .It Dv BIOCGDLT .Pq Li u_int Returns the type of the data link layer underlying the attached interface. .Er EINVAL is returned if no interface has been specified. The device types, prefixed with .Dq Li DLT_ , are defined in .Aq Pa net/bpf.h . .It Dv BIOCPROMISC Forces the interface into promiscuous mode. All packets, not just those destined for the local host, are processed. Since more than one file can be listening on a given interface, a listener that opened its interface non-promiscuously may receive packets promiscuously. This problem can be remedied with an appropriate filter. .It Dv BIOCFLUSH Flushes the buffer of incoming packets, and resets the statistics that are returned by BIOCGSTATS. .It Dv BIOCGETIF .Pq Li "struct ifreq" Returns the name of the hardware interface that the file is listening on. The name is returned in the ifr_name field of the .Li ifreq structure. All other fields are undefined. .It Dv BIOCSETIF .Pq Li "struct ifreq" Sets the hardware interface associate with the file. This command must be performed before any packets can be read. The device is indicated by name using the .Li ifr_name field of the .Li ifreq structure. Additionally, performs the actions of .Dv BIOCFLUSH . .It Dv BIOCSRTIMEOUT .It Dv BIOCGRTIMEOUT .Pq Li "struct timeval" Set or get the read timeout parameter. The argument specifies the length of time to wait before timing out on a read request. This parameter is initialized to zero by .Xr open 2 , indicating no timeout. .It Dv BIOCGSTATS .Pq Li "struct bpf_stat" Returns the following structure of packet statistics: .Bd -literal struct bpf_stat { u_int bs_recv; /* number of packets received */ u_int bs_drop; /* number of packets dropped */ }; .Ed .Pp The fields are: .Bl -hang -offset indent .It Li bs_recv the number of packets received by the descriptor since opened or reset (including any buffered since the last read call); and .It Li bs_drop the number of packets which were accepted by the filter but dropped by the kernel because of buffer overflows (i.e., the application's reads aren't keeping up with the packet traffic). .El .It Dv BIOCIMMEDIATE .Pq Li u_int Enable or disable .Dq immediate mode , based on the truth value of the argument. When immediate mode is enabled, reads return immediately upon packet reception. Otherwise, a read will block until either the kernel buffer becomes full or a timeout occurs. This is useful for programs like .Xr rarpd 8 which must respond to messages in real time. The default for a new file is off. .It Dv BIOCSETF .Pq Li "struct bpf_program" Sets the filter program used by the kernel to discard uninteresting packets. An array of instructions and its length is passed in using the following structure: .Bd -literal struct bpf_program { int bf_len; struct bpf_insn *bf_insns; }; .Ed .Pp The filter program is pointed to by the .Li bf_insns field while its length in units of .Sq Li struct bpf_insn is given by the .Li bf_len field. Also, the actions of .Dv BIOCFLUSH are performed. See section .Sx "FILTER MACHINE" for an explanation of the filter language. .It Dv BIOCVERSION .Pq Li "struct bpf_version" Returns the major and minor version numbers of the filter language currently recognized by the kernel. Before installing a filter, applications must check that the current version is compatible with the running kernel. Version numbers are compatible if the major numbers match and the application minor is less than or equal to the kernel minor. The kernel version number is returned in the following structure: .Bd -literal struct bpf_version { u_short bv_major; u_short bv_minor; }; .Ed .Pp The current version numbers are given by .Dv BPF_MAJOR_VERSION and .Dv BPF_MINOR_VERSION from .Aq Pa net/bpf.h . An incompatible filter may result in undefined behavior (most likely, an error returned by .Fn ioctl or haphazard packet matching). .It Dv BIOCSHDRCMPLT .It Dv BIOCGHDRCMPLT .Pq Li u_int Set or get the status of the .Dq header complete flag. Set to zero if the link level source address should be filled in automatically by the the interface output routine. Set to one if the link level source address will be written, as provided, to the wire. This flag is initialized to zero by default. .It Dv BIOCSSEESENT .It Dv BIOCGSEESENT .Pq Li u_int Set or get the flag determining whether locally generated packets on the interface should be returned by BPF. Set to zero to see only incoming packets on the interface. Set to one to see packets originating locally and remotely on the interface. This flag is initialized to one by default. .El .Sh BPF HEADER The following structure is prepended to each packet returned by .Xr read 2 : .Bd -literal struct bpf_hdr { struct timeval bh_tstamp; /* time stamp */ u_long bh_caplen; /* length of captured portion */ u_long bh_datalen; /* original length of packet */ u_short bh_hdrlen; /* length of bpf header (this struct plus alignment padding */ }; .Ed .Pp The fields, whose values are stored in host order, and are: .Pp .Bl -tag -compact -width bh_datalen .It Li bh_tstamp The time at which the packet was processed by the packet filter. .It Li bh_caplen The length of the captured portion of the packet. This is the minimum of the truncation amount specified by the filter and the length of the packet. .It Li bh_datalen The length of the packet off the wire. This value is independent of the truncation amount specified by the filter. .It Li bh_hdrlen The length of the .Nm header, which may not be equal to .\" XXX - not really a function call .Fn sizeof "struct bpf_hdr" . .El .Pp The .Li bh_hdrlen field exists to account for padding between the header and the link level protocol. The purpose here is to guarantee proper alignment of the packet data structures, which is required on alignment sensitive architectures and improves performance on many other architectures. The packet filter insures that the .Li bpf_hdr and the network layer header will be word aligned. Suitable precautions must be taken when accessing the link layer protocol fields on alignment restricted machines. (This isn't a problem on an Ethernet, since the type field is a short falling on an even offset, and the addresses are probably accessed in a bytewise fashion). .Pp Additionally, individual packets are padded so that each starts on a word boundary. This requires that an application has some knowledge of how to get from packet to packet. The macro .Dv BPF_WORDALIGN is defined in .Aq Pa net/bpf.h to facilitate this process. It rounds up its argument to the nearest word aligned value (where a word is .Dv BPF_ALIGNMENT bytes wide). .Pp For example, if .Sq Li p points to the start of a packet, this expression will advance it to the next packet: .Dl p = (char *)p + BPF_WORDALIGN(p->bh_hdrlen + p->bh_caplen) .Pp For the alignment mechanisms to work properly, the buffer passed to .Xr read 2 must itself be word aligned. The .Xr malloc 3 function will always return an aligned buffer. .Sh FILTER MACHINE A filter program is an array of instructions, with all branches forwardly directed, terminated by a .Em return instruction. Each instruction performs some action on the pseudo-machine state, which consists of an accumulator, index register, scratch memory store, and implicit program counter. .Pp The following structure defines the instruction format: .Bd -literal struct bpf_insn { u_short code; u_char jt; u_char jf; u_long k; }; .Ed .Pp The .Li k field is used in different ways by different instructions, and the .Li jt and .Li jf fields are used as offsets by the branch instructions. The opcodes are encoded in a semi-hierarchical fashion. There are eight classes of instructions: .Dv BPF_LD , .Dv BPF_LDX , .Dv BPF_ST , .Dv BPF_STX , .Dv BPF_ALU , .Dv BPF_JMP , .Dv BPF_RET , and .Dv BPF_MISC . Various other mode and operator bits are or'd into the class to give the actual instructions. The classes and modes are defined in .Aq Pa net/bpf.h . .Pp Below are the semantics for each defined .Nm instruction. We use the convention that A is the accumulator, X is the index register, P[] packet data, and M[] scratch memory store. P[i:n] gives the data at byte offset .Dq i in the packet, interpreted as a word (n=4), unsigned halfword (n=2), or unsigned byte (n=1). M[i] gives the i'th word in the scratch memory store, which is only addressed in word units. The memory store is indexed from 0 to .Dv BPF_MEMWORDS - 1. .Li k , .Li jt , and .Li jf are the corresponding fields in the instruction definition. .Dq len refers to the length of the packet. .Pp .Bl -tag -width BPF_STXx .It Dv BPF_LD These instructions copy a value into the accumulator. The type of the source operand is specified by an .Dq addressing mode and can be a constant .Pq Dv BPF_IMM , packet data at a fixed offset .Pq Dv BPF_ABS , packet data at a variable offset .Pq Dv BPF_IND , the packet length .Pq Dv BPF_LEN , or a word in the scratch memory store .Pq Dv BPF_MEM . For .Dv BPF_IND and .Dv BPF_ABS , the data size must be specified as a word .Pq Dv BPF_W , halfword .Pq Dv BPF_H , or byte .Pq Dv BPF_B . The semantics of all the recognized .Dv BPF_LD instructions follow. .Pp .Bl -tag -width "BPF_LD+BPF_W+BPF_IND" -compact .It Li BPF_LD+BPF_W+BPF_ABS A <- P[k:4] .It Li BPF_LD+BPF_H+BPF_ABS A <- P[k:2] .It Li BPF_LD+BPF_B+BPF_ABS A <- P[k:1] .It Li BPF_LD+BPF_W+BPF_IND A <- P[X+k:4] .It Li BPF_LD+BPF_H+BPF_IND A <- P[X+k:2] .It Li BPF_LD+BPF_B+BPF_IND A <- P[X+k:1] .It Li BPF_LD+BPF_W+BPF_LEN A <- len .It Li BPF_LD+BPF_IMM A <- k .It Li BPF_LD+BPF_MEM A <- M[k] .El .It Dv BPF_LDX These instructions load a value into the index register. Note that the addressing modes are more restrictive than those of the accumulator loads, but they include .Dv BPF_MSH , a hack for efficiently loading the IP header length. .Pp .Bl -tag -width "BPF_LDX+BPF_W+BPF_MEM" -compact .It Li BPF_LDX+BPF_W+BPF_IMM X <- k .It Li BPF_LDX+BPF_W+BPF_MEM X <- M[k] .It Li BPF_LDX+BPF_W+BPF_LEN X <- len .It Li BPF_LDX+BPF_B+BPF_MSH X <- 4*(P[k:1]&0xf) .El .It Dv BPF_ST This instruction stores the accumulator into the scratch memory. We do not need an addressing mode since there is only one possibility for the destination. .Pp .Bl -tag -width "BPF_ST" -compact .It Li BPF_ST M[k] <- A .El .It Dv BPF_STX This instruction stores the index register in the scratch memory store. .Pp .Bl -tag -width "BPF_STX" -compact .It Li BPF_STX M[k] <- X .El .It Dv BPF_ALU The alu instructions perform operations between the accumulator and index register or constant, and store the result back in the accumulator. For binary operations, a source mode is required .Po .Dv BPF_K or .Dv BPF_X .Pc . .Pp .Bl -tag -width "BPF_ALU+BPF_MUL+BPF_K" -compact .It Li BPF_ALU+BPF_ADD+BPF_K A <- A + k .It Li BPF_ALU+BPF_SUB+BPF_K A <- A - k .It Li BPF_ALU+BPF_MUL+BPF_K A <- A * k .It Li BPF_ALU+BPF_DIV+BPF_K A <- A / k .It Li BPF_ALU+BPF_AND+BPF_K A <- A & k .It Li BPF_ALU+BPF_OR+BPF_K A <- A | k .It Li BPF_ALU+BPF_LSH+BPF_K A <- A << k .It Li BPF_ALU+BPF_RSH+BPF_K A <- A >> k .It Li BPF_ALU+BPF_ADD+BPF_X A <- A + X .It Li BPF_ALU+BPF_SUB+BPF_X A <- A - X .It Li BPF_ALU+BPF_MUL+BPF_X A <- A * X .It Li BPF_ALU+BPF_DIV+BPF_X A <- A / X .It Li BPF_ALU+BPF_AND+BPF_X A <- A & X .It Li BPF_ALU+BPF_OR+BPF_X A <- A | X .It Li BPF_ALU+BPF_LSH+BPF_X A <- A << X .It Li BPF_ALU+BPF_RSH+BPF_X A <- A >> X .It Li BPF_ALU+BPF_NEG A <- -A .El .It Dv BPF_JMP The jump instructions alter flow of control. Conditional jumps compare the accumulator against a constant .Pq Dv BPF_K or the index register .Pq Dv BPF_X . If the result is true (or non-zero), the true branch is taken, otherwise the false branch is taken. Jump offsets are encoded in 8 bits so the longest jump is 256 instructions. However, the jump always .Pq Dv BPF_JA opcode uses the 32 bit .Li k field as the offset, allowing arbitrarily distant destinations. All conditionals use unsigned comparison conventions. .Pp .Bl -tag -width "BPF_JMP+BPF_KSET+BPF_X" -compact .It Li BPF_JMP+BPF_JA pc += k .It Li BPF_JMP+BPF_JGT+BPF_K pc += (A > k) ? jt : jf .It Li BPF_JMP+BPF_JGE+BPF_K pc += (A >= k) ? jt : jf .It Li BPF_JMP+BPF_JEQ+BPF_K pc += (A == k) ? jt : jf .It Li BPF_JMP+BPF_JSET+BPF_K pc += (A & k) ? jt : jf .It Li BPF_JMP+BPF_JGT+BPF_X pc += (A > X) ? jt : jf .It Li BPF_JMP+BPF_JGE+BPF_X pc += (A >= X) ? jt : jf .It Li BPF_JMP+BPF_JEQ+BPF_X pc += (A == X) ? jt : jf .It Li BPF_JMP+BPF_JSET+BPF_X pc += (A & X) ? jt : jf .El .It Dv BPF_RET The return instructions terminate the filter program and specify the amount of packet to accept (i.e., they return the truncation amount). A return value of zero indicates that the packet should be ignored. The return value is either a constant .Pq Dv BPF_K or the accumulator .Pq Dv BPF_A . .Pp .Bl -tag -width "BPF_RET+BPF_K" -compact .It Li BPF_RET+BPF_A accept A bytes .It Li BPF_RET+BPF_K accept k bytes .El .It Dv BPF_MISC The miscellaneous category was created for anything that doesn't fit into the above classes, and for any new instructions that might need to be added. Currently, these are the register transfer instructions that copy the index register to the accumulator or vice versa. .Pp .Bl -tag -width "BPF_MISC+BPF_TAX" -compact .It Li BPF_MISC+BPF_TAX X <- A .It Li BPF_MISC+BPF_TXA A <- X .El .El .Pp The .Nm interface provides the following macros to facilitate array initializers: .Fn BPF_STMT opcode operand and .Fn BPF_JUMP opcode operand true_offset false_offset . .Pp .Sh EXAMPLES The following filter is taken from the Reverse ARP Daemon. It accepts only Reverse ARP requests. .Bd -literal struct bpf_insn insns[] = { BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_REVARP, 0, 3), BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, REVARP_REQUEST, 0, 1), BPF_STMT(BPF_RET+BPF_K, sizeof(struct ether_arp) + sizeof(struct ether_header)), BPF_STMT(BPF_RET+BPF_K, 0), }; .Ed .Pp This filter accepts only IP packets between host 128.3.112.15 and 128.3.112.35. .Bd -literal struct bpf_insn insns[] = { BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 8), BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 26), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 2), BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 3, 4), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 0, 3), BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 1), BPF_STMT(BPF_RET+BPF_K, (u_int)-1), BPF_STMT(BPF_RET+BPF_K, 0), }; .Ed .Pp Finally, this filter returns only TCP finger packets. We must parse the IP header to reach the TCP header. The .Dv BPF_JSET instruction checks that the IP fragment offset is 0 so we are sure that we have a TCP header. .Bd -literal struct bpf_insn insns[] = { BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 10), BPF_STMT(BPF_LD+BPF_B+BPF_ABS, 23), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, IPPROTO_TCP, 0, 8), BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20), BPF_JUMP(BPF_JMP+BPF_JSET+BPF_K, 0x1fff, 6, 0), BPF_STMT(BPF_LDX+BPF_B+BPF_MSH, 14), BPF_STMT(BPF_LD+BPF_H+BPF_IND, 14), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 2, 0), BPF_STMT(BPF_LD+BPF_H+BPF_IND, 16), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 0, 1), BPF_STMT(BPF_RET+BPF_K, (u_int)-1), BPF_STMT(BPF_RET+BPF_K, 0), }; .Ed .Sh SEE ALSO .Xr tcpdump 1 , .Xr ioctl 2 , .Xr byteorder 3 , -.Xr ng_bpf 8 +.Xr ng_bpf 4 .Rs .%A McCanne, S. .%A Jacobson V. .%T "An efficient, extensible, and portable network monitor" .Re .Sh FILES .Bl -tag -compact -width /dev/bpfXXX .It Pa /dev/bpf Ns Sy n the packet filter device .El .Sh BUGS The read buffer must be of a fixed size (returned by the .Dv BIOCGBLEN ioctl). .Pp A file that does not request promiscuous mode may receive promiscuously received packets as a side effect of another file requesting this mode on the same hardware interface. This could be fixed in the kernel with additional processing overhead. However, we favor the model where all files must assume that the interface is promiscuous, and if so desired, must utilize a filter to reject foreign packets. .Pp Data link protocols with variable length headers are not currently supported. .Sh HISTORY .Pp The Enet packet filter was created in 1980 by Mike Accetta and Rick Rashid at Carnegie-Mellon University. Jeffrey Mogul, at Stanford, ported the code to BSD and continued its development from 1983 on. Since then, it has evolved into the Ultrix Packet Filter at .Tn DEC , a .Tn STREAMS .Tn NIT module under .Tn SunOS 4.1 , and .Tn BPF . .Sh AUTHORS .An -nosplit .An Steven McCanne , of Lawrence Berkeley Laboratory, implemented BPF in Summer 1990. Much of the design is due to .An Van Jacobson . Index: stable/4/share/man/man4/ipsec.4 =================================================================== --- stable/4/share/man/man4/ipsec.4 (revision 78135) +++ stable/4/share/man/man4/ipsec.4 (revision 78136) @@ -1,321 +1,321 @@ .\" $FreeBSD$ .\" $KAME: ipsec.4,v 1.13 2000/06/15 04:08:54 itojun Exp $ .\" .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. .\" 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 project 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 PROJECT 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 PROJECT 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. .\" .Dd January 29, 1999 .Dt IPSEC 4 .Os .Sh NAME .Nm ipsec .Nd IP security protocol .Sh SYNOPSIS .Fd #include .Fd #include .Fd #include .Sh DESCRIPTION .Nm is a security protocol in Internet Protocol layer. .Nm is defined for both IPv4 and IPv6 .Po .Xr inet 4 and .Xr inet6 4 .Pc . .Nm consists of two sub-protocols, namely ESP .Pq encapsulated security payload and AH .Pq authentication header . ESP protects IP payload from wire-tapping by encrypting it by secret key cryptography algorithms. AH guarantees integrity of IP packet and protects it from intermediate alteration or impersonation, by attaching cryptographic checksum computed by one-way hash functions. .Nm has two operation modes: transport mode and tunnel mode. Transport mode is for protecting peer-to-peer commuication between end nodes. Tunnel mode includes IP-in-IP encapsulation operation and is designed for security gateways, like VPN configurations. .\" .Ss Kernel interface .Nm is controlled by key management engine and policy engine, in the operating system kernel. .Pp Key management engine can be accessed from the userland by using .Dv PF_KEY sockets. The .Dv PF_KEY socket API is defined in RFC2367. .Pp Policy engine can be controlled by extended part of .Dv PF_KEY API, .Xr setsockopt 2 operations, and .Xr sysctl 3 interface. The kernel implements extended version of .Dv PF_KEY interface, and allows you to define IPsec policy like per-packet filters. .Xr setsockopt 2 interface is used to define per-socket behavior, and .Xr sysctl 3 interface is used to define host-wide default behavior. .Pp The kernel code does not implement dynamic encryption key exchange protocol like IKE .Pq Internet Key Exchange . That should be implemented as userland programs .Pq usually as daemons , by using the above described APIs. .\" .Ss Policy management The kernel implements experimental policy management code. You can manage the IPsec policy in two ways. One is to configure per-socket policy using -.Xr setsockopt 3 . +.Xr setsockopt 2 . The other is to configure kernel packet filter-based policy using .Dv PF_KEY interface, via .Xr setkey 8 . In both cases, IPsec policy must be specified with syntax described in .Xr ipsec_set_policy 3 . .Pp With -.Xr setsockopt 3 , +.Xr setsockopt 2 , you can define IPsec policy in per-socket basis. You can enforce particular IPsec policy onto packets that go through particular socket. .Pp With .Xr setkey 8 you can define IPsec policy against packets, using sort of packet filtering rule. Refer to .Xr setkey 8 on how to use it. .Pp In the latter case, .Dq Li default policy is allowed for use with .Xr setkey 8 . By configuring policy to .Li default , you can refer system-wide .Xr sysctl 8 variable for default settings. The following variables are available. .Li 1 means .Dq Li use , and .Li 2 means .Dq Li require in the syntax. .Bl -column net.inet6.ipsec6.esp_trans_deflev integerxxx .It Sy "Name Type Changeable" .It "net.inet.ipsec.esp_trans_deflev integer yes" .It "net.inet.ipsec.esp_net_deflev integer yes" .It "net.inet.ipsec.ah_trans_deflev integer yes" .It "net.inet.ipsec.ah_net_deflev integer yes" .It "net.inet6.ipsec6.esp_trans_deflev integer yes" .It "net.inet6.ipsec6.esp_net_deflev integer yes" .It "net.inet6.ipsec6.ah_trans_deflev integer yes" .It "net.inet6.ipsec6.ah_net_deflev integer yes" .El .Pp If kernel finds no matching policy system wide default value is applied. System wide default is specified by the following .Xr sysctl 8 variables. .Li 0 means .Dq Li discard which asks the kernel to drop the packet. .Li 1 means .Dq Li none . .Bl -column net.inet6.ipsec6.def_policy integerxxx .It Sy "Name Type Changeable" .It "net.inet.ipsec.def_policy integer yes" .It "net.inet6.ipsec6.def_policy integer yes" .El .\" .Ss Miscellaneous sysctl variables The following variables are accessible via .Xr sysctl 8 , for tweaking kernel IPsec behavior: .Bl -column net.inet6.ipsec6.inbonud_call_ike integerxxx .It Sy "Name Type Changeable" .It "net.inet.ipsec.ah_cleartos integer yes" .It "net.inet.ipsec.ah_offsetmask integer yes" .It "net.inet.ipsec.dfbit integer yes" .It "net.inet.ipsec.ecn integer yes" .It "net.inet.ipsec.debug integer yes" .It "net.inet6.ipsec6.ecn integer yes" .It "net.inet6.ipsec6.debug integer yes" .El .Pp The variables are interpreted as follows: .Bl -tag -width 6n .It Li ipsec.ah_cleartos If set to non-zero, the kernel clears type-of-service field in the IPv4 header during AH authentication data computation. The variable is for tweaking AH behavior to interoperate with devices that implement RFC1826 AH. It should be set to non-zero .Pq clear the type-of-service field for RFC2402 conformance. .It Li ipsec.ah_offsetmask During AH authentication data computation, the kernel will include 16bit fragment offset field .Pq including flag bits in IPv4 header, after computing logical AND with the variable. The variable is for tweaking AH behavior to interoperate with devices that implement RFC1826 AH. It should be set to zero .Pq clear the fragment offset field during computation for RFC2402 conformance. .It Li ipsec.dfbit The variable configures the kernel behavior on IPv4 IPsec tunnel encapsulation. If set to 0, DF bit on the outer IPv4 header will be cleared. 1 means that the outer DF bit is set regardless from the inner DF bit. 2 means that the DF bit is copied from the inner header to the outer. The variable is supplied to conform to RFC2403 chapter 6.1. .It Li ipsec.ecn If set to non-zero, IPv4 IPsec tunnel encapsulation/decapsulation behavior will be friendly to ECN .Pq explicit congestion notification , as documented in .Li draft-ietf-ipsec-ecn-02.txt . .Xr gif 4 talks more about the behavior. .It Li ipsec.debug If set to non-zero, debug messages will be generated via .Xr syslog 3 . .El .Pp Variables under .Li net.inet6.ipsec6 tree has similar meaning as the .Li net.inet.ipsec counterpart. .\" .Sh PROTOCOLS The .Nm protocol works like plug-in to .Xr inet 4 and .Xr inet6 4 protocols. Therefore, .Nm supports most of the protocols defined upon those IP-layer protocols. Some of the protocols, like .Xr icmp 4 or .Xr icmp6 4 , may behave differently with .Nm . This is because .Nm can prevent .Xr icmp 4 or .Xr icmp6 4 routines from looking into IP payload. .\" .Sh SEE ALSO .Xr ioctl 2 , .Xr socket 2 , .Xr ipsec_set_policy 3 , .Xr icmp6 4 , .Xr intro 4 , .Xr ip6 4 , .Xr setkey 8 , .Xr sysctl 8 .\".Xr racoon 8 .Pp .Sh STANDARDS .Rs .%A Daniel L. McDonald .%A Craig Metz .%A Bao G. Phan .%T "PF_KEY Key Management API, Version 2" .%R RFC .%N 2367 .Re .Pp .Rs .%A "D. L. McDonald" .%T "A Simple IP Security API Extension to BSD Sockets" .%R internet draft .%N "draft-mcdonald-simple-ipsec-api-03.txt" .%O work in progress material .Re .Sh HISTORY The implementation described herein appeared in WIDE/KAME IPv6/IPsec stack. .Sh BUGS The IPsec support is subject to change as the IPsec protocols develop. .Pp There is no single standard for policy engine API, so the policy engine API described herein is just for KAME implementation. .Pp AH tunnel may not work as you might expect. If you configure .Dq require policy against AH tunnel for inbound, tunnelled packets will be rejected. This is because AH authenticates encapsulating .Pq outer packet, not the encapsulated .Pq inner packet. .Pp Under certain condition, truncated result may be raised from the kernel against .Dv SADB_DUMP and .Dv SADB_SPDDUMP operation on .Dv PF_KEY socket. This occurs if there are too many database entries in the kernel and socket buffer for the .Dv PF_KEY socket is insufficient. If you manipulate many IPsec key/policy database entries, increase the size of socket buffer. Index: stable/4/share/man/man4/tty.4 =================================================================== --- stable/4/share/man/man4/tty.4 (revision 78135) +++ stable/4/share/man/man4/tty.4 (revision 78136) @@ -1,402 +1,402 @@ .\" Copyright (c) 1991, 1992, 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. 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. .\" .\" @(#)tty.4 8.3 (Berkeley) 4/19/94 .\" $FreeBSD$ .\" .Dd August 14, 1992 .Dt TTY 4 .Os BSD 4 .Sh NAME .Nm tty .Nd general terminal interface .Sh SYNOPSIS .Fd #include .Sh DESCRIPTION This section describes the interface to the terminal drivers in the system. .Ss Terminal Special Files Each hardware terminal port on the system usually has a terminal special device file associated with it in the directory ``/dev/'' (for example, ``/dev/tty03''). When a user logs into the system on one of these hardware terminal ports, the system has already opened the associated device and prepared the line for normal interactive use (see .Xr getty 8 . ) There is also a special case of a terminal file that connects not to a hardware terminal port, but to another program on the other side. These special terminal devices are called .Em ptys and provide the mechanism necessary to give users the same interface to the system when logging in over a network (using .Xr rlogin 1 , or .Xr telnet 1 for example). Even in these cases the details of how the terminal file was opened and set up is already handled by special software in the system. Thus, users do not normally need to worry about the details of how these lines are opened or used. Also, these lines are often used for dialing out of a system (through an out-calling modem), but again the system provides programs that hide the details of accessing these terminal special files (see .Xr tip 1 ) . .Pp When an interactive user logs in, the system prepares the line to behave in a certain way (called a .Em "line discipline" ) , the particular details of which is described in .Xr stty 1 at the command level, and in .Xr termios 4 at the programming level. A user may be concerned with changing settings associated with his particular login terminal and should refer to the preceding man pages for the common cases. The remainder of this man page is concerned with describing details of using and controlling terminal devices at a low level, such as that possibly required by a program wishing to provide features similar to those provided by the system. .Ss Line disciplines A terminal file is used like any other file in the system in that it can be opened, read, and written to using standard system calls. For each existing terminal file, there is a software processing module called a .Em "line discipline" is associated with it. The .Em "line discipline" essentially glues the low level device driver code with the high level generic interface routines (such as .Xr read 2 and .Xr write 2 ) , and is responsible for implementing the semantics associated with the device. When a terminal file is first opened by a program, the default .Em "line discipline" called the .Dv termios line discipline is associated with the file. This is the primary line discipline that is used in most cases and provides the semantics that users normally associate with a terminal. When the .Dv termios line discipline is in effect, the terminal file behaves and is operated according to the rules described in .Xr termios 4 . Please refer to that man page for a full description of the terminal semantics. The operations described here generally represent features common across all .Em "line disciplines" , however some of these calls may not make sense in conjunction with a line discipline other than .Dv termios , and some may not be supported by the underlying hardware (or lack thereof, as in the case of ptys). .Ss Terminal File Operations All of the following operations are invoked using the .Xr ioctl 2 system call. Refer to that man page for a description of the .Em request and .Em argp parameters. In addition to the ioctl .Em requests defined here, the specific line discipline in effect will define other .Em requests specific to it (actually .Xr termios 4 defines them as function calls, not ioctl .Em requests . ) The following section lists the available ioctl requests. The name of the request, a description of its purpose, and the typed .Em argp parameter (if any) are listed. For example, the first entry says .Pp .D1 Em "TIOCSETD int *ldisc" .Pp and would be called on the terminal associated with file descriptor zero by the following code fragment: .Bd -literal int ldisc; ldisc = TTYDISC; ioctl(0, TIOCSETD, &ldisc); .Ed .Ss Terminal File Request Descriptions .Bl -tag -width TIOCGWINSZ .It Dv TIOCSETD Fa int *ldisc Change to the new line discipline pointed to by .Fa ldisc . The available line disciplines are listed in .Aq Pa sys/ttycom.h and currently are: .Pp .Bl -tag -width NETGRAPHDISC -compact .It TTYDISC Termios interactive line discipline. .It TABLDISC Tablet line discipline. .It SLIPDISC Serial IP line discipline. .It PPPDISC PPP line discipline. .It NETGRAPHDISC Netgraph -.Xr ng_tty 8 +.Xr ng_tty 4 line discipline. .El .Pp .It Dv TIOCGETD Fa int *ldisc Return the current line discipline in the integer pointed to by .Fa ldisc . .It Dv TIOCSBRK Fa void Set the terminal hardware into BREAK condition. .It Dv TIOCCBRK Fa void Clear the terminal hardware BREAK condition. .It Dv TIOCSDTR Fa void Assert data terminal ready (DTR). .It Dv TIOCCDTR Fa void Clear data terminal ready (DTR). .It Dv TIOCGPGRP Fa int *tpgrp Return the current process group the terminal is associated with in the integer pointed to by .Fa tpgrp . This is the underlying call that implements the .Xr termios 4 .Fn tcgetattr call. .It Dv TIOCSPGRP Fa int *tpgrp Associate the terminal with the process group (as an integer) pointed to by .Fa tpgrp . This is the underlying call that implements the .Xr termios 4 .Fn tcsetattr call. .It Dv TIOCGETA Fa struct termios *term Place the current value of the termios state associated with the device in the termios structure pointed to by .Fa term . This is the underlying call that implements the .Xr termios 4 .Fn tcgetattr call. .It Dv TIOCSETA Fa struct termios *term Set the termios state associated with the device immediately. This is the underlying call that implements the .Xr termios 4 .Fn tcsetattr call with the .Dv TCSANOW option. .It Dv TIOCSETAW Fa struct termios *term First wait for any output to complete, then set the termios state associated with the device. This is the underlying call that implements the .Xr termios 4 .Fn tcsetattr call with the .Dv TCSADRAIN option. .It Dv TIOCSETAF Fa struct termios *term First wait for any output to complete, clear any pending input, then set the termios state associated with the device. This is the underlying call that implements the .Xr termios 4 .Fn tcsetattr call with the .Dv TCSAFLUSH option. .It Dv TIOCOUTQ Fa int *num Place the current number of characters in the output queue in the integer pointed to by .Fa num . .It Dv TIOCSTI Fa char *cp Simulate typed input. Pretend as if the terminal received the character pointed to by .Fa cp . .It Dv TIOCNOTTY Fa void This call is obsolete but left for compatibility. In the past, when a process that didn't have a controlling terminal (see .Em The Controlling Terminal in .Xr termios 4 ) first opened a terminal device, it acquired that terminal as its controlling terminal. For some programs this was a hazard as they didn't want a controlling terminal in the first place, and this provided a mechanism to disassociate the controlling terminal from the calling process. It .Em must be called by opening the file .Pa /dev/tty and calling .Dv TIOCNOTTY on that file descriptor. .Pp The current system does not allocate a controlling terminal to a process on an .Fn open call: there is a specific ioctl called .Dv TIOSCTTY to make a terminal the controlling terminal. In addition, a program can .Fn fork and call the .Fn setsid system call which will place the process into its own session - which has the effect of disassociating it from the controlling terminal. This is the new and preferred method for programs to lose their controlling terminal. .It Dv TIOCSTOP Fa void Stop output on the terminal (like typing ^S at the keyboard). .It Dv TIOCSTART Fa void Start output on the terminal (like typing ^Q at the keyboard). .It Dv TIOCSCTTY Fa void Make the terminal the controlling terminal for the process (the process must not currently have a controlling terminal). .It Dv TIOCDRAIN Fa void Wait until all output is drained. .It Dv TIOCEXCL Fa void Set exclusive use on the terminal. No further opens are permitted except by root. Of course, this means that programs that are run by root (or setuid) will not obey the exclusive setting - which limits the usefulness of this feature. .It Dv TIOCNXCL Fa void Clear exclusive use of the terminal. Further opens are permitted. .It Dv TIOCFLUSH Fa int *what If the value of the int pointed to by .Fa what contains the .Dv FREAD bit as defined in .Aq Pa sys/file.h , then all characters in the input queue are cleared. If it contains the .Dv FWRITE bit, then all characters in the output queue are cleared. If the value of the integer is zero, then it behaves as if both the .Dv FREAD and .Dv FWRITE bits were set (i.e. clears both queues). .It Dv TIOCGWINSZ Fa struct winsize *ws Put the window size information associated with the terminal in the .Va winsize structure pointed to by .Fa ws . The window size structure contains the number of rows and columns (and pixels if appropriate) of the devices attached to the terminal. It is set by user software and is the means by which most full\&-screen oriented programs determine the screen size. The .Va winsize structure is defined in .Aq Pa sys/ioctl.h . .It Dv TIOCSWINSZ Fa struct winsize *ws Set the window size associated with the terminal to be the value in the .Va winsize structure pointed to by .Fa ws (see above). .It Dv TIOCCONS Fa int *on If .Fa on points to a non-zero integer, redirect kernel console output (kernel printf's) to this terminal. If .Fa on points to a zero integer, redirect kernel console output back to the normal console. This is usually used on workstations to redirect kernel messages to a particular window. .It Dv TIOCMSET Fa int *state The integer pointed to by .Fa state contains bits that correspond to modem state. Following is a list of defined variables and the modem state they represent: .Pp .Bl -tag -width TIOCMXCTS -compact .It TIOCM_LE Line Enable. .It TIOCM_DTR Data Terminal Ready. .It TIOCM_RTS Request To Send. .It TIOCM_ST Secondary Transmit. .It TIOCM_SR Secondary Receive. .It TIOCM_CTS Clear To Send. .It TIOCM_CAR Carrier Detect. .It TIOCM_CD Carrier Detect (synonym). .It TIOCM_RNG Ring Indication. .It TIOCM_RI Ring Indication (synonym). .It TIOCM_DSR Data Set Ready. .El .Pp This call sets the terminal modem state to that represented by .Fa state . Not all terminals may support this. .It Dv TIOCMGET Fa int *state Return the current state of the terminal modem lines as represented above in the integer pointed to by .Fa state . .It Dv TIOCMBIS Fa int *state The bits in the integer pointed to by .Fa state represent modem state as described above, however the state is OR-ed in with the current state. .It Dv TIOCMBIC Fa int *state The bits in the integer pointed to by .Fa state represent modem state as described above, however each bit which is on in .Fa state is cleared in the terminal. .El .Sh SEE ALSO .Xr stty 1 , .Xr ioctl 2 , .Xr pty 4 , .Xr termios 4 , -.Xr ng_tty 8 , +.Xr ng_tty 4 , .Xr getty 8 Index: stable/4/share/man/man5/rc.conf.5 =================================================================== --- stable/4/share/man/man5/rc.conf.5 (revision 78135) +++ stable/4/share/man/man5/rc.conf.5 (revision 78136) @@ -1,1585 +1,1585 @@ .\" Copyright (c) 1995 .\" Jordan K. Hubbard .\" .\" 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 ``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 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 February 4, 2001 .Dt RC.CONF 5 .Os .Sh NAME .Nm rc.conf .Nd system configuration information. .Sh DESCRIPTION The file .Nm contains descriptive information about the local host name, configuration details for any potential network interfaces and which services should be started up at system initial boot time. In new installations, the .Nm file is generally initialized by the system installation utility: .Pa /stand/sysinstall . .Pp The purpose of .Nm is not to run commands or perform system startup actions directly. Instead, it is included by the various generic startup scripts in .Pa /etc which conditionalize their internal actions according to the settings found there. .Pp The .Pa /etc/rc.conf file is included from the file .Pa /etc/defaults/rc.conf , which specifies the default settings for all the available options. Options need only be specified in .Pa /etc/rc.conf when the system administrator wishes to override these defaults. The file .Pa /etc/rc.conf.local is used to override settings in .Pa /etc/rc.conf for historical reasons. See the .Dq rc_conf_files option below. .Pp The following list provides a name and short description for each variable you can set in the .Nm file: .Bl -tag -width Ar .It Ar swapfile (str) If set to .Ar NO then no swapfile is installed, otherwise the value is used as the full pathname to a file to use for additional swap space. .It Ar apm_enable (bool) If set to .Ar YES , enable support for Automatic Power Management with the .Xr apm 8 command. .It Ar apmd_enable (bool) Run .Xr apmd 8 to handle APM event from userland. This also enable support for APM. .It Ar apmd_flags (str) If .Ar apmd_enable is set to .Ar YES , these are the flags to pass to the .Xr apmd 8 daemon. .It Ar pccard_enable (bool) If set to .Ar YES , enable PCCARD support at boot time. .It Ar pccard_mem (str) Set to PCCARD controller memory address or .Ar DEFAULT for the default value. .It Ar pccard_ifconfig (str) List of arguments to be passed to ifconfig(8) at boot time or on insertion of of the card (e.g. "inet 192.168.1.1 netmask 255.255.255.0" for a fixed address or "DHCP" for a DHCP client). .It Ar pccard_beep (integer) If 0, set the PCCARD controller to silent mode. If 1, set it to beep mode. If 2, set it to melody mode. .It Ar pccard_conf (str) Path to the configuration file for the .Xr pccardd 8 daemon (e.g. .Pa /etc/pccard.conf.sample ) . .It Ar pccardd_flags (str) If .Ar pccard_enable is set to .Ar YES , these are the flags to pass to the .Xr pccardd 8 daemon. .It Ar local_startup (str) List of directories to search for startup script files. .It Ar hostname (str) The Fully Qualified Domain Name of your host on the network. This should almost certainly be set to something meaningful, even if you are not connected to a network. If you are using .Xr dhclient 8 to set your hostname via DHCP, this variable should be set to an empty string. .It Ar nisdomainname (str) The NIS domainname of your host, or .Ar NO if you are not running NIS. .It Ar dhcp_program (str) Path to the DHCP client program .Po .Pa /sbin/dhclient , the ISC DHCP client, is the default .Pc . .It Ar dhcp_flags (str) Additional flags to pass to the DHCP client program. For the ISC DHCP client, see the .Xr dhclient 8 page for a description of the command line options available. .It Ar firewall_enable (bool) Set to .Ar NO if you do not want have firewall rules loaded at startup, or .Ar YES if you do. If set to .Ar YES , and the kernel was not built with IPFIREWALL, the ipfw kernel module will be loaded. See also .Ar ipfilter_enable . .It Ar firewall_script (str) If you want to run a firewall script other than .Pa /etc/rc.firewall , set this variable to the full path to that script. .It Ar firewall_type (str) Names the firewall type from the selection in .Pa /etc/rc.firewall , or the file which contains the local firewall ruleset. Valid selections from .Pa /etc/rc.firewall , are .Dq open - unrestricted IP access; .Dq closed - all IP services disabled, except via lo0; .Dq client - basic protection for a workstation; .Dq simple - basic protection for a LAN. If a filename is specified, the full path must be given. .It Ar firewall_quiet (bool) Set to .Ar YES to disable the display of ipfw rules on the console during boot. .It Ar firewall_logging (bool) Set to .Ar YES to enable ipfw event logging. This is equivalent to the IPFIREWALL_VERBOSE kernel option. .It Ar natd_program (str) path to .Xr natd 8 . .It Ar natd_enable (bool) Set to .Ar YES to enable natd. .Ar Firewall_enable must also be set to .Ar YES , and .Xr divert 4 sockets must be enabled in your kernel. .It Ar natd_interface This is the name of the public interface on which natd should run. It is mandatory if .Ar natd_enable is set to .Ar YES . The interface may be given as an interface name or as an IP address. .It Ar natd_flags Additional natd flags should be placed here. The .Fl n or .Fl a flag is automatically added with the above .Ar natd_interface as an argument. .\" ----- ipfilter_enable seting -------------------------------- .It Ar ipfilter_enable (bool) Set to .Ar NO by default. Setting this to .Ar YES enables .Xr ipf 8 packet filtering. Strictly speaking almost any filter could be established "abusing" this setting and the fact that .Ar ipfilter_program , .Ar ipfilter_rules and .Ar ipfilter_flags are concatenated to form a command, as long as the file specified in .Ar ipfilter_rules is readable. When .Ar ipfilter_enable and .Ar ipnat_enable are set to .Ar YES and the file specified in .Ar ipnat_rules is readable, .Ar ipnat_program , .Ar ipnat_rules and .Ar ipnat_flags make up a command line to start a network address translation program. When .Ar ipfilter_enable and .Ar ipmon_enable are set to .Ar YES , .Ar ipmon_program and .Ar ipmon_flags form another command line for monitoring the above actions. See .Pa /etc/rc.network for details. .Pp Typical usage will require putting .Bd -literal ipfilter_enable="YES" ipfilter_flags="" ipnat_enable="YES" ipmon_enable="YES" .Ed into .Pa /etc/rc.conf and editing .Pa /etc/ipf.rules and .Pa /etc/ipnat.rules appropriately. Turning off .Ar firewall_enable when using ipf is recommended. Having .Bd -literal options IPFILTER options IPFILTER_LOG options IPFILTER_DEFAULT_BLOCK .Ed in the kernel configuration file is a good idea, too. .\" ----- ipfilter_program setting ------------------------------ .It Ar ipfilter_program (str) Set to .Ar /sbin/ipf -Fa -f by default. This variable contains a command line up to (but not including) the filter rule definition (expected to live in a separate file). See .Ar ipfilter_enable for a detailled discussion. .\" ----- ipfilter_rules setting -------------------------------- .It Ar ipfilter_rules (str) Set to .Ar /etc/ipf.rules by default. This variable contains the name of the filter rule definition file. The file is expected to be readable for the filter command to execute. See .Ar ipfilter_enable for a detailled discussion. .\" ----- ipfilter_flags setting -------------------------------- .It Ar ipfilter_flags (str) Set to .Ar -E by default. This variable contains flags appended to the filter command after the rule definition filename. The default setting will initialize an on demand loaded ipf module. When compiling ipfilter directly into your kernel (as is recommended) the variable should be empty to not initialize the code more than once. See .Ar ipfilter_enable for a detailled discussion. .\" ----- ipnat_enable setting ---------------------------------- .It Ar ipnat_enable (bool) Set to .Ar NO by default. Set it to .Ar YES to enable -.Xr ipnat 8 +.Xr ipnat 1 network address translation. Setting this variable needs setting .Ar ipfilter_enable , too. See .Ar ipfilter_enable for a detailled discussion. .\" ----- ipnat_program setting --------------------------------- .It Ar ipnat_program (str) Set to .Ar /sbin/ipnat -CF -f by default. This variable contains a command line up to (but not including) the translation rule definition (expected to live in a separate file). See .Ar ipfilter_enable for a detailled discussion. .\" ----- ipnat_rules setting ----------------------------------- .It Ar ipnat_rules (str) Set to .Ar /etc/ipnat.rules by default. This variable contains the name of the file holding the network address translation definition. This file is expected to be readable for the NAT command to execute. See .Ar ipfilter_enable for a detailled discussion. .\" ----- ipnat_flags setting ----------------------------------- .It Ar ipnat_flags (str) Empty by default. This variable contains additional flags appended to the ipnat command line after the rule definition filename. See .Ar ipfilter_enable for a detailled discussion. .\" ----- ipmon_enable setting ---------------------------------- .It Ar ipmon_enable (bool) Set to .Ar NO by default. Set it to .Ar YES to enable .Xr ipmon 8 monitoring (logging .Xr ipf 8 and -.Xr ipnat 8 +.Xr ipnat 1 events). Setting this variable needs setting .Ar ipfilter_enable , too. See .Ar ipfilter_enable for a detailled discussion. .\" ----- ipmon_program setting --------------------------------- .It Ar ipmon_program (str) Set to .Ar /sbin/ipmon by default. This variable contains the .Xr ipmon 8 executable filename. See .Ar ipfilter_enable for a detailled discussion. .\" ----- ipmon_flags setting ----------------------------------- .It Ar ipmon_flags (str) Set to .Ar -Ds by default. This variable contains flags passed to the .Xr ipmon 8 program. Another typical example would be .Ar -D /var/log/ipflog to have .Xr ipmon 8 log directly to a file bypassing .Xr syslogd 8 . Make sure to adjust .Pa /etc/newsyslog.conf in such case like this: .Bd -literal /var/log/ipflog 640 10 100 * Z /var/run/ipmon.pid .Ed See .Ar ipfilter_enable for a detailled discussion. .\" ----- end of added ipf hook --------------------------------- .It Ar tcp_extensions (bool) Set to .Ar YES by default. Setting this to NO disables certain TCP options as described by .Rs .%T RFC 1323 .Re If you have problems with connections randomly hanging or other weird behavior of such nature, you might try setting this to .Ar NO and seeing if that helps. Some hardware/software out there is known to be broken with respect to these options. .It Ar log_in_vain (bool) Set to .Ar NO by default. Setting to YES will enable logging of connection attempts to ports that have no listening socket on them. .It Ar tcp_keepalive (bool) Set to .Ar YES by default. Setting to NO will disable probing idle TCP connections to verify that the peer is still up and reachable. .It Ar tcp_drop_synfin (bool) Set to .Ar NO by default. Setting to YES will cause the kernel to ignore TCP frames that have both the SYN and FIN flags set. This prevents OS fingerprinting, but may break some legitimate applications. This option is only available if the kernel was built with the TCP_DROP_SYNFIN option. .It Ar icmp_drop_redirect (bool) Set to .Ar NO by default. Setting to YES will cause the kernel to ignore ICMP REDIRECT packets. .It Ar icmp_log_redirect (bool) Set to .Ar NO by default. Setting to YES will cause the kernel to log ICMP REDIRECT packets. Note that the log messages are not rate-limited, so this option should only be used for troubleshooting your own network. .It Ar network_interfaces (str) Set to the list of network interfaces to configure on this host. For example, if you had a loopback device (standard) and an SMC Elite Ultra NIC, you might have this set to .Qq Ar "lo0 ed0" for the two interfaces. An .No ifconfig_ Ns Em interface variable is also assumed to exist for each value of .Em interface . It is also possible to add IP alias entries here in cases where you want a single interface to have multiple IP addresses registered against it. Assuming that the interface in question was ed0, it might look something like this: .Bd -literal ifconfig_ed0_alias0="inet 127.0.0.253 netmask 0xffffffff" ifconfig_ed0_alias1="inet 127.0.0.254 netmask 0xffffffff" .Ed And so on. For each ifconfig__alias entry that is found, its contents are passed to .Xr ifconfig 8 . Execution stops at the first unsuccessful access, so if you had something like: .Bd -literal ifconfig_ed0_alias0="inet 127.0.0.251 netmask 0xffffffff" ifconfig_ed0_alias1="inet 127.0.0.252 netmask 0xffffffff" ifconfig_ed0_alias2="inet 127.0.0.253 netmask 0xffffffff" ifconfig_ed0_alias4="inet 127.0.0.254 netmask 0xffffffff" .Ed Then note that alias4 would .Em not be added since the search would stop with the missing alias3 entry. .Pp You can bring up an interface with DHCP by setting the .No ifconfig_ Ns Em interface variable to .Dq DHCP . For instance, to initialize your ed0 device via DHCP, you might have something like: .Bd -literal ifconfig_ed0="DHCP" .Ed .It Ar ppp_enable (bool) If set to .Ar YES , run the .Xr ppp 8 daemon. .It Ar ppp_mode (str) Mode in which to run the .Xr ppp 8 daemon. Accepted modes are .Ar auto , ddial , direct and .Ar dedicated . See the manual for a full description. .It Ar ppp_nat (bool) If set to .Ar YES , enables packet aliasing. Used in conjunction with .Ar gateway_enable allows hosts on private network addresses access to the Internet using this host as a network address translating router. .It Ar ppp_profile (str) The name of the profile to use from .Pa /etc/ppp/ppp.conf . .It Ar ppp_user (str) The name of the user under which ppp should be started. By default, ppp is started as .Ar root . .It Ar rc_conf_files (str) This option is used to specify a list of files that will override the settings in .Pa /etc/defaults/rc.conf . The files will be read in the order in which they are specified and should include the full path to the file. By default, the files specified are .Pa /etc/rc.conf and .Pa /etc/rc.conf.local .It Ar fsck_y_enable (bool) if set to .Ar YES , .Xr fsck 8 will be run with the -y flag if the initial preen of the filesystems fails. .It Ar syslogd_enable (bool) If set to .Ar YES , run the .Xr syslogd 8 daemon. .It Ar syslogd_flags (str) if syslogd_enable is set to .Ar YES , these are the flags to pass to .Xr syslogd 8 . .It Ar inetd_enable (bool) If set to .Ar YES , run the .Xr inetd 8 daemon. .It Ar inetd_flags (str) if inetd_enable is set to .Ar YES , these are the flags to pass to .Xr inetd 8 . .It Ar named_enable (bool) If set to .Ar YES , run the .Xr named 8 daemon. .It Ar named_program (str) path to .Xr named 8 (default .Pa /usr/sbin/named ) . .It Ar named_flags (str) if .Ar named_enable is set to .Ar YES , these are the flags to pass to .Xr named 8 . .It Ar kerberos_server_enable (bool) Set to .Ar YES if you want to run a Kerberos authentication server at boot time. .It Ar kadmind_server_enable .Ar YES if you want to run .Xr kadmind 8 the Kerberos Administration Daemon); set to .Ar NO on a slave server. .It Ar kerberos_stash (str) If .Ar YES , instruct the Kerberos servers to use the stashed master key instead of prompting for it (only if .Ar kerberos_server_enable is set to .Ar YES , and is used for both .Xr kerberos 1 and .Xr kadmind 8 ) . .It Ar rwhod_enable (bool) If set to .Ar YES , run the .Xr rwhod 8 daemon at boot time. .It Ar rwhod_flags (str) If .Ar rwhod_enable is set to .Ar YES , these are the flags to pass to it. .It Ar amd_enable (bool) If set to .Ar YES , run the .Xr amd 8 daemon at boot time. .It Ar amd_flags (str) If .Ar amd_enable is set to .Ar YES , these are the flags to pass to it. See the .Xr amd 8 .Xr info 1 page for more information. .It Ar update_motd (bool) If set to .Ar YES , .Pa /etc/motd will be updated at boot time to reflect the kernel release bring run. If set to .Ar NO , .Pa /etc/motd will not be updated .It Ar nfs_client_enable (bool) If set to .Ar YES , run the NFS client daemons at boot time. .It Ar nfs_client_flags (str) If .Ar nfs_client_enable is set to .Ar YES , these are the flags to pass to the .Xr nfsiod 8 daemon. .It Ar nfs_access_cache if .Ar nfs_client_enable is set to .Ar YES , this can be set to .Ar 0 to disable NFS ACCESS RPC caching, or to the number of seconds for which NFS ACCESS results should be cached. A value of 2-10 seconds will substantially reduce network traffic for many NFS operations. .It Ar nfs_server_enable (bool) If set to .Ar YES , run the NFS server daemons at boot time. .It Ar nfs_server_flags (str) If .Ar nfs_server_enable is set to .Ar YES , these are the flags to pass to the .Xr nfsd 8 daemon. .It Ar single_mountd_enable (bool) If set to .Ar YES , and no .Ar nfs_server_enable is set, start .Xr mountd 8 , but not .Xr nfsd 8 daemon. It is commonly needed to run CFS without real NFS used. .It Ar weak_mountd_authentication (bool) If set to .Ar YES , allow services like PCNFSD to make non-privileged mount requests. .It Ar nfs_privport (bool) If set to .Ar YES , provide NFS services only on a secure port. .It Ar nfs_bufpackets (integer) If set to a number, indicates the number of packets worth of socket buffer space to reserve on an NFS client. If set to .Ar DEFAULT , the kernel default is used (typically 4). Using a higher number may be useful on gigabit networks to improve performance. The minimum value is 2 and the maximum is 64. .It Ar rpc_lockd_enable (bool) If set to .Ar YES and also an NFS server, run .Xr rpc.lockd 8 at boot time. .It Ar rpc_statd_enable (bool) If set to .Ar YES and also an NFS server, run .Xr rpc.statd 8 at boot time. .It Ar portmap_program (str) path to .Xr portmap 8 (default .Pa /usr/sbin/portmap ) . .It Ar portmap_enable (bool) If set to .Ar YES , run the .Xr portmap 8 service at boot time. .It Ar portmap_flags (str) If .Ar portmap_enable is set to .Ar YES , these are the flags to pass to the .Xr portmap 8 daemon. .It Ar xtend_enable (bool) If set to .Ar YES then run the .Xr xtend 8 daemon at boot time. .It Ar xtend_flags (str) If .Ar xtend_enable is set to .Ar YES , these are the flags to pass to the .Xr xtend 8 daemon. .It Ar pppoed_enable (bool) If set to .Ar YES then run the .Xr pppoed 8 daemon at boot time to provide PPP over Ethernet services. .It Ar pppoed_provider .Xr pppoed 8 listens to requests to this .Ar provider and ultimately runs .Xr ppp 8 with a .Ar system argument of the same name. .It Ar pppoed_flags Additional flags to pass to .Xr pppoed 8 . .It Ar pppoed_interface The network interface to run pppoed on. This is mandatory when .Ar pppoed_enable is set to .Dq YES . .It Ar timed_enable (boot) if .Ar YES then run the .Xr timed 8 service at boot time. This command is intended for networks of machines where a consistent .Qq "network time" for all hosts must be established. This is often useful in large NFS environments where time stamps on files are expected to be consistent network-wide. .It Ar timed_flags (str) If .Ar timed_enable is set to .Ar YES , these are the flags to pass to the .Xr timed 8 service. .It Ar ntpdate_enable (bool) If set to .Ar YES , run ntpdate at system startup. This command is intended to synchronize the system clock only .Ar once from some standard reference. An option to set this up initially (from a list of known servers) is also provided by the .Pa /stand/sysinstall program when the system is first installed. .It Ar ntpdate_program (str) path to .Xr ntpdate 8 (default .Pa /usr/sbin/ntpdate ) . .It Ar ntpdate_flags (str) If .Ar ntpdate_enable is set to .Ar YES , these are the flags to pass to the .Xr ntpdate 8 command (typically a hostname). .It Ar xntpd_enable (bool) If set to .Ar YES then run the .Xr xntpd 8 command at boot time. .It Ar xntpd_program (str) path to .Xr xntpd 8 (default .Pa /usr/sbin/xntpd ) . .It Ar xntpd_flags (str) If .Ar xntpd_enable is set to .Ar YES , these are the flags to pass to the .Xr xntpd 8 daemon. .It Ar nis_client_enable (bool) If set to .Ar YES then run the .Xr ypbind 8 service at system boot time. .It Ar nis_client_flags (str) If .Ar nis_client_enable is set to .Ar YES , these are the flags to pass to the .Xr ypbind 8 service. .It Ar nis_ypset_enable (bool) If set to .Ar YES then run the .Xr ypset 8 daemon at system boot time. .It Ar nis_ypset_flags (str) If .Ar nis_ypset_enable is set to .Ar YES , these are the flags to pass to the .Xr ypset 8 daemon. .It Ar nis_server_enable (bool) If set to .Ar YES then run the .Xr ypserv 8 daemon at system boot time. .It Ar nis_server_flags (str) If .Ar nis_server_enable is set to .Ar YES , these are the flags to pass to the .Xr ypserv 8 daemon. .It Ar nis_ypxfrd_enable (bool) If set to .Ar YES then run the .Xr ypxfrd 8 daemon at system boot time. .It Ar nis_ypxfrd_flags (str) If .Ar nis_ypxfrd_enable is set to .Ar YES , these are the flags to pass to the .Xr ypxfrd 8 daemon. .It Ar nis_yppasswdd_enable (bool) If set to .Ar YES then run the .Xr yppasswdd 8 daemon at system boot time. .It Ar nis_yppasswdd_flags (str) If .Ar nis_yppasswdd_enable is set to .Ar YES , these are the flags to pass to the .Xr yppasswdd 8 daemon. .It Ar defaultrouter (str) If not set to .Ar NO then create a default route to this host name or IP address (use IP address value if you also require this router to get to a name server!) .It Ar static_routes (str) Set to the list of static routes you would like to add at system boot time. If not set to .Ar NO then for each whitespace separated .Em element in the value, a .No route_ Ns element variable is assumed to exist whose contents will later be passed to a .Dq route add operation. .It Ar gateway_enable (bool) If set to .Ar YES , then configure host to at as an IP router, e.g. to forward packets between interfaces. .It Ar router_enable (bool) If set to .Ar YES then run a routing daemon of some sort, based on the settings of .Ar router and .Ar router_flags . .It Ar router (str) If .Ar router_enable is set to .Ar YES , this is the name of the routing daemon to use. .It Ar router_flags (str) If .Ar router_enable is set to .Ar YES , these are the flags to pass to the routing daemon. .It Ar mrouted_enable (bool) If set to .Ar YES then run the multicast routing daemon, .Xr mrouted 8 . .It Ar mrouted_flags (str) If .Ar mrouted_enable is set to .Ar YES , these are the flags to pass to the multicast routing daemon. .It Ar ipxgateway_enable (bool) If set to .Ar YES then enable the routing of IPX traffic. .It Ar ipxrouted_enable (bool) If set to .Ar YES then run the .Xr IPXrouted 8 daemon at system boot time. .It Ar ipxrouted_flags (str) If .Ar ipxrouted_enable is set to .Ar YES , these are the flags to pass to the .Xr IPXrouted 8 daemon. .It Ar arpproxy_all If set to .Ar YES then enable global proxy ARP. .It Ar forward_sourceroute If set to .Ar YES then when .Ar gateway_enable is also set to .Ar YES , source routed packets are forwarded. .It Ar accept_sourceroute If set to .Ar YES then the system will accept source routed packets directed at it. .It Ar rarpd_enable (bool) If set to .Ar YES then run the .Xr rarpd 8 daemon at system boot time. .It Ar rarpd_flags (str) If .Ar rarpd_enable is set to .Ar YES , these are the flags to pass to the .Xr rarpd 8 daemon. .It Ar atm_enable (bool) Set to .Ar YES to enable the configuration of ATM interfaces at system boot time. For all of the ATM variables described below, please refer to the .Xr atm 8 man page for further details on the available command parameters. Also refer to the files in .Pa /usr/share/examples/atm for more detailed configuration information. .It Ar atm_netif_ (str) For the ATM physical interface .Va , this variable defines the name prefix and count for the ATM network interfaces to be created. The value will be passed as the parameters of an .Dq atm set netif Va command. .It Ar atm_sigmgr_ (str) For the ATM physical interface .Va , this variable defines the ATM signalling manager to be used. The value will be passed as the parameters of an .Dq atm attach Va command. .It Ar atm_prefix_ (str) For the ATM physical interface .Va , this variable defines the NSAP prefix for interfaces using a UNI signalling manager. If set to .Em ILMI , then the prefix will automatically be set via the .Xr ilmid 8 daemon. Otherwise, the value will be passed as the parameters of an .Dq atm set prefix Va command. .It Ar atm_macaddr_ (str) For the ATM physical interface .Va , this variable defines the MAC address for interfaces using a UNI signalling manager. If set to .Em NO , then the hardware MAC address contained in the ATM interface card will be used. Otherwise, the value will be passed as the parameters of an .Dq atm set mac Va command. .It Ar atm_arpserver_ (str) For the ATM network interface .Va , this variable defines the ATM address for a host which is to provide ATMARP service. This variable is only applicable to interfaces using a UNI signalling manager. If set to .Em local , then this host will become an ATMARP server. The value will be passed as the parameters of an .Dq atm set arpserver Va command. .It Ar atm_scsparp_ (bool) If set to .Em YES , then SCSP/ATMARP service for the network interface .Va will be initiated using the .Xr scspd 8 and .Xr atmarpd 8 daemons. This variable is only applicable if .So .No atm_arpserver_ Ns Va .No = Ns Qq local .Sc is defined. .It Ar atm_pvcs (str) Set to the list of ATM PVCs you would like to add at system boot time. For each whitespace separated .Em element in the value, an .No atm_pvc_ Ns Em element variable is assumed to exist. The value of each of these variables will be passed as the parameters of an .Dq atm add pvc command. .It Ar atm_arps (str) Set to the list of permanent ATM ARP entries you would like to add at system boot time. For each whitespace separated .Em element in the value, an .No atm_arp_ Ns Em element variable is assumed to exist. The value of each of these variables will be passed as the parameters of an .Dq atm add arp command. .It Ar keymap (str) If set to .Ar NO then no keymap is installed, otherwise the value is used to install the keymap file in .Pa /usr/share/syscons/keymaps/.kbd .It Ar keyrate (str) The keyboard repeat speed. Set to .Ar slow , .Ar normal , .Ar fast or .Ar NO if the default behavior is desired. .It Ar keychange (str) If not set to .Ar NO , attempt to program the function keys with the value. The value should be a single string of the form: .Qq Ar " [ ]..." .It Ar cursor (str) Can be set to the value of .Ar normal , .Ar blink , .Ar destructive or .Ar NO to set the cursor behavior explicitly or choose the default behavior. .It Ar scrnmap (str) If set to .Ar NO then no screen map is installed, otherwise the value is used to install the screen map file in .Pa /usr/share/syscons/scrnmaps/ . .It Ar font8x16 (str) If set to .Ar NO then the default 8x16 font value is used for screen size requests, otherwise the value in .Pa /usr/share/syscons/fonts/ is used. .It Ar font8x14 (str) If set to .Ar NO then the default 8x14 font value is used for screen size requests, otherwise the value in .Pa /usr/share/syscons/fonts/ is used. .It Ar font8x8 (str) If set to .Ar NO then the default 8x8 font value is used for screen size requests, otherwise the value in .Pa /usr/share/syscons/fonts/ is used. .It Ar blanktime (int) If set to .Ar NO then the default screen blanking interval is used, otherwise it is set to .Ar value seconds. .It Ar saver (str) If not set to .Ar NO , this is the actual screen saver to use (blank, snake, daemon, etc). .It Ar moused_enable (str) If set to .Ar YES , the .Xr moused 8 daemon is started for doing cut/paste selection on the console. .It Ar moused_type (str) This is the protocol type of mouse you would like to use. This variable must be set if .Ar moused_enable is set to .Ar YES . The .Xr moused 8 daemon is able to detect the appropriate mouse type automatically in many cases. You can set this variable to .Ar auto to let the daemon detect it, or select one from the following list if the automatic detection fails. .Pp If your mouse is attached to the PS/2 mouse port, you should always choose .Ar auto or .Ar ps/2 , regardless of the brand and model of the mouse. Likewise, if your mouse is attached to the bus mouse port, choose .Ar auto or .Ar busmouse . All other protocols are for serial mice and will not work with the PS/2 and bus mice. If you have a USB mouse, .Ar auto is the only protocol type which works with the USB mouse. .Bd -literal microsoft Microsoft mouse (serial) intellimouse Microsoft IntelliMouse (serial) mousesystems Mouse systems Corp mouse (serial) mmseries MM Series mouse (serial) logitech Logitech mouse (serial) busmouse A bus mouse mouseman Logitech MouseMan and TrackMan (serial) glidepoint ALPS GlidePoint (serial) thinkingmouse Kensignton ThinkingMouse (serial) ps/2 PS/2 mouse mmhittab MM HitTablet (serial) x10mouseremote X10 MouseRemote (serial) versapad Interlink VersaPad (serial) .Ed Even if your mouse is not in the above list, it may be compatible with one in the list. Refer to the man page for .Xr moused 8 for compatibility information. .Pp It should also be noted that while this is enabled, any other client of the mouse (such as an X server) should access the mouse through the virtual mouse device: .Pa /dev/sysmouse and configure it as a sysmouse type mouse, since all mouse data is converted to this single canonical format when using .Xr moused 8 . If the client program does not support the sysmouse type, specify the mousesystems type. It is the second preferred type. .It Ar moused_port (str) If .Ar moused_enable is set to .Ar YES , this is the actual port the mouse is on. It might be .Pa /dev/cuaa0 for a COM1 serial mouse, .Pa /dev/psm0 for a PS/2 mouse or .Pa /dev/mse0 for a bus mouse, for example. .It Ar moused_flags (str) If .Ar moused_type is set, these are the additional flags to pass to the .Xr moused 8 daemon. .It Ar allscreens_flags (str) If set, .Xr vidcontrol 1 is run with these options for each of the virtual terminals .Pq Pa /dev/ttyv* . For example, .Ar -m on will enable the mouse pointer on all virtual terminals if .Ar moused_enable is set to .Ar YES . .It Ar cron_enable (bool) If set to .Ar YES then run the .Xr cron 8 daemon at system boot time. .It Ar cron_program (str) path to .Xr cron 8 (default .Pa /usr/sbin/cron ) . .It Ar cron_flags (str) if .Ar cron_enable is set to .Ar YES , these are the flags to pass to .Xr cron 8 . .It Ar lpd_program (str) path to .Xr lpd 8 (default .Pa /usr/sbin/lpd ) . .It Ar lpd_enable (bool) If set to .Ar YES then run the .Xr lpd 8 daemon at system boot time. .It Ar lpd_flags (str) If .Ar lpd_enable is set to .Ar YES , these are the flags to pass to the .Xr lpd 8 daemon. .It Ar sendmail_enable (bool) If set to .Ar YES then run the .Xr sendmail 8 daemon at system boot time. .It Ar sendmail_flags (str) If .Ar sendmail_enable is set to .Ar YES , these are the flags to pass to the .Xr sendmail 8 daemon. .It Ar dumpdev (str) If not set to .Ar NO then point kernel crash-dumps at the swap device specified as .Em value . When the system restarts, a crash-dump found on the specified device will typically be stored in the .Pa /var/crash directory by the .Xr savecore 8 program. .It Ar check_quotas (bool) Set to .Ar YES if you want to enable user disk quota checking via the .Xr quotacheck 8 command. .It Ar accounting_enable (bool) Set to .Ar YES if you wish to enable system accounting through the .Xr accton 8 facility. .It Ar ibcs2_enable (bool) Set to .Ar YES if you wish to enable iBCS2 (SCO) binary emulation at system initial boot time. .It Ar ibcs2_loaders (str) If not set to .Ar NO and if .Ar ibcs2_enable is set to .Ar YES , this specifies a list of additional iBCS2 loaders to enable. .It Ar linux_enable (bool) Set to .Ar YES if you wish to enable Linux/ELF binary emulation at system initial boot time. .It Ar osf1_enable (bool) Set to .Ar YES if you wish to enable OSF/1 (Digital UNIX) binary emulation at system initial boot time. (alpha) .It Ar rand_irqs (str) Set to the list of IRQs to monitor for random number creation (see the man page for .Xr rndcontrol 8 ) . .It Ar clear_tmp_enable (bool) Set to .Ar YES if you want .Pa /tmp to be cleaned at startup. .It Ar ldconfig_paths (str) Set to the list of shared library paths to use with .Xr ldconfig 8 . NOTE: .Pa /usr/lib will always be added first, so it need not appear in this list. .It Ar ldconfig_insecure (bool) The .Xr ldconfig 8 utility normally refuses to use directories which are writable by anyone except root. Set this variable to .Ar YES if you want to disable that security check during system startup. .It Ar kern_securelevel_enable (bool) Set to .Ar YES if you wish to set the kernel security level at system startup. .It Ar kern_securelevel (int) The kernel security level to set at startup. The allowed range of .Ar value ranges from -1 (the compile time default) to 3 (the most secure). See .Xr init 8 for the list of possible security levels and their effect on system operation. .It Ar start_vinum (bool) Set to .Ar YES if you want to start .Xr vinum 8 at system boot time. .It Ar sshd_program (str) Path to the SSH server program .Po .Pa /usr/sbin/sshd is the default .Pc . .It Ar sshd_enable (bool) Set to .Ar YES if you want to start .Xr sshd 8 at system boot time. .It Ar sshd_flags (str) If .Ar sshd_enable is set to .Ar YES , these are the flags to pass to the .Xr sshd 8 daemon. .It Ar unaligned_print (bool) If set to .Ar NO then unaligned access warnings will not be printed. (alpha) .\" ----- isdn settings --------------------------------- .It Ar isdn_enable (bool) Set to .Ar NO by default. When set to .Ar YES , starts the isdn daemon .Pa /usr/sbin/isdnd at system boot time. .It Va isdn_flags (str) Set to .Ar -dn -d0x1f9 by default. Additional flags to pass to .Xr isndn 8 (but see .Ar isdn_fsdev and .Ar isdn_ttype for certain tunable parameters). .It Ar isdn_ttype (str) Set to .Ar cons25 by default. The terminal type of the output device when .Xr idsnd 8 operates in fullscreen mode. .It Ar isdn_fsdev (str) Set to .Ar /dev/ttyv4 by default. The output device for .Xr idsnd 8 in fullscreen mode (or .Ar NO for daemon mode). .It Ar isdn_trace (bool) Set to .Ar NO by default. When set to .Ar YES , enables the ISDN protocol trace utility .Pa /usr/sbin/isdntrace at system boot time. .It Ar isdn_traceflags (str) Set to .Ar -f /var/tmp/isdntrace0 by default. Flags for .Pa /usr/sbin/isdntrace . .It Ar isdn_screenflags (str) Set to .Ar NO by default. The video mode for fullscreen mode (only for .Xr syscons 4 console driver, see .Xr vidcontrol 1 for valid modes). .\" ----------------------------------------------------- .El .Sh FILES .Bl -tag -width /etc/defaults/rc.conf -compact .It Pa /etc/defaults/rc.conf .It Pa /etc/rc.conf .It Pa /etc/rc.conf.local .El .Sh SEE ALSO .Xr catman 1 , .Xr makewhatis 1 , .Xr gdb 1 , .Xr info 1 , .Xr exports 5 , .Xr motd 5 , .Xr accton 8 , .Xr amd 8 , .Xr apm 8 , .Xr atm 8 , .Xr cron 8 , .Xr dhclient 8 , .Xr gated 8 , .Xr ifconfig 8 , .Xr inetd 8 , .Xr isdnd 8 , .Xr isdntrace 8 , .Xr lpd 8 , .Xr moused 8 , .Xr mrouted 8 , .Xr named 8 , .Xr nfsd 8 , .Xr nfsiod 8 , .Xr ntpdate 8 , .Xr pcnfsd 8 , .Xr portmap 8 , .Xr quotacheck 8 , .Xr rc 8 , .Xr rndcontrol 8 , .Xr route 8 , .Xr routed 8 , .Xr rpc.lockd 8 , .Xr rpc.statd 8 , .Xr rwhod 8 , .Xr savecore 8 , .Xr sendmail 8 , .Xr sshd 8 , .Xr sysctl 8 , .Xr syslogd 8 , .Xr swapon 8 , .Xr tickadj 8 , .Xr timed 8 , .Xr vidcontrol 1 , .Xr vinum 8 , .Xr vnconfig 8 , .Xr xntpd 8 , .Xr xtend 8 , .Xr ypbind 8 , .Xr ypserv 8 , .Xr ypset 8 .Sh HISTORY The .Nm file appeared in .Fx 2.2.2 . .Sh AUTHORS .An Jordan K. Hubbard . Index: stable/4/sys/modules/netgraph/bpf/ng_bpf.4 =================================================================== --- stable/4/sys/modules/netgraph/bpf/ng_bpf.4 (revision 78135) +++ stable/4/sys/modules/netgraph/bpf/ng_bpf.4 (revision 78136) @@ -1,192 +1,192 @@ .\" Copyright (c) 1999 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $FreeBSD$ .\" $Whistle: ng_bpf.8,v 1.2 1999/12/03 01:57:12 archie Exp $ .\" .Dd December 2, 1999 .Dt NG_BPF 4 .Os FreeBSD .Sh NAME .Nm ng_bpf .Nd Berkeley packet filter netgraph node type .Sh SYNOPSIS .Fd #include .Fd #include .Sh DESCRIPTION The .Nm bpf node type allows Berkeley Packet Filter (see .Xr bpf 4 ) filters to be applied to data travelling through a Netgraph network. Each node allows an arbitrary number of connections to arbitrarily named hooks. With each hook is associated a .Xr bpf 4 filter program which is applied to incoming data only, a destination hook for matching packets, a destination hook for non-matching packets, and various statistics counters. .Pp A .Xr bpf 4 program returns an unsigned integer, which is normally interpreted as the length of the prefix of the packet to return. In the context of this node type, returning zero is considered a non-match, in which case the entire packet is delivered out the non-match destination hook. Returning a value greater than zero causes the packet to be truncated to that length and delivered out the match destination hook. Either or both destination hooks may be the empty string, or may not exist, in which case the packet is dropped. .Pp New hooks are initially configured to drop all packets. A new filter program may be installed using the .Dv NGM_BPF_SET_PROGRAM control message. .Sh HOOKS This node type supports any number of hooks having arbitrary names. .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_BPF_SET_PROGRAM This command sets the filter program that will be applied to incoming data on a hook. The following structure must be supplied as an argument: .Bd -literal -offset 4n struct ng_bpf_hookprog { char thisHook[NG_HOOKLEN+1]; /* name of hook */ char ifMatch[NG_HOOKLEN+1]; /* match dest hook */ char ifNotMatch[NG_HOOKLEN+1]; /* !match dest hook */ int32_t bpf_prog_len; /* #isns in program */ struct bpf_insn bpf_prog[0]; /* bpf program */ }; .Ed .Pp The hook to be updated is specified in .Dv thisHook . The BPF program is the sequence of instructions in the .Dv bpf_prog array; there must be .Dv bpf_prog_len of them. Matching and non-matching incoming packets are delivered out the hooks named .Dv ifMatch and .Dv ifNotMatch , respectively. The program must be a valid .Xr bpf 4 program or else .Er EINVAL is returned. .It Dv NGM_BPF_GET_PROGRAM This command takes an .Tn ASCII string argument, the hook name, and returns the corresponding .Dv "struct ng_bpf_hookprog" as shown above. .It Dv NGM_BPF_GET_STATS This command takes an .Tn ASCII string argument, the hook name, and returns the statistics associated with the hook as a .Dv "struct ng_bpf_hookstat" . .It Dv NGM_BPF_CLR_STATS This command takes an .Tn ASCII string argument, the hook name, and clears the statistics associated with the hook. .It Dv NGM_BPF_GETCLR_STATS This command is identical to .Dv NGM_BPF_GET_STATS , except that the statistics are also atomically cleared. .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. .Sh EXAMPLE It is possible to configure a node from the command line, using -.Xr tcpdump 8 +.Xr tcpdump 1 to generate raw BPF instructions which are then fed into an .Xr awk 1 script to create the ASCII form of a .Dv NGM_BPF_SET_PROGRAM control message, as demonstrated here: .Bd -literal -offset 4n #!/bin/sh PATTERN="tcp dst port 80" NODEPATH="my_node:" INHOOK="hook1" MATCHHOOK="hook2" NOTMATCHHOOK="hook3" cat > /tmp/bpf.awk << xxENDxx { if (!init) { printf "bpf_prog_len=%d bpf_prog=[", \\$1; init=1; } else { printf " { code=%d jt=%d jf=%d k=%d }", \\$1, \\$2, \\$3, \\$4; } } END { print " ]" } xxENDxx BPFPROG=`tcpdump -s 8192 -ddd ${PATTERN} | awk -f /tmp/bpf.awk` ngctl msg ${NODEPATH} setprogram { thisHook=\\"${INHOOK}\\" \\ ifMatch=\\"${MATCHHOOK}\\" \\ ifNotMatch=\\"${NOTMATCHHOOK}\\" \\ ${BPFPROG} } } .Ed .Sh BUGS When built as a loadable kernel module, this module includes the file .Pa net/bpf_filter.c . Although loading the module should fail if .Pa net/bpf_filter.c already exists in the kernel, currently it does not, and the duplicate copies of the file do not interfere. However, this may change in the future. .Sh HISTORY The .Nm node type was implemented in .Fx 4.0 . .Sh SEE ALSO .Xr netgraph 4 , .Xr bpf 4 , .Xr ngctl 8 .Sh AUTHORS .An Archie Cobbs Aq archie@freebsd.org Index: stable/4/sys/modules/netgraph/netgraph/netgraph.4 =================================================================== --- stable/4/sys/modules/netgraph/netgraph/netgraph.4 (revision 78135) +++ stable/4/sys/modules/netgraph/netgraph/netgraph.4 (revision 78136) @@ -1,1056 +1,1055 @@ .\" Copyright (c) 1996-1999 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Authors: Julian Elischer .\" Archie Cobbs .\" .\" $FreeBSD$ .\" $Whistle: netgraph.4,v 1.7 1999/01/28 23:54:52 julian Exp $ .\" .Dd January 19, 1999 .Dt NETGRAPH 4 .Os FreeBSD .Sh NAME .Nm netgraph .Nd graph based kernel networking subsystem .Sh DESCRIPTION The .Nm system provides a uniform and modular system for the implementation of kernel objects which perform various networking functions. The objects, known as .Em nodes , can be arranged into arbitrarily complicated graphs. Nodes have .Em hooks which are used to connect two nodes together, forming the edges in the graph. Nodes communicate along the edges to process data, implement protocols, etc. .Pp The aim of .Nm is to supplement rather than replace the existing kernel networking infrastructure. It provides: .Pp .Bl -bullet -compact -offset 2n .It A flexible way of combining protocol and link level drivers .It A modular way to implement new protocols .It A common framework for kernel entities to inter-communicate .It A reasonably fast, kernel-based implementation .El .Sh Nodes and Types The most fundamental concept in .Nm is that of a .Em node . All nodes implement a number of predefined methods which allow them to interact with other nodes in a well defined manner. .Pp Each node has a .Em type , which is a static property of the node determined at node creation time. A node's type is described by a unique .Tn ASCII type name. The type implies what the node does and how it may be connected to other nodes. .Pp In object-oriented language, types are classes and nodes are instances of their respective class. All node types are subclasses of the generic node type, and hence inherit certain common functionality and capabilities (e.g., the ability to have an .Tn ASCII name). .Pp Nodes may be assigned a globally unique .Tn ASCII name which can be used to refer to the node. The name must not contain the characters .Dq .\& or .Dq \&: and is limited to .Dv "NG_NODELEN + 1" characters (including NUL byte). .Pp Each node instance has a unique .Em ID number which is expressed as a 32-bit hex value. This value may be used to refer to a node when there is no .Tn ASCII name assigned to it. .Sh Hooks Nodes are connected to other nodes by connecting a pair of .Em hooks , one from each node. Data flows bidirectionally between nodes along connected pairs of hooks. A node may have as many hooks as it needs, and may assign whatever meaning it wants to a hook. .Pp Hooks have these properties: .Pp .Bl -bullet -compact -offset 2n .It A hook has an .Tn ASCII name which is unique among all hooks on that node (other hooks on other nodes may have the same name). The name must not contain a .Dq .\& or a .Dq \&: and is limited to .Dv "NG_HOOKLEN + 1" characters (including NUL byte). .It A hook is always connected to another hook. That is, hooks are created at the time they are connected, and breaking an edge by removing either hook destroys both hooks. .El .Pp A node may decide to assign special meaning to some hooks. For example, connecting to the hook named .Dq debug might trigger the node to start sending debugging information to that hook. .Sh Data Flow Two types of information flow between nodes: data messages and control messages. Data messages are passed in mbuf chains along the edges in the graph, one edge at a time. The first mbuf in a chain must have the .Dv M_PKTHDR flag set. Each node decides how to handle data coming in on its hooks. .Pp Control messages are type-specific C structures sent from one node directly to some arbitrary other node. Control messages have a common header format, followed by type-specific data, and are binary structures for efficiency. However, node types also may support conversion of the type specific data between binary and .Tn ASCII for debugging and human interface purposes (see the .Dv NGM_ASCII2BINARY and .Dv NGM_BINARY2ASCII generic control messages below). Nodes are not required to support these conversions. .Pp There are two ways to address a control message. If there is a sequence of edges connecting the two nodes, the message may be .Dq source routed by specifying the corresponding sequence of hooks as the destination address for the message (relative addressing). Otherwise, the recipient node global .Tn ASCII name (or equivalent ID based name) is used as the destination address for the message (absolute addressing). The two types of addressing may be combined, by specifying an absolute start node and a sequence of hooks. .Pp Messages often represent commands that are followed by a reply message in the reverse direction. To facilitate this, the recipient of a control message is supplied with a .Dq return address that is suitable for addressing a reply. .Pp Each control message contains a 32 bit value called a .Em typecookie indicating the type of the message, i.e., how to interpret it. Typically each type defines a unique typecookie for the messages that it understands. However, a node may choose to recognize and implement more than one type of message. .Sh Netgraph is Functional In order to minimize latency, most .Nm operations are functional. That is, data and control messages are delivered by making function calls rather than by using queues and mailboxes. For example, if node A wishes to send a data mbuf to neighboring node B, it calls the generic .Nm data delivery function. This function in turn locates node B and calls B's .Dq receive data method. While this mode of operation results in good performance, it has a few implications for node developers: .Pp .Bl -bullet -compact -offset 2n .It Whenever a node delivers a data or control message, the node may need to allow for the possibility of receiving a returning message before the original delivery function call returns. .It Netgraph nodes and support routines generally run at .Fn splnet . However, some nodes may want to send data and control messages from a different priority level. Netgraph supplies queueing routines which utilize the NETISR system to move message delivery to .Fn splnet . Note that messages are always received at .Fn splnet . .It It's possible for an infinite loop to occur if the graph contains cycles. .El .Pp So far, these issues have not proven problematical in practice. .Sh Interaction With Other Parts of the Kernel A node may have a hidden interaction with other components of the kernel outside of the .Nm subsystem, such as device hardware, kernel protocol stacks, etc. In fact, one of the benefits of .Nm is the ability to join disparate kernel networking entities together in a consistent communication framework. .Pp An example is the node type .Em socket which is both a netgraph node and a .Xr socket 2 BSD socket in the protocol family .Dv PF_NETGRAPH . Socket nodes allow user processes to participate in .Nm . Other nodes communicate with socket nodes using the usual methods, and the node hides the fact that it is also passing information to and from a cooperating user process. .Pp Another example is a device driver that presents a node interface to the hardware. .Sh Node Methods Nodes are notified of the following actions via function calls to the following node methods (all at .Fn splnet ) and may accept or reject that action (by returning the appropriate error code): .Bl -tag -width xxx .It Creation of a new node The constructor for the type is called. If creation of a new node is allowed, the constructor must call the generic node creation function (in object-oriented terms, the superclass constructor) and then allocate any special resources it needs. For nodes that correspond to hardware, this is typically done during the device attach routine. Often a global .Tn ASCII name corresponding to the device name is assigned here as well. .It Creation of a new hook The hook is created and tentatively linked to the node, and the node is told about the name that will be used to describe this hook. The node sets up any special data structures it needs, or may reject the connection, based on the name of the hook. .It Successful connection of two hooks After both ends have accepted their hooks, and the links have been made, the nodes get a chance to find out who their peer is across the link and can then decide to reject the connection. Tear-down is automatic. .It Destruction of a hook The node is notified of a broken connection. The node may consider some hooks to be critical to operation and others to be expendable: the disconnection of one hook may be an acceptable event while for another it may effect a total shutdown for the node. .It Shutdown of a node This method allows a node to clean up and to ensure that any actions that need to be performed at this time are taken. The method must call the generic (i.e., superclass) node destructor to get rid of the generic components of the node. Some nodes (usually associated with a piece of hardware) may be .Em persistent in that a shutdown breaks all edges and resets the node, but doesn't remove it, in which case the generic destructor is not called. .El .Sh Sending and Receiving Data Three other methods are also supported by all nodes: .Bl -tag -width xxx .It Receive data message An mbuf chain is passed to the node. The node is notified on which hook the data arrived, and can use this information in its processing decision. The node must must always .Fn m_freem the mbuf chain on completion or error, or pass it on to another node (or kernel module) which will then be responsible for freeing it. .Pp In addition to the mbuf chain itself there is also a pointer to a structure describing meta-data about the message (e.g. priority information). This pointer may be .Dv NULL if there is no additional information. The format for this information is described in .Pa netgraph.h . The memory for meta-data must allocated via .Fn malloc with type .Dv M_NETGRAPH . As with the data itself, it is the receiver's responsibility to .Fn free the meta-data. If the mbuf chain is freed the meta-data must be freed at the same time. If the meta-data is freed but the real data on is passed on, then a .Dv NULL pointer must be substituted. .Pp The receiving node may decide to defer the data by queueing it in the .Nm NETISR system (see below). .Pp The structure and use of meta-data is still experimental, but is presently used in frame-relay to indicate that management packets should be queued for transmission at a higher priority than data packets. This is required for conformance with Frame Relay standards. .Pp .It Receive queued data message Usually this will be the same function as .Em Receive data message. This is the entry point called when a data message is being handed to the node after having been queued in the NETISR system. This allows a node to decide in the .Em Receive data message method that a message should be deferred and queued, and be sure that when it is processed from the queue, it will not be queued again. .It Receive control message This method is called when a control message is addressed to the node. A return address is always supplied, giving the address of the node that originated the message so a reply message can be sent anytime later. .Pp It is possible for a synchronous reply to be made, and in fact this is more common in practice. This is done by setting a pointer (supplied as an extra function parameter) to point to the reply. Then when the control message delivery function returns, the caller can check if this pointer has been made non-NULL, and if so then it points to the reply message allocated via .Fn malloc and containing the synchronous response. In both directions, (request and response) it is up to the receiver of that message to .Fn free the control message buffer. All control messages and replies are allocated with .Fn malloc type .Dv M_NETGRAPH . .El .Pp Much use has been made of reference counts, so that nodes being free'd of all references are automatically freed, and this behaviour has been tested and debugged to present a consistent and trustworthy framework for the .Dq type module writer to use. .Sh Addressing The .Nm framework provides an unambiguous and simple to use method of specifically addressing any single node in the graph. The naming of a node is independent of its type, in that another node, or external component need not know anything about the node's type in order to address it so as to send it a generic message type. Node and hook names should be chosen so as to make addresses meaningful. .Pp Addresses are either absolute or relative. An absolute address begins with a node name, (or ID), followed by a colon, followed by a sequence of hook names separated by periods. This addresses the node reached by starting at the named node and following the specified sequence of hooks. A relative address includes only the sequence of hook names, implicitly starting hook traversal at the local node. .Pp There are a couple of special possibilities for the node name. The name .Dq .\& (referred to as .Dq \&.: ) always refers to the local node. Also, nodes that have no global name may be addressed by their ID numbers, by enclosing the hex representation of the ID number within square brackets. Here are some examples of valid netgraph addresses: .Bd -literal -offset 4n -compact .: foo: .:hook1 foo:hook1.hook2 [f057cd80]:hook1 .Ed .Pp Consider the following set of nodes might be created for a site with a single physical frame relay line having two active logical DLCI channels, with RFC-1490 frames on DLCI 16 and PPP frames over DLCI 20: .Pp .Bd -literal [type SYNC ] [type FRAME] [type RFC1490] [ "Frame1" ](uplink)<-->(data)[](dlci16)<-->(mux)[ ] [ A ] [ B ](dlci20)<---+ [ C ] | | [ type PPP ] +>(mux)[] [ D ] .Ed .Pp One could always send a control message to node C from anywhere by using the name .Em "Frame1:uplink.dlci16" . Similarly, .Em "Frame1:uplink.dlci20" could reliably be used to reach node D, and node A could refer to node B as .Em ".:uplink" , or simply .Em "uplink" . Conversely, B can refer to A as .Em "data" . The address .Em "mux.data" could be used by both nodes C and D to address a message to node A. .Pp Note that this is only for .Em control messages . Data messages are routed one hop at a time, by specifying the departing hook, with each node making the next routing decision. So when B receives a frame on hook .Em data it decodes the frame relay header to determine the DLCI, and then forwards the unwrapped frame to either C or D. .Pp A similar graph might be used to represent multi-link PPP running over an ISDN line: .Pp .Bd -literal [ type BRI ](B1)<--->(link1)[ type MPP ] [ "ISDN1" ](B2)<--->(link2)[ (no name) ] [ ](D) <-+ | +----------------+ | +->(switch)[ type Q.921 ](term1)<---->(datalink)[ type Q.931 ] [ (no name) ] [ (no name) ] .Ed .Sh Netgraph Structures Interesting members of the node and hook structures are shown below: .Bd -literal struct ng_node { char *name; /* Optional globally unique name */ void *private; /* Node implementation private info */ struct ng_type *type; /* The type of this node */ int refs; /* Number of references to this struct */ int numhooks; /* Number of connected hooks */ hook_p hooks; /* Linked list of (connected) hooks */ }; typedef struct ng_node *node_p; struct ng_hook { char *name; /* This node's name for this hook */ void *private; /* Node implementation private info */ int refs; /* Number of references to this struct */ struct ng_node *node; /* The node this hook is attached to */ struct ng_hook *peer; /* The other hook in this connected pair */ struct ng_hook *next; /* Next in list of hooks for this node */ }; typedef struct ng_hook *hook_p; .Ed .Pp The maintenance of the name pointers, reference counts, and linked list of hooks for each node is handled automatically by the .Nm subsystem. Typically a node's private info contains a back-pointer to the node or hook structure, which counts as a new reference that must be registered by incrementing .Dv "node->refs" . .Pp From a hook you can obtain the corresponding node, and from a node the list of all active hooks. .Pp Node types are described by these structures: .Bd -literal /** How to convert a control message from binary <-> ASCII */ struct ng_cmdlist { u_int32_t cookie; /* typecookie */ int cmd; /* command number */ const char *name; /* command name */ const struct ng_parse_type *mesgType; /* args if !NGF_RESP */ const struct ng_parse_type *respType; /* args if NGF_RESP */ }; struct ng_type { u_int32_t version; /* Must equal NG_VERSION */ const char *name; /* Unique type name */ /* Module event handler */ modeventhand_t mod_event; /* Handle load/unload (optional) */ /* Constructor */ int (*constructor)(node_p *node); /* Create a new node */ /** Methods using the node **/ int (*rcvmsg)(node_p node, /* Receive control message */ struct ng_mesg *msg, /* The message */ const char *retaddr, /* Return address */ struct ng_mesg **resp); /* Synchronous response */ int (*shutdown)(node_p node); /* Shutdown this node */ int (*newhook)(node_p node, /* create a new hook */ hook_p hook, /* Pre-allocated struct */ const char *name); /* Name for new hook */ /** Methods using the hook **/ int (*connect)(hook_p hook); /* Confirm new hook attachment */ int (*rcvdata)(hook_p hook, /* Receive data on a hook */ struct mbuf *m, /* The data in an mbuf */ meta_p meta); /* Meta-data, if any */ int (*disconnect)(hook_p hook); /* Notify disconnection of hook */ /** How to convert control messages binary <-> ASCII */ const struct ng_cmdlist *cmdlist; /* Optional; may be NULL */ }; .Ed .Pp Control messages have the following structure: .Bd -literal #define NG_CMDSTRLEN 15 /* Max command string (16 with null) */ struct ng_mesg { struct ng_msghdr { u_char version; /* Must equal NG_VERSION */ u_char spare; /* Pad to 2 bytes */ u_short arglen; /* Length of cmd/resp data */ u_long flags; /* Message status flags */ u_long token; /* Reply should have the same token */ u_long typecookie; /* Node type understanding this message */ u_long cmd; /* Command identifier */ u_char cmdstr[NG_CMDSTRLEN+1]; /* Cmd string (for debug) */ } header; char data[0]; /* Start of cmd/resp data */ }; #define NG_VERSION 1 /* Netgraph version */ #define NGF_ORIG 0x0000 /* Command */ #define NGF_RESP 0x0001 /* Response */ .Ed .Pp Control messages have the fixed header shown above, followed by a variable length data section which depends on the type cookie and the command. Each field is explained below: .Bl -tag -width xxx .It Dv version Indicates the version of netgraph itself. The current version is .Dv NG_VERSION . .It Dv arglen This is the length of any extra arguments, which begin at .Dv data . .It Dv flags Indicates whether this is a command or a response control message. .It Dv token The .Dv token is a means by which a sender can match a reply message to the corresponding command message; the reply always has the same token. .Pp .It Dv typecookie The corresponding node type's unique 32-bit value. If a node doesn't recognize the type cookie it must reject the message by returning .Er EINVAL . .Pp Each type should have an include file that defines the commands, argument format, and cookie for its own messages. The typecookie insures that the same header file was included by both sender and receiver; when an incompatible change in the header file is made, the typecookie .Em must be changed. The de facto method for generating unique type cookies is to take the seconds from the epoch at the time the header file is written (i.e., the output of .Dv "date -u +'%s'" ) . .Pp There is a predefined typecookie .Dv NGM_GENERIC_COOKIE for the .Dq generic node type, and a corresponding set of generic messages which all nodes understand. The handling of these messages is automatic. .It Dv command The identifier for the message command. This is type specific, and is defined in the same header file as the typecookie. .It Dv cmdstr Room for a short human readable version of .Dq command (for debugging purposes only). .El .Pp Some modules may choose to implement messages from more than one of the header files and thus recognize more than one type cookie. .Sh Control Message ASCII Form Control messages are in binary format for efficiency. However, for debugging and human interface purposes, and if the node type supports it, control messages may be converted to and from an equivalent .Tn ASCII form. The .Tn ASCII form is similar to the binary form, with two exceptions: .Pp .Bl -tag -compact -width xxx .It o The .Dv cmdstr header field must contain the .Tn ASCII name of the command, corresponding to the .Dv cmd header field. .It o The .Dv args field contains a NUL-terminated .Tn ASCII string version of the message arguments. .El .Pp In general, the arguments field of a control messgage can be any arbitrary C data type. Netgraph includes parsing routines to support some pre-defined datatypes in .Tn ASCII with this simple syntax: .Pp .Bl -tag -compact -width xxx .It o Integer types are represented by base 8, 10, or 16 numbers. .It o Strings are enclosed in double quotes and respect the normal C language backslash escapes. .It o IP addresses have the obvious form. .It o Arrays are enclosed in square brackets, with the elements listed consecutively starting at index zero. An element may have an optional index and equals sign preceeding it. Whenever an element does not have an explicit index, the index is implicitly the previous element's index plus one. .It o Structures are enclosed in curly braces, and each field is specified in the form .Dq fieldname=value . .It o Any array element or structure field whose value is equal to its .Dq default value may be omitted. For integer types, the default value is usually zero; for string types, the empty string. .It o Array elements and structure fields may be specified in any order. .El .Pp Each node type may define its own arbitrary types by providing the necessary routines to parse and unparse. .Tn ASCII forms defined for a specific node type are documented in the documentation for that node type. .Sh Generic Control Messages There are a number of standard predefined messages that will work for any node, as they are supported directly by the framework itself. These are defined in .Pa ng_message.h along with the basic layout of messages and other similar information. .Bl -tag -width xxx .It Dv NGM_CONNECT Connect to another node, using the supplied hook names on either end. .It Dv NGM_MKPEER Construct a node of the given type and then connect to it using the supplied hook names. .It Dv NGM_SHUTDOWN The target node should disconnect from all its neighbours and shut down. Persistent nodes such as those representing physical hardware might not disappear from the node namespace, but only reset themselves. The node must disconnect all of its hooks. This may result in neighbors shutting themselves down, and possibly a cascading shutdown of the entire connected graph. .It Dv NGM_NAME Assign a name to a node. Nodes can exist without having a name, and this is the default for nodes created using the .Dv NGM_MKPEER method. Such nodes can only be addressed relatively or by their ID number. .It Dv NGM_RMHOOK Ask the node to break a hook connection to one of its neighbours. Both nodes will have their .Dq disconnect method invoked. Either node may elect to totally shut down as a result. .It Dv NGM_NODEINFO Asks the target node to describe itself. The four returned fields are the node name (if named), the node type, the node ID and the number of hooks attached. The ID is an internal number unique to that node. .It Dv NGM_LISTHOOKS This returns the information given by .Dv NGM_NODEINFO , but in addition includes an array of fields describing each link, and the description for the node at the far end of that link. .It Dv NGM_LISTNAMES This returns an array of node descriptions (as for .Dv NGM_NODEINFO ")" where each entry of the array describes a named node. All named nodes will be described. .It Dv NGM_LISTNODES This is the same as .Dv NGM_LISTNAMES except that all nodes are listed regardless of whether they have a name or not. .It Dv NGM_LISTTYPES This returns a list of all currently installed netgraph types. .It Dv NGM_TEXT_STATUS The node may return a text formatted status message. The status information is determined entirely by the node type. It is the only "generic" message that requires any support within the node itself and as such the node may elect to not support this message. The text response must be less than .Dv NG_TEXTRESPONSE bytes in length (presently 1024). This can be used to return general status information in human readable form. .It Dv NGM_BINARY2ASCII This message converts a binary control message to its .Tn ASCII form. The entire control message to be converted is contained within the arguments field of the .Dv Dv NGM_BINARY2ASCII message itself. If successful, the reply will contain the same control message in .Tn ASCII form. A node will typically only know how to translate messages that it itself understands, so the target node of the .Dv NGM_BINARY2ASCII is often the same node that would actually receive that message. .It Dv NGM_ASCII2BINARY The opposite of .Dv NGM_BINARY2ASCII . The entire control message to be converted, in .Tn ASCII form, is contained in the arguments section of the .Dv NGM_ASCII2BINARY and need only have the .Dv flags , .Dv cmdstr , and .Dv arglen header fields filled in, plus the NUL-terminated string version of the arguments in the arguments field. If successful, the reply contains the binary version of the control message. .El .Sh Metadata Data moving through the .Nm system can be accompanied by meta-data that describes some aspect of that data. The form of the meta-data is a fixed header, which contains enough information for most uses, and can optionally be supplemented by trailing .Em option structures, which contain a .Em cookie (see the section on control messages), an identifier, a length and optional data. If a node does not recognize the cookie associated with an option, it should ignore that option. .Pp Meta data might include such things as priority, discard eligibility, or special processing requirements. It might also mark a packet for debug status, etc. The use of meta-data is still experimental. .Sh INITIALIZATION The base .Nm code may either be statically compiled into the kernel or else loaded dynamically as a KLD via .Xr kldload 8 . In the former case, include .Pp .Dl options NETGRAPH .Pp in your kernel configuration file. You may also include selected node types in the kernel compilation, for example: .Bd -literal -offset indent options NETGRAPH options NETGRAPH_SOCKET options NETGRAPH_ECHO .Ed .Pp Once the .Nm subsystem is loaded, individual node types may be loaded at any time as KLD modules via .Xr kldload 8 . Moreover, .Nm knows how to automatically do this; when a request to create a new node of unknown type .Em type is made, .Nm will attempt to load the KLD module .Pa ng_type.ko . .Pp Types can also be installed at boot time, as certain device drivers may want to export each instance of the device as a netgraph node. .Pp In general, new types can be installed at any time from within the kernel by calling .Fn ng_newtype , supplying a pointer to the type's .Dv struct ng_type structure. .Pp The .Fn NETGRAPH_INIT macro automates this process by using a linker set. .Sh EXISTING NODE TYPES Several node types currently exist. Each is fully documented in its own man page: .Bl -tag -width xxx .It SOCKET The socket type implements two new sockets in the new protocol domain .Dv PF_NETGRAPH . The new sockets protocols are .Dv NG_DATA and .Dv NG_CONTROL , both of type .Dv SOCK_DGRAM . Typically one of each is associated with a socket node. When both sockets have closed, the node will shut down. The .Dv NG_DATA socket is used for sending and receiving data, while the .Dv NG_CONTROL socket is used for sending and receiving control messages. Data and control messages are passed using the .Xr sendto 2 and .Xr recvfrom 2 calls, using a .Dv struct sockaddr_ng socket address. .Pp .It HOLE Responds only to generic messages and is a .Dq black hole for data, Useful for testing. Always accepts new hooks. .Pp .It ECHO Responds only to generic messages and always echoes data back through the hook from which it arrived. Returns any non generic messages as their own response. Useful for testing. Always accepts new hooks. .Pp .It TEE This node is useful for .Dq snooping . It has 4 hooks: .Dv left , .Dv right , .Dv left2right , and .Dv right2left . Data entering from the right is passed to the left and duplicated on .Dv right2left, and data entering from the left is passed to the right and duplicated on .Dv left2right . Data entering from .Dv left2right is sent to the right and data from .Dv right2left to left. .Pp .It RFC1490 MUX Encapsulates/de-encapsulates frames encoded according to RFC 1490. Has a hook for the encapsulated packets .Pq Dq downstream and one hook for each protocol (i.e., IP, PPP, etc.). .Pp .It FRAME RELAY MUX Encapsulates/de-encapsulates Frame Relay frames. Has a hook for the encapsulated packets .Pq Dq downstream and one hook for each DLCI. .Pp .It FRAME RELAY LMI Automatically handles frame relay .Dq LMI (link management interface) operations and packets. Automatically probes and detects which of several LMI standards is in use at the exchange. .Pp .It TTY This node is also a line discipline. It simply converts between mbuf frames and sequential serial data, allowing a tty to appear as a netgraph node. It has a programmable .Dq hotkey character. .Pp .It ASYNC This node encapsulates and de-encapsulates asynchronous frames according to RFC 1662. This is used in conjunction with the TTY node type for supporting PPP links over asynchronous serial lines. .Pp .It INTERFACE This node is also a system networking interface. It has hooks representing each protocol family (IP, AppleTalk, IPX, etc.) and appears in the output of .Xr ifconfig 8 . The interfaces are named .Em ng0 , .Em ng1 , etc. .El .Sh NOTES Whether a named node exists can be checked by trying to send a control message to it (e.g., .Dv NGM_NODEINFO ). If it does not exist, .Er ENOENT will be returned. .Pp All data messages are mbuf chains with the M_PKTHDR flag set. .Pp Nodes are responsible for freeing what they allocate. There are three exceptions: .Bl -tag -width xxxx .It 1 Mbufs sent across a data link are never to be freed by the sender. .It 2 Any meta-data information traveling with the data has the same restriction. It might be freed by any node the data passes through, and a .Dv NULL passed onwards, but the caller will never free it. Two macros .Fn NG_FREE_META "meta" and .Fn NG_FREE_DATA "m" "meta" should be used if possible to free data and meta data (see .Pa netgraph.h ) . .It 3 Messages sent using .Fn ng_send_message are freed by the callee. As in the case above, the addresses associated with the message are freed by whatever allocated them so the recipient should copy them if it wants to keep that information. .El .Sh FILES .Bl -tag -width xxxxx -compact .It Pa /sys/netgraph/netgraph.h Definitions for use solely within the kernel by .Nm nodes. .It Pa /sys/netgraph/ng_message.h Definitions needed by any file that needs to deal with .Nm messages. .It Pa /sys/netgraph/ng_socket.h Definitions needed to use .Nm socket type nodes. .It Pa /sys/netgraph/ng_{type}.h Definitions needed to use .Nm {type} nodes, including the type cookie definition. .It Pa /modules/netgraph.ko Netgraph subsystem loadable KLD module. .It Pa /modules/ng_{type}.ko Loadable KLD module for node type {type}. .El .Sh USER MODE SUPPORT There is a library for supporting user-mode programs that wish to interact with the netgraph system. See .Xr netgraph 3 for details. .Pp Two user-mode support programs, .Xr ngctl 8 and .Xr nghook 8 , are available to assist manual configuration and debugging. .Pp There are a few useful techniques for debugging new node types. First, implementing new node types in user-mode first makes debugging easier. The .Em tee node type is also useful for debugging, especially in conjunction with .Xr ngctl 8 and .Xr nghook 8 . .Sh SEE ALSO .Xr socket 2 , .Xr netgraph 3 , .Xr ng_async 4 , .Xr ng_bpf 4 , .Xr ng_cisco 4 , .Xr ng_ether 4 , .Xr ng_echo 4 , .Xr ng_frame_relay 4 , .Xr ng_hole 4 , .Xr ng_iface 4 , .Xr ng_ksocket 4 , .Xr ng_lmi 4 , .Xr ng_mppc 4 , .Xr ng_ppp 4 , .Xr ng_pppoe 4 , .Xr ng_rfc1490 4 , .Xr ng_socket 4 , .Xr ng_tee 4 , .Xr ng_tty 4 , .Xr ng_UI 4 , .Xr ng_vjc 4 , -.Xr ng_{type} 4 , .Xr ngctl 8 , .Xr nghook 8 .Sh HISTORY The .Nm system was designed and first implemented at Whistle Communications, Inc. in a version of .Fx 2.2 customized for the Whistle InterJet. It first made its debut in the main tree in .Fx 3.4 . .Sh AUTHORS .An -nosplit .An Julian Elischer Aq julian@freebsd.org , with contributions by .An Archie Cobbs Aq archie@freebsd.org . Index: stable/4/usr.sbin/lpr/lpr/printcap.5 =================================================================== --- stable/4/usr.sbin/lpr/lpr/printcap.5 (revision 78135) +++ stable/4/usr.sbin/lpr/lpr/printcap.5 (revision 78136) @@ -1,398 +1,398 @@ .\" 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. 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. .\" .\" @(#)printcap.5 8.2 (Berkeley) 12/11/93 .\" $FreeBSD$ .\" .Dd October 11, 2000 .Dt PRINTCAP 5 .Os BSD 4.2 .Sh NAME .Nm printcap .Nd printer capability data base .Sh SYNOPSIS .Nm .Sh DESCRIPTION The .Nm Printcap function is a simplified version of the .Xr termcap 5 data base used to describe line printers. The spooling system accesses the .Nm file every time it is used, allowing dynamic addition and deletion of printers. Each entry in the data base is used to describe one printer. This data base may not be substituted for, as is possible for .Xr termcap 5 , because it may allow accounting to be bypassed. .Pp The default printer is normally .Em lp , though the environment variable .Ev PRINTER may be used to override this. Each spooling utility supports an option, .Fl P Ar printer , to allow explicit naming of a destination printer. .Pp Refer to the .%T "4.3 BSD Line Printer Spooler Manual" for a complete discussion on how to setup the database for a given printer. .Sh CAPABILITIES Refer to .Xr termcap 5 for a description of the file layout. .Bl -column Namexxx Typexx "/var/spool/lpdxxxxx" .Sy "Name Type Default Description .It "af str" Ta Dv NULL Ta No "name of accounting file" .It "br num none if lp is a tty, set the baud rate" .Pf ( Xr ioctl 2 call) .It "cf str" Ta Dv NULL Ta No "cifplot data filter" .It "ct num 120 TCP connection timeout in seconds" .It "df str" Ta Dv NULL Ta No "tex data filter" .Pf ( Tn DVI format) .It "ff str" Ta So Li \ef Sc Ta No "string to send for a form feed" .It "fo bool false print a form feed when device is opened" .It "gf str" Ta Dv NULL Ta No "graph data filter" .Pf ( Xr plot 3 format .It "hl bool false print the burst header page last" .It "ic bool false driver supports (non standard) ioctl to indent printout" .It "if str" Ta Dv NULL Ta No "name of text filter which does accounting" .It "lf str" Ta Pa /dev/console Ta No "error logging file name" .It "lo str" Ta Pa lock Ta No "name of lock file" .It "lp str" Ta Pa /dev/lp Ta No "device name to open for output" .It "ms str" Ta Dv NULL Ta No "if lp is a tty, a comma-separated," .Xr stty 1 Ns -like list describing the tty modes .It "mx num 1000 maximum file size (in" .Dv BUFSIZ blocks), zero = unlimited .It "nd str" Ta Dv NULL Ta No "next directory for list of queues (unimplemented)" .It "nf str" Ta Dv NULL Ta No "ditroff data filter (device independent troff)" .It "of str" Ta Dv NULL Ta No "name of output filtering program" .It "pc num 200 price per foot or page in hundredths of cents" .It "pl num 66 page length (in lines)" .It "pw num 132 page width (in characters)" .It "px num 0 page width in pixels (horizontal)" .It "py num 0 page length in pixels (vertical)" .It "rf str" Ta Dv NULL Ta No "filter for printing" .Tn FORTRAN style text files .It "rg str" Ta Dv NULL Ta No "restricted group. Only members of group allowed access" .It "rm str" Ta Dv NULL Ta No "machine name for remote printer" .It "rp str ``lp'' remote printer name argument" .It "rs bool false restrict remote users to those with local accounts" .It "rw bool false open the printer device for reading and writing" .It "sb bool false short banner (one line only)" .It "sc bool false suppress multiple copies" .It "sd str" Ta Pa /var/spool/lpd Ta No "spool directory" .It "sf bool false suppress form feeds" .It "sh bool false suppress printing of burst page header" .It "sr str" Ta Dv NULL Ta No "file name to hold statistics of each datafile as it is received" .It "ss str" Ta Dv NULL Ta No "file name to hold statistics of each datafile as it is sent" .It "st str" Ta Pa status Ta No "status file name" .It "tf str" Ta Dv NULL Ta No "troff data filter (cat phototypesetter)" .It "tr str" Ta Dv NULL Ta No "trailer string to print when queue empties" .It "vf str" Ta Dv NULL Ta No "raster image filter" .El .Pp Each two-letter capability has a human-readable alternate name. .Bl -column "Short form" "Long form" .Sy "Short form Long form" .It "af acct.file" .It "br tty.rate" .It "cf filt.cifplot" .It "ct remote.timeout" .It "df filt.dvi" .It "du daemon.user" .It "ff job.formfeed" .It "fo job.topofform" .It "gf filt.plot" .It "hl banner.last" .It "if filt.input" .It "lf spool.log" .It "lo spool.lock" .It "lp tty.device" .It "mc max.copies" .It "ms tty.mode" .It "mx max.blocks" .It "nf filt.ditroff" .It "of filt.output" .It "pc acct.price" .It "pl page.length" .It "pw page.width" .It "px page.pwidth" .It "py page.plength" .It "rf filt.fortran" .It "rg daemon.restrictgrp" .It "rm remote.host" .It "rp remote.queue" .It "rs daemon.restricted" .It "rw tty.rw" .It "sb banner.short" .It "sc job.no_copies" .It "sd spool.dir" .It "sf job.no_formfeed" .It "sh banner.disable" .It "sr stat.recv" .It "ss stat.send" .It "st spool.status" .It "tr job.trailer" .It "vf filt.raster" .El .Pp If the local line printer driver supports indentation, the daemon must understand how to invoke it. .Sh FILTERS The .Xr lpd 8 daemon creates a pipeline of .Em filters to process files for various printer types. The filters selected depend on the flags passed to .Xr lpr 1 . The pipeline set up is: .Bd -literal -offset indent p pr | if regular text + pr(1) none if regular text c cf cifplot d df DVI (tex) g gf plot(3) n nf ditroff f rf Fortran t tf troff v vf raster image .Ed .Pp The .Sy if filter is invoked with arguments: .Bd -ragged -offset indent .Cm if .Op Fl c .Fl w Ns Ar width .Fl l Ns Ar length .Fl i Ns Ar indent .Fl n Ar login .Fl h Ar host acct-file .Ed .Pp The .Fl c flag is passed only if the .Fl l flag (pass control characters literally) is specified to .Xr lpr 1 . The .Ar Width function and .Ar length specify the page width and length (from .Cm pw and .Cm pl respectively) in characters. The .Fl n and .Fl h parameters specify the login name and host name of the owner of the job respectively. The .Ar Acct-file function is passed from the .Cm af .Nm entry. .Pp If no .Cm if is specified, .Cm of is used instead, with the distinction that .Cm of is opened only once, while .Cm if is opened for every individual job. Thus, .Cm if is better suited to performing accounting. The .Cm of is only given the .Ar width and .Ar length flags. .Pp All other filters are called as: .Bd -ragged -offset indent .Nm filter .Fl x Ns Ar width .Fl y Ns Ar length .Fl n Ar login .Fl h Ar host acct-file .Ed .Pp where .Ar width and .Ar length are represented in pixels, specified by the .Cm px and .Cm py entries respectively. .Pp All filters take .Em stdin as the file, .Em stdout as the printer, may log either to .Em stderr or using .Xr syslog 3 , and must not ignore .Dv SIGINT . .Sh REMOTE PRINTING When printing to a remote printer using .Cm rm , it is possible to use either .Cm if or .Cm of . If both are specified, .Cm of is ignored. Both filters behave the same except that they are passed different arguments as above. Specifically, the output filter is terminated and restarted for each file transmitted. This is necessary in order to pass the resulting size to the remote .Xr lpd 8 . .Pp If the .Fl p flag was passed to .Xr lpr 1 , .Xr pr 1 is not executed locally, but is requested of the remote .Xr lpd 8 . Any input filtering via .Cm if will therefore happen before .Xr pr 1 is executed rather than afterwards. .Pp If .Cm lp is specified as .Em port Ns No @ Ns Em machine (and .Cm rm is not in use), printing will be send directly to the given .Em port on the given .Em machine . .Sh TRANSFER STATISTICS When a print job is transfered to a remote machine (which might be another unix box, or may be a network printer), it may be useful to keep statistics on each transfer. The .Cm sr and .Cm ss options indicate filenames that lpd should use to store such statistics. A statistics line is written for each datafile of a job as the file is successfully transferred. The format of the line is the same for both the sending and receiving side of a transfer. .Pp Statistics on datafiles being received would be used on a print server, if you are interested in network performance between a variety of machines which are sending jobs to that print server. The print server could collect statistics on the speed of each print job as it arrived on the server. .Pp Statistics on datafiles being sent might be used as a minimal accounting record, when you want to know who sent which jobs to a remote printer, when they were sent, and how large (in bytes) the files were. This will not give include any idea of how many pages were printed, because there is no standard way to get that information back from a remote (network) printer in this case. .Sh LOGGING Error messages generated by the line printer programs themselves (that is, the .Xr lpd 8 and related programs) are logged by .Xr syslog 3 using the .Dv LPR facility. Messages printed on .Em stderr of one of the filters are sent to the corresponding .Cm lf file. The filters may, of course, use -.Xr syslog 8 +.Xr syslogd 8 themselves. .Pp Error messages sent to the console have a carriage return and a line feed appended to them, rather than just a line feed. .Sh SEE ALSO .Xr lpq 1 , .Xr lpr 1 , .Xr lprm 1 , .Xr hosts.lpd 5 , .Xr termcap 5 , .Xr lpc 8 , .Xr lpd 8 , .Xr pac 8 .Rs .%T "4.3 BSD Line Printer Spooler Manual" .Re .Sh HISTORY The .Nm file format appeared in .Bx 4.2 . Index: stable/4/usr.sbin/nghook/nghook.8 =================================================================== --- stable/4/usr.sbin/nghook/nghook.8 (revision 78135) +++ stable/4/usr.sbin/nghook/nghook.8 (revision 78136) @@ -1,92 +1,92 @@ .\" Copyright (c) 1996-1999 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" $Whistle: nghook.8,v 1.4 1999/01/20 03:19:45 archie Exp $ .\" .Dd January 19, 1999 .Dt NGHOOK 8 .Os FreeBSD .Sh NAME .Nm nghook .Nd connect to a .Xr netgraph 4 node .Sh SYNOPSIS .Nm .Op Fl a .Op Fl d .Ar path .Op Ar hookname .Sh DESCRIPTION .Nm creates a -.Xr ng_socket 8 +.Xr ng_socket 4 socket type node and connects it to hook .Ar hookname of the node found at .Ar path . If .Ar hookname is omitted, .Dq debug is assumed. .Pp At this point all data written to standard input is sent to the node and all data received from the node is relayed to standard output. .Pp The options are as follows: .Pp .Bl -tag -width indent .It Fl a Output each read packet in .Tn ASCII . .It Fl d Increase the debugging verbosity level. .El .Sh BUGS Although all input is read in unbuffered mode, there's no way to control the packetization of the input. .Sh SEE ALSO .Xr netgraph 4 , .Xr netgraph 3 , .Xr ngctl 8 . .Sh HISTORY The .Em netgraph system was designed and first implemented at Whistle Communications, Inc. in a version of .Fx 2.2 customized for the Whistle InterJet. .Sh AUTHOR .An Archie Cobbs Aq archie@whistle.com Index: stable/4/usr.sbin/ppp/ppp.8 =================================================================== --- stable/4/usr.sbin/ppp/ppp.8 (revision 78135) +++ stable/4/usr.sbin/ppp/ppp.8 (revision 78136) @@ -1,5617 +1,5617 @@ .\" .\" 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 September 20, 1995 .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. Normally, .Em PPP is implemented as a part of the kernel (e.g., as managed by .Xr pppd 8 ) and it's 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. .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 isn't 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 receiving incoming connections. .Nm ignores the .Dq set device line and uses descriptor 0 as the link. .Pp If callback is configured, .Nm will use the .Dq set device information when dialing back. .It Fl dedicated This option is designed for machines connected with a dedicated wire. .Nm will always keep the device open and will never use any configured chat scripts. .It Fl ddial This mode is equivalent to .Fl auto mode except that .Nm will bring the link back up any time it's 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 .Pq 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 (ftp://ftp.microsoft.com/developr/rfc/cbcp.txt). .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) 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 .Pa libradius 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 ISDN. If .Nm is given a raw B-channel i4b device to open as a link, it's able to talk to the .Xr isdnd 8 daemon to establish an ISDN connection. .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 pppoe 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. .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're 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 Your kernel must include a tunnel device (the GENERIC kernel includes one by default). If it doesn't, or if you require more than one tun interface, you'll need to rebuild your kernel with the following line in your kernel configuration file: .Pp .Dl pseudo-device tun N .Pp where .Ar N is the maximum number of .Em PPP connections you wish to support. .It Check your .Pa /dev directory for the tunnel device entries .Pa /dev/tunN , where .Sq N represents the number of the tun device, starting at zero. If they don't exist, you can create them by running "sh ./MAKEDEV tunN". This will create tun devices 0 through .Ar N . .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 . Don't 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 .Pq using Xr named 8 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/cuaa0 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 can't 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'll 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's 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 .Pq 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/cuaa0 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's 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 couldn't 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 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. .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's 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 now supports .Sq sticky routes , where all routes that contain the .Dv HISADDR or .Dv MYADDR literals will automatically be updated when the values of .Dv HISADDR and/or .Dv MYADDR 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 , .Pq for example, Dq 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 Xo .Oo + Ns Ar inc Ns .Op - Ns Ar max Ns .Oc Ns Op . Ns Ar next .Op Ar attempts .Xc .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, .Pp .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 .Pp .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 Don't 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/cuaa1 ppp ON awfulhak> set speed 38400 ppp ON awfulhak> term deflink: Entering terminal mode on /dev/cuaa1 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 .Pp .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 .Pq 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 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 .Pq 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 doesn't 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 Don't forget to send a .Dv HUP signal to .Xr inetd 8 after you've 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'll 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 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're enabling PAP, you'll also need this in the .Pa /etc/ppp/ppp.conf profile: .Bd -literal -offset indent set authname MyAuthName set authkey MyAuthKey .Ed .Pp We're 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 .Pq 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 accross 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've 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). .Pp .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. .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 or .Dv HISADDR (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 must be one of .Sq icmp , .Sq igmp , .Sq ipip , .Sq ospf , .Sq udp or .Sq tcp . .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 .Pp .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's 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 .Pq 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 .Pq 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 .Pq 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 .Nm uses IPCP to negotiate IP addresses. Each side of the connection specifies the IP address that it's willing to use, and if the requested IP address is acceptable then .Nm returns 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 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 won't 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'd like to use 192.244.177.38 as my address if it is possible, but I'll also accept any IP address between 192.244.177.0 and 192.244.177.255. .It I'd like to make him use 192.244.177.2 as his own address, but I'll 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'll accept/permit any IP address but I'll try to insist that 192.244.177.2 be used first. .El .Pp .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 Xo .Oo \&| Ns Ar backupnumber .Oc Ns ... Ns Oo : Ns Ar nextnumber .Oc Ns ... .Xc .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's 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's 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're 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/cuaa0 set speed 115200 .Ed .Pp Cuaa0 is the first serial port on .Fx . If you're 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 don't 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 .Pp .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 . .Pp This tells .Nm to add a default route to whatever the peer address is .Pq 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. .Pp Previous versions of .Nm required a similar entry in the .Pa /etc/ppp/ppp.linkup file. Since the advent of .Sq sticky routes , this is no longer required. .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 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 couldn't 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 .Pp .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 .Pq 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 .Pq 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: .Pp .Bd -literal -offset indent mp: set timeout 0 set log phase chat set device /dev/cuaa0 /dev/cuaa1 /dev/cuaa2 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. .Pp .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: .Pp .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: .Pp .Bd -literal -offset indent link 1 set device /dev/cuaa0 link 2 set device /dev/cuaa1 link 3 set device /dev/cuaa2 .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 .Xr pppd 8 - 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 Ns ! .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 .Xr pppd 8 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 doesn't agree, .Nm will send ECHO LQR requests instead. These packets pass no information of interest, but they .Em MUST be replied to by the peer. .Pp Whether using LQR or ECHO LQR, .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. .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, .Xr pppd 8 (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 .Pq 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 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's 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 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 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 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 or .Dv MYADDR values, entries are stored in the .Sq stick route list. Each time .Dv HISADDR or .Dv MYADDR 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 Op tcp Ns Xo .No mssfixup .Xc Default: Enabled. This option tells .Nm to adjust outgoing 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. .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 .Pq 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 . .El .Pp .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 or .Sq HISADDR as the destination, and .Sq HISADDR as the .Ar gateway . .Sq MYADDR is replaced with the interface address and .Sq HISADDR is replaced with the interface destination (peer) address. .Pp If the .Ar add!\& command is used .Pq 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 DNS0 , or .Dq DNS1 constants are considered .Sq sticky . They are stored in a list (use .Dq show ipcp to see the list), and each time the value of .Dv HISADDR , .Dv MYADDR , .Dv DNS0 , or .Dv DNS1 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's 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 .Pp .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 doesn't 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 Ns .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 .Pq 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 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 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. .Pp .It Op !\& Ns Xo .No bg Ar command .Xc The given .Ar command is executed in the background with the following words replaced: .Bl -tag -width PEER_ENDDISC .It Li AUTHNAME This is replaced with the local .Ar authname value. See the .Dq set authname command below. .It Li COMPILATIONDATE This is replaced with the date on which .Nm was compiled. .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 INTERFACE This is replaced with the name of the interface that's in use. .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 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 VERSION This is replaced with the current version number of .Nm . .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. .El .Pp These substitutions are also done by the .Dq set proctitle command. .Pp If you wish to pause .Nm while the command executes, use the .Dq shell command instead. .It clear physical|ipcp Op current|overall|peak... Clear the specified throughput values at either the .Dq physical or .Dq ipcp 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've 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 .Pq 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 .Pq note the trailing Dq !\& , .Nm will not complain if the route does not already exist. .It dial|call Op Ar label 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's not considered polite to use this command on a Finite State Machine that's 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 .Pq 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 If this command is used while .Nm is in the OPENED state or while in .Fl auto mode, all addresses except for the IPCP 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 .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 isn't currently assigned to the interface (and no deletion takes place). .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 Op data Ns Xo .No link .Ar name Ns Op , Ns Ar name Ns .No ... 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 Op Ar label 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 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's 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 cuaa0 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 Op auth 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 .Pq 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's 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 .Pq 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's 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): .Pp .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 .Pp .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's not set, .Nm assumes that this is because the device doesn't support carrier (which is true for most .Dq laplink NULL-modem cables), logs the fact and stops checking for carrier. .Pp As ptys don't support the TIOCMGET ioctl, the tty device will switch all carrier detection off when it detects that the device is a pty. .It ISDN (i4b) Devices Carrier is checked once per second for 6 seconds. If it's not set after the sixth second, the connection attempt is considered to have failed and the device is closed. Carrier is always required for i4b devices. .It PPPoE (netgraph) Devices Carrier is checked once per second for 5 seconds. If it's 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 don't 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 isn't increased, this will result in .Nm Ns No 's inability to detect when the link is dropped, as .Nm assumes that the device isn't 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 isn't 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 ISDN and serial device names are expected to begin with .Pa /dev/ . ISDN devices are usually called .Pa i4brbchX and 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 pppoe 8 program available under OpenBSD. 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. Refer to .Xr netgraph 4 and -.Xr ng_pppoe 8 +.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 [ tcp|udp|ospf|ipip|igmp|icmp 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 doesn't 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 Xo .Oc Ns Oo , Ns Ar \&IP Ns .Op \&- Ns Ar \&IP Ns .Oc Ns ... .Xc .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's 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 isn't 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 .Pq 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 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 Ar frequency This command sets the .Ar frequency in seconds at which .Em LQR or .Em ECHO LQR packets are sent. The default is 30 seconds. You must also use the .Dq enable lqr command if you wish to send LQR 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 {40|56|128} This option selects particular key length. Default is 128. .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 Op Ar value The default MRU (Maximum Receive Unit) is 1500. If it is increased, the other side *may* increase its MTU. There is no point in decreasing the MRU to below the default as the .Em PPP protocol *must* be able to accept packets of at least 1500 octets. If no argument is given, 1500 is assumed. .It set mtu Op Ar value The default MTU is 1500. At negotiation time, .Nm will accept whatever MRU or MRRU that the peer wants (assuming it's not less than 296 bytes). If the MTU is set, .Nm will not accept MRU/MRRU values less than .Ar value . When negotiations are complete, the MTU is assigned to the interface, even if the peer requested a higher value MRU/MRRU. This can be useful for limiting your packet size (giving better bandwidth sharing at the expense of more header data). .Pp If no .Ar value is given, 1500, or whatever the peer asks for is used. .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 Op proc 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's compiled in). .Ar config-file refers to the radius client configuration file as described in .Xr radius.conf 5 . If PAP or CHAP 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 neither PAP or CHAP 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_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 sepcify 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 don't include the .Dv MYADDR or .Dv HISADDR keywords. .Pp .El Values received from the RADIUS server may be viewed using .Dq show bundle . .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 .Op - Ns Ar max Ns .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 doesn't 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 doesn't 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 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 .Pp .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 .Pq 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 Op data 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 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 .Pp .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 .Pp .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's available. .It The following URLs contain useful information: .Bl -bullet -compact .It http://www.FreeBSD.org/FAQ/userppp.html .It http://www.FreeBSD.org/handbook/userppp.html .El .Pp .El .Pp .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/syslogd.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 .Pp .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 libalias 3 , .Xr syslog 3 , .Xr uucplock 3 , .Xr netgraph 4 , .Xr crontab 5 , .Xr group 5 , .Xr passwd 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 isdn 8 , .Xr named 8 , -.Xr ng_pppoe 8 , +.Xr ng_pppoe 4 , .Xr ping 8 , .Xr pppctl 8 , .Xr pppd 8 , .Xr pppoe 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 tony-o@iij.ad.jp , and was submitted to .Fx 2.0.5 by .An Atsushi Murai Aq amurai@spec.co.jp . .Pp It was substantially modified during 1997 by .An Brian Somers Aq 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.