docs: Added All OpenBSD Manuals

1 files changed, 1515 insertions, 0 deletions

diff --git a/static/openbsd/man8/pppd.8 b/static/openbsd/man8/pppd.8
new file mode 100644
index 00000000..911253b8
--- /dev/null
+++ b/static/openbsd/man8/pppd.8
@@ -0,0 +1,1515 @@
+.\" $OpenBSD: pppd.8,v 1.48 2022/03/31 17:27:31 naddy Exp $
+.\" Id: pppd.8,v 1.27 1998/03/31 04:31:08 paulus Exp $
+.\"
+.\" Copyright (c) 1993-2003 Paul Mackerras <paulus@samba.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: March 31 2022 $
+.Dt PPPD 8
+.Os
+.Sh NAME
+.Nm pppd
+.Nd Point-to-Point Protocol daemon
+.Sh SYNOPSIS
+.Nm pppd
+.Op Ar tty_name
+.Op Ar speed
+.Op Ar options
+.Sh DESCRIPTION
+PPP is the protocol used for establishing internet links over dial-up
+modems, DSL connections, and many other types of point-to-point links.
+The
+.Nm
+daemon works together with the kernel
+.Xr ppp 4
+driver to establish and maintain a PPP link with another system
+(called the
+.Em peer )
+and to negotiate Internet Protocol (IP) addresses for each end of the link.
+.Nm
+can also authenticate the peer and/or supply authentication information
+to the peer.
+PPP can be used with other network protocols besides IP, but such use
+is becoming increasingly rare.
+.Sh FREQUENTLY USED OPTIONS
+.Bl -tag -width Ds
+.It Ar tty_name
+Use the serial port called
+.Ar ttyname
+to communicate with the peer.
+The string
+.Dq /dev/
+is prepended to
+.Ar ttyname
+to form the name of the device to open.
+If no device name is given, or if the name of the terminal
+connected to the standard input is given,
+.Nm
+will use that terminal, and will not fork to put itself in the background.
+This option is privileged if the
+.Cm noauth
+option is used.
+.It Ar speed
+An option that is a decimal number is taken as the desired baud rate
+for the serial device.
+On systems such as
+.Bx 4.4
+and
+.Ox ,
+any speed can be specified.
+Other systems (e.g., Linux, SunOS) only support the commonly used
+baud-rates.
+.It Cm active-filter Ar filter-expression
+Specifies a packet filter to be applied to data packets to determine
+which packets are to be regarded as link activity, and therefore reset
+the idle timer, or cause the link to be brought up in demand-dialling
+mode.
+This option is useful in conjunction with the
+.Cm idle
+option if there are packets being sent or received regularly over the link
+(for example, routing information packets)
+which would otherwise prevent the link from ever appearing to be idle.
+The
+.Ar filter-expression
+syntax is as described for
+.Xr tcpdump 8 ,
+except that qualifiers which are inappropriate for a PPP link, such as
+.Ar ether
+and
+.Ar arp ,
+are not permitted.
+Generally the filter expression should be enclosed in single quotes to
+prevent whitespace in the expression from being interpreted by the shell.
+.It Cm asyncmap Ar map
+This option sets the Async-Control-Character-Map (ACCM) for this end
+of the link.
+The ACCM is a set of 32 bits, one for each of the ASCII control characters
+with values from 0 to 31, where a 1 bit indicates that the corresponding
+control character should not be used in PPP packets sent to this system.
+The map is encoded as a hexadecimal number (without a leading 0x) where the
+least significant bit (00000001) represents character 0 and the
+most significant bit (80000000) represents character 31.
+.Nm
+will ask the peer to send these characters as a 2-byte escape sequence.
+If multiple
+.Cm asyncmap
+options are given, the values are ORed together.
+If no
+.Cm asyncmap
+option is given, no async character map will be negotiated for the receive
+direction; the peer should then escape
+.Em all
+control characters.
+To escape transmitted characters, use the
+.Cm escape
+option.
+.It Cm auth
+Require the peer to authenticate itself before allowing network
+packets to be sent or received.
+.It Cm call Ar name
+Read options from the file
+.Pa /etc/ppp/peers/name .
+This file may contain privileged options, such as
+.Cm noauth ,
+even if
+.Nm
+is not being run by root.
+The
+.Ar name
+string may not begin with
+.Qq /
+or include
+.Qq ..
+as a pathname component.
+The format of the options file is described below.
+.It Cm connect Ar script
+Usually there is something which needs to be done to prepare the link
+before the PPP protocol can be started; for instance, with a dial-up
+modem, commands need to be sent to the modem to dial the appropriate
+phone number.
+This option specifies a command for
+.Nm
+to execute (by passing it to a shell) before attempting to start PPP
+negotiation.
+The
+.Xr chat 8
+program is often useful here, as it provides a way to send arbitrary strings
+to a modem and respond to received characters.
+This option is privileged if the
+.Cm noauth
+option is used.
+.It Cm crtscts
+Specifies that
+.Nm
+should set the serial port to use hardware flow control using the RTS and CTS
+signals in the RS-232 interface.
+If neither the
+.Cm crtscts
+nor the
+.Cm nocrtscts
+option is given, the hardware flow control setting for the serial port
+is left unchanged.
+.It Cm defaultroute
+Add a default route to the system routing tables, using the peer as
+the gateway, when IPCP negotiation is successfully completed.
+This entry is removed when the PPP connection is broken.
+This option is privileged if the
+.Cm nodefaultroute
+option has been specified.
+.It Cm disconnect Ar script
+Execute the command specified by
+.Ar script ,
+by passing it to a shell,
+after
+.Nm
+has terminated the link.
+This command could, for example, issue commands to the modem to cause it
+to hang up if hardware modem control signals were not available.
+The disconnect script is not run if the modem has already hung up.
+This option is privileged if the
+.Cm noauth
+option is used.
+.It Cm escape Ar xx,yy,...
+Specifies that certain characters should be escaped on transmission
+(regardless of whether the peer requests them to be escaped with its
+async control character map).
+The characters to be escaped are specified as a list of hex numbers
+separated by commas.
+Note that almost any character can be specified for the
+.Cm escape
+option, unlike the
+.Cm asyncmap
+option which only allows control characters to be specified.
+The characters which may not be escaped are those with hex values
+0x20 \- 0x3f or 0x5e.
+.It Cm file Ar name
+Read options from file
+.Ar name
+(the format is described below).
+The file must be readable by the user who has invoked
+.Nm pppd .
+.It Cm lock
+Specifies that
+.Nm
+should create a UUCP-style lock file for the
+serial device to ensure exclusive access to the device.
+.It Cm mru Ar n
+Set the MRU (Maximum Receive Unit) value to
+.Ar n .
+.Nm
+will ask the peer to send packets of no more than
+.Ar n
+bytes.
+The value of
+.Ar n
+must be between 128 and 16384; the default is 1500.
+A value of 296 works well on very slow links
+(40 bytes for TCP/IP header + 256 bytes of data).
+Note that for the IPv6 protocol, the MRU must be at least 1280.
+.It Cm mtu Ar n
+Set the MTU (Maximum Transmit Unit) value to
+.Ar n .
+Unless the peer requests a smaller value via MRU negotiation,
+.Nm
+will request that the kernel networking code send data packets of no more than
+.Ar n
+bytes through the PPP network interface.
+Note that for the IPv6 protocol, the MTU must be at least 1280.
+.It Cm passive
+Enables the
+.Qq passive
+option in the LCP.
+With this option,
+.Nm
+will attempt to initiate a connection; if no reply is received from the peer,
+.Nm
+will then just wait passively for a valid LCP packet from the peer,
+instead of exiting, as it would without this option.
+.El
+.Sh OPTIONS
+.Bl -tag -width Ds
+.It Xo
+.Oo Ar local_IP_address Oc : Ns
+.Op Ar remote_IP_address
+.Xc
+Set the local and/or remote interface IP addresses.
+Either one may be omitted.
+The IP addresses can be specified with a host name or in
+decimal dot notation (e.g., 150.234.56.78).
+The default local address is the (first) IP address of the system (unless the
+.Cm noipdefault
+option is given).
+The remote address will be obtained from the peer
+if not specified in any option.
+Thus, in simple cases, this option is not required.
+If a local and/or remote IP address is specified with this option,
+.Nm
+will not accept a different value from the peer in the IPCP negotiation,
+unless the
+.Cm ipcp-accept-local
+and/or
+.Cm ipcp-accept-remote
+options are given, respectively.
+.It Cm bsdcomp Ar nr,nt
+Request that the peer compress packets that it sends, using the
+BSD-Compress scheme, with a maximum code size of
+.Ar nr
+bits, and agree to compress packets sent to the peer with
+a maximum code size of
+.Ar nt
+bits.
+If
+.Ar nt
+is not specified, it defaults to the value given for
+.Ar nr .
+Values in the range 9 to 15 may be used for
+.Ar nr
+and
+.Ar nt ;
+larger values give better compression but
+consume more kernel memory for compression dictionaries.
+Alternatively, a value of 0 for
+.Ar nr
+or
+.Ar nt
+disables compression in the corresponding direction.
+.Cm nobsdcomp
+or
+.Cm bsdcomp 0
+disables BSD-Compress compression entirely.
+.It Cm chap-interval Ar n
+If this option is given,
+.Nm
+will rechallenge the peer every
+.Ar n
+seconds.
+.It Cm chap-max-challenge Ar n
+Set the maximum number of CHAP challenge transmissions to
+.Ar n
+(default 10).
+.It Cm chap-restart Ar n
+Set the CHAP restart interval (retransmission timeout for challenges) to
+.Ar n
+seconds (default 3).
+.It Cm debug
+Enables connection debugging facilities.
+If this option is given,
+.Nm
+will log the contents of all control packets sent or received in a
+readable form.
+The packets are logged through
+.Xr syslogd 8
+with facility
+.Ar daemon
+and level
+.Ar debug .
+This information can be directed to a file by setting up
+.Pa /etc/syslog.conf
+appropriately (see
+.Xr syslog.conf 5 ) .
+.It Cm default-asyncmap
+Disable asyncmap negotiation, forcing all control characters to be
+escaped for both the transmit and the receive direction.
+.It Cm default-mru
+Disable MRU (Maximum Receive Unit) negotiation.
+With this option,
+.Nm
+will use the default MRU value of 1500 bytes for both the
+transmit and receive direction.
+.It Cm deflate Ar nr,nt
+Request that the peer compress packets that it sends, using the
+Deflate scheme, with a maximum window size of
+.Ar 2**nr
+bytes, and agree to compress packets sent to the peer with
+a maximum window size of
+.Ar 2**nt
+bytes.
+If
+.Ar nt
+is not specified, it defaults to the value given for
+.Ar nr .
+Values in the range 8 to 15 may be used for
+.Ar nr
+and
+.Ar nt ;
+larger values give better compression but consume more kernel memory
+for compression dictionaries.
+Alternatively, a value of 0 for
+.Ar nr
+or
+.Ar nt
+disables compression in the corresponding direction.
+Use
+.Cm nodeflate
+or
+.Cm deflate 0
+to disable Deflate compression entirely.
+(Note:
+.Nm
+requests Deflate compression in preference to BSD-Compress if the peer
+can do either.)
+.It Cm demand
+Initiate the link only on demand, i.e., when data traffic is present.
+With this option, the remote IP address must be specified by the user
+on the command line or in an options file.
+.Nm
+will initially configure the interface and enable it for IP traffic without
+connecting to the peer.
+When traffic is available,
+.Nm
+will connect to the peer and perform negotiation, authentication, etc.
+When this is completed,
+.Nm
+will commence passing data packets (i.e., IP packets) across the link.
+.Pp
+The
+.Cm demand
+option implies the
+.Cm persist
+option.
+If this behaviour is not desired, use the
+.Cm nopersist
+option after the
+.Cm demand
+option.
+The
+.Cm idle
+and
+.Cm holdoff
+options are also useful in conjunction with the
+.Cm demand
+option.
+.It Cm domain Ar d
+Append the domain name
+.Ar d
+to the local host name for authentication purposes.
+For example, if
+.Xr gethostname 3
+returns the name porsche, but the fully qualified domain name is
+porsche.Quotron.COM, you could specify
+.Cm domain Quotron.COM .
+.Nm
+would then use the name
+.Ar porsche.Quotron.COM
+for looking up secrets in the secrets file, and as the default name to
+send to the peer when authenticating itself to the peer.
+This option is privileged.
+.It Cm holdoff Ar n
+Specifies how many seconds to wait before re-initiating the link after
+it terminates.
+This option only has any effect if the
+.Cm persist
+or
+.Cm demand
+option is used.
+The holdoff period is not applied if the link was terminated
+because it was idle.
+.It Cm idle Ar n
+Specifies that
+.Nm
+should disconnect if the link is idle for
+.Ar n
+seconds.
+The link is idle when no data packets (i.e., IP packets) are
+being sent or received.
+Note: it is not advisable to use this option with the
+.Cm persist
+option without the
+.Cm demand
+option.
+If the
+.Cm active-filter
+option is given, data packets which are rejected by the specified
+activity filter also count as the link being idle.
+.It Cm ipcp-accept-local
+With this option,
+.Nm
+will accept the peer's idea of our local IP address,
+even if the local IP address was specified in an option.
+.It Cm ipcp-accept-remote
+With this option,
+.Nm
+will accept the peer's idea of its (remote) IP address,
+even if the remote IP address was specified in an option.
+.It Cm ipcp-max-configure Ar n
+Set the maximum number of IPCP configure-request transmissions to
+.Ar n
+(default 10).
+.It Cm ipcp-max-failure Ar n
+Set the maximum number of IPCP configure-NAKs returned before starting
+to send configure-Rejects to
+.Ar n
+(default 10).
+.It Cm ipcp-max-terminate Ar n
+Set the maximum number of IPCP terminate-request transmissions to
+.Ar n
+(default 3).
+.It Cm ipcp-restart Ar n
+Set the IPCP restart interval (retransmission timeout) to
+.Ar n
+seconds (default 3).
+.It Cm ipparam Ar string
+Provides an extra parameter to the ip-up and ip-down scripts.
+If this option is given, the
+.Ar string
+supplied is given as the 6th parameter to those scripts.
+.It Cm kdebug Ar n
+Enable debugging code in the kernel-level PPP driver.
+The argument
+.Ar n
+is a number which is the sum of the following values:
+1 to enable general debug messages,
+2 to request that the contents of received packets be printed,
+and 4 to request that the contents of transmitted packets be printed.
+On most systems, messages printed by the kernel are logged by
+.Xr syslogd 8
+to a file as directed in the
+.Pa /etc/syslog.conf
+configuration file.
+.It Cm lcp-echo-failure Ar n
+If this option is given,
+.Nm
+will presume the peer to be dead if
+.Ar n
+LCP echo-requests are sent without receiving a valid LCP echo-reply.
+If this happens,
+.Nm
+will terminate the connection.
+Use of this option requires a non-zero value for the
+.Cm lcp-echo-interval
+parameter.
+This option can be used to enable
+.Nm
+to terminate after the physical connection has been broken
+(e.g., the modem has hung up) in situations where no hardware modem
+control lines are available.
+.It Cm lcp-echo-interval Ar n
+If this option is given,
+.Nm
+will send an LCP echo-request frame to the peer every
+.Ar n
+seconds.
+Normally the peer should respond to the echo-request by sending an echo-reply.
+This option can be used with the
+.Cm lcp-echo-failure
+option to detect that the peer is no longer connected.
+.It Cm lcp-max-configure Ar n
+Set the maximum number of LCP configure-request transmissions to
+.Ar n
+(default 10).
+.It Cm lcp-max-failure Ar n
+Set the maximum number of LCP configure-NAKs returned before starting
+to send configure-Rejects to
+.Ar n
+(default 10).
+.It Cm lcp-max-terminate Ar n
+Set the maximum number of LCP terminate-request transmissions to
+.Ar n
+(default 3).
+.It Cm lcp-restart Ar n
+Set the LCP restart interval (retransmission timeout) to
+.Ar n
+seconds (default 3).
+.It Cm local
+Don't use the modem control lines.
+With this option,
+.Nm
+will ignore the state of the CD (Carrier Detect) signal from the modem
+and will not change the state of the DTR (Data Terminal Ready) signal.
+.It Cm login
+Use the system password database for authenticating the peer using
+PAP, and record the user in the system wtmp file.
+Note that the peer must have an entry in the
+.Pa /etc/ppp/pap-secrets
+file as well as the system password database to be allowed access.
+.It Cm maxconnect Ar n
+Terminate the connection when it has been available for network
+traffic for
+.Ar n
+seconds (i.e.,
+.Ar n
+seconds after the first network control protocol comes up).
+.It Cm modem
+Use the modem control lines.
+This option is the default.
+With this option,
+.Nm
+will wait for the CD (Carrier Detect) signal from the
+modem to be asserted when opening the serial device (unless a connect
+script is specified), and it will drop the DTR (Data Terminal Ready)
+signal briefly when the connection is terminated and before executing
+the connect script.
+On Ultrix, this option implies hardware flow control, as for the
+.Cm crtscts
+option.
+.It Cm modem_chat
+Use the modem control lines during the chat script.
+The default is to ignore the state of the CD (Carrier Detect) signal
+from the modem during the chat script.
+If you are using a
+.Xr cua 4
+device (as opposed to a
+.Xr tty 4
+device),
+you should set this option.
+You should not use this option with a dialback setup as it will cause
+the chat script to exit when carrier drops.
+.It Cm ms-dns Op Ar addr
+If
+.Nm
+is acting as a server for Microsoft Windows clients, this option allows
+.Nm
+to supply one or two DNS (Domain Name Server) addresses to the clients.
+The first instance of this option specifies the primary DNS address;
+the second instance (if given) specifies the secondary DNS address.
+(This option was present in some older versions of
+.Nm
+under the name
+.Cm dns-addr . )
+.It Cm ms-wins Op Ar addr
+If
+.Nm
+is acting as a server for Microsoft Windows or
+.Qq Samba
+clients,
+this option allows
+.Nm
+to supply one or two WINS (Windows Internet Name Services) server addresses
+to the clients.
+The first instance of this option specifies the primary WINS address;
+the second instance (if given) specifies the secondary WINS address.
+.It Cm name Ar name
+Set the name of the local system for authentication purposes to
+.Ar name .
+This is a privileged option.
+With this option,
+.Nm
+will use lines in the secrets files which have
+.Ar name
+as the second field when looking for a secret to use
+in authenticating the peer.
+In addition, unless overridden with the
+.Cm user
+option,
+.Ar name
+will be used as the name to send to the peer when authenticating the
+local system to the peer.
+(Note that
+.Nm
+does not append the domain name to
+.Ar name . )
+.It Cm netmask Ar n
+Set the interface netmask to
+.Ar n ,
+a 32-bit netmask in
+.Dq decimal dot
+notation (e.g. 255.255.255.0).
+If this option is given, the value specified is ORed with the default netmask.
+The default netmask is chosen based on the negotiated remote IP address;
+it is the appropriate network mask for the class of the remote IP address,
+ORed with the netmasks for any non point-to-point network interfaces in the
+system which are on the same network.
+(Note: on some platforms,
+.Nm
+will always use 255.255.255.255 for the netmask, if that is the only
+appropriate value for a point-to-point interface.)
+.It Cm noaccomp
+Disable Address/Control compression in both directions (send and receive).
+.It Cm noauth
+Do not require the peer to authenticate itself.
+This option is privileged if the
+.Cm auth
+option is specified in
+.Pa /etc/ppp/options .
+.It Cm nobsdcomp
+Disables BSD-Compress compression;
+.Nm
+will not request or agree to compress packets using the BSD-Compress scheme.
+.It Cm noccp
+Disable CCP (Compression Control Protocol) negotiation.
+This option should only be required if the peer is buggy and gets confused by
+requests from
+.Nm
+for CCP negotiation.
+.It Cm nocrtscts
+Disable hardware flow control (i.e., RTS/CTS) on the serial port.
+If neither the
+.Cm crtscts
+nor the
+.Cm nocrtscts
+option is given, the hardware flow control setting for the serial port
+is left unchanged.
+.It Cm nodefaultroute
+Disable the
+.Cm defaultroute
+option.
+The system administrator who wishes to prevent users from creating
+default routes with
+.Nm
+can do so by placing this option in the
+.Pa /etc/ppp/options
+file.
+.It Cm nodeflate
+Disables Deflate compression;
+.Nm
+will not request or agree to compress packets using the Deflate scheme.
+.It Cm nodetach
+Don't detach from the controlling terminal.
+Without this option, if a serial device other than the terminal
+on the standard input is specified,
+.Nm
+will fork to become a background process.
+.It Cm noip
+Disable IPCP negotiation and IP communication.
+This option should only be required if the peer is buggy and gets confused
+by requests from
+.Nm
+for IPCP negotiation.
+.It Cm noipdefault
+Disables the default behaviour when no local IP address is specified,
+which is to determine (if possible) the local IP address from the hostname.
+With this option, the peer will have to supply the local IP
+address during IPCP negotiation (unless it was specified explicitly
+on the command line or in an options file).
+.It Cm nomagic
+Disable magic number negotiation.
+With this option,
+.Nm
+cannot detect a looped-back line.
+This option should only be needed if the peer is buggy.
+.It Cm nopcomp
+Disable protocol field compression negotiation in both the receive and
+the transmit direction.
+.It Cm nopersist
+Exit once a connection has been made and terminated.
+This is the default unless the
+.Cm persist
+or
+.Cm demand
+option has been specified.
+.It Cm nopredictor1
+Do not accept or agree to Predictor-1 compression.
+.It Cm noproxyarp
+Disable the
+.Cm proxyarp
+option.
+The system administrator who wishes to prevent users from creating
+proxy ARP entries with
+.Nm
+can do so by placing this option in the
+.Pa /etc/ppp/options
+file.
+.It Cm novj
+Disable Van Jacobson style TCP/IP header compression in both the
+transmit and the receive direction.
+.It Cm novjccomp
+Disable the connection-ID compression option in Van Jacobson style
+TCP/IP header compression.
+With this option,
+.Nm
+will not omit the connection-ID byte from Van Jacobson compressed
+TCP/IP headers, nor ask the peer to do so.
+.It Cm papcrypt
+Indicates that all secrets in the
+.Pa /etc/ppp/pap-secrets
+file which are used for checking the identity of the peer are encrypted,
+and thus
+.Nm
+should not accept a password which, before encryption,
+is identical to the secret from the
+.Pa /etc/ppp/pap-secrets
+file.
+.It Cm pap-max-authreq Ar n
+Set the maximum number of PAP authenticate-request transmissions to
+.Ar n
+(default 10).
+.It Cm pap-restart Ar n
+Set the PAP restart interval (retransmission timeout) to
+.Ar n
+seconds (default 3).
+.It Cm pap-timeout Ar n
+Set the maximum time that
+.Nm
+will wait for the peer to authenticate itself with PAP to
+.Ar n
+seconds (0 means no limit).
+.It Cm pass-filter Ar filter-expression
+Specifies a packet filter to apply to data packets being sent or
+received to determine which packets should be allowed to pass.
+Packets which are rejected by the filter are silently discarded.
+This option can be used to prevent specific network protocols
+using up link bandwidth, or to provide a basic firewall capability.
+The
+.Ar filter-expression
+syntax is as described for
+.Xr tcpdump 8 ,
+except that qualifiers which are inappropriate for a PPP link, such as
+.Ar ether
+and
+.Ar arp ,
+are not permitted.
+Generally the filter expression should be enclosed in single quotes to prevent
+whitespace in the expression from being interpreted by the shell.
+Note that it is possible to apply different constraints to incoming and
+outgoing packets using the
+.Cm inbound
+and
+.Cm outbound
+qualifiers.
+.It Cm persist
+Do not exit after a connection is terminated; instead try to reopen
+the connection.
+.It Cm predictor1
+Request that the peer compress frames that it sends using Predictor-1
+compression, and agree to compress transmitted frames with Predictor-1
+if requested.
+This option has no effect unless the kernel driver supports Predictor-1
+compression.
+.It Cm proxyarp
+Add an entry to this system's ARP (Address Resolution Protocol) table
+with the IP address of the peer and the Ethernet address of this system.
+This will have the effect of making the peer appear to other
+systems to be on the local Ethernet.
+.It Cm remotename Ar name
+Set the assumed name of the remote system for authentication purposes to
+.Ar name .
+.It Cm refuse-chap
+With this option,
+.Nm
+will not agree to authenticate itself to the peer using CHAP.
+.It Cm refuse-pap
+With this option,
+.Nm
+will not agree to authenticate itself to the peer using PAP.
+.It Cm require-chap
+Require the peer to authenticate itself using CHAP
+(Challenge Handshake Authentication Protocol) authentication.
+.It Cm require-pap
+Require the peer to authenticate itself using PAP
+(Password Authentication Protocol) authentication.
+.It Cm silent
+With this option,
+.Nm
+will not transmit LCP packets to initiate a connection until a valid LCP
+packet is received from the peer (as for the `passive' option with ancient
+versions of
+.Nm pppd ) .
+.It Cm usehostname
+Enforce the use of the hostname (with domain name appended, if given)
+as the name of the local system for authentication purposes (overrides the
+.Cm name
+option).
+.It Cm user Ar name
+Sets the name used for authenticating the local system to the peer to
+.Ar name .
+.It Cm vj-max-slots Ar n
+Sets the number of connection slots to be used by the Van Jacobson
+TCP/IP header compression and decompression code to
+.Ar n ,
+which must be between 2 and 16, inclusive.
+.It Cm welcome Ar script
+Run the executable or shell command specified by
+.Ar script
+before initiating PPP negotiation, after the connect script (if any) has
+completed.
+This option is privileged if the
+.Cm noauth
+option is used.
+.It Cm xonxoff
+Use software flow control (i.e., XON/XOFF) to control the flow of data on
+the serial port.
+.El
+.Sh OPTIONS FILES
+Options can be taken from files as well as the command line.
+.Nm
+reads options from the files
+.Pa /etc/ppp/options , ~/.ppprc
+and
+.Pf /etc/ppp/options. Ar ttyname
+(in that order) before processing the options on the command line.
+(In fact, the command-line options are scanned to find the terminal name
+before the
+.Pf options. Ar ttyname
+file is read.)
+In forming the name of the
+.Pf options. Ar ttyname
+file,
+the initial /dev/ is removed from the terminal name, and any remaining
+/ characters are replaced with dots.
+.Pp
+An options file is parsed into a series of words, delimited by whitespace.
+Whitespace can be included in a word by enclosing the word in double-quotes (").
+A backslash (\e) quotes the following character.
+A hash (#) starts a comment, which continues until the end of the line.
+There is no restriction on using the
+.Cm file
+or
+.Cm call
+options within an options file.
+.Sh SECURITY
+Users must be in group
+.Qq network
+to be able to use
+.Nm pppd .
+.Pp
+.Nm
+provides system administrators with sufficient access control that PPP
+access to a server machine can be provided to legitimate users without
+fear of compromising the security of the server or the network it's on.
+In part this is provided by the
+.Pa /etc/ppp/options file ,
+where the administrator can place options to restrict the ways in which
+.Nm
+can be used, and in part by the PAP and CHAP secrets files, where the
+administrator can restrict the set of IP addresses which individual
+users may use.
+.Pp
+The normal way that
+.Nm
+should be set up is to have the
+.Cm auth
+option in the
+.Pa /etc/ppp/options
+file.
+(This may become the default in later releases.)
+If users wish to use
+.Nm
+to dial out to a peer which will refuse to authenticate itself
+(such as an internet service provider), the system administrator should
+create an options file under
+.Pa /etc/ppp/peers
+containing the
+.Cm noauth
+option, the name of the serial port to use, and the
+.Cm connect
+option (if required), plus any other appropriate options.
+In this way,
+.Nm
+can be set up to allow non-privileged users to make unauthenticated
+connections only to trusted peers.
+.Pp
+As indicated above, some security-sensitive options are privileged,
+which means that they may not be used by an ordinary non-privileged
+user running a setuid-root
+.Nm pppd ,
+either on the command line, in the user's
+.Pa ~/.ppprc
+file, or in an options file read using the
+.Cm file
+option.
+Privileged options may be used in the
+.Pa /etc/ppp/options
+file or in an options file read using the
+.Cm call
+option.
+If
+.Nm
+is being run by the root user, privileged options can be used without
+restriction.
+.Sh AUTHENTICATION
+Authentication is the process whereby one peer convinces the other of
+its identity.
+This involves the first peer sending its name to the other,
+together with some kind of secret information which could only
+come from the genuine authorized user of that name.
+In such an exchange, we will call the first peer the
+.Qq client
+and the other the
+.Qq server .
+The client has a name by which it identifies itself to the server,
+and the server also has a name by which it identifies itself to the client.
+Generally the genuine client shares some secret (or password) with the server,
+and authenticates itself by proving that it knows that secret.
+Very often, the names used for authentication correspond to the internet
+hostnames of the peers, but this is not essential.
+.Pp
+At present,
+.Nm
+supports two authentication protocols:
+the Password Authentication Protocol (PAP)
+and the Challenge Handshake Authentication Protocol (CHAP).
+PAP involves the client sending its name and a cleartext password
+to the server to authenticate itself.
+In contrast, the server initiates the CHAP authentication exchange by
+sending a challenge to the client (the challenge packet includes the
+server's name).
+The client must respond with a response which includes its name
+plus a hash value derived from the shared secret and the challenge,
+in order to prove that it knows the secret.
+.Pp
+The PPP protocol, being symmetrical, allows both peers to require the
+other to authenticate itself.
+In that case, two separate and independent authentication exchanges
+will occur.
+The two exchanges could use different authentication protocols,
+and in principle, different names could be used in the two exchanges.
+.Pp
+The default behaviour of
+.Nm
+is to agree to authenticate if requested, and to not require authentication
+from the peer.
+However,
+.Nm
+will not agree to authenticate itself with a particular protocol
+if it has no secrets which could be used to do so.
+.Pp
+.Nm
+stores secrets for use in authentication in secrets files
+.Pf ( Pa /etc/ppp/pap-secrets
+for PAP,
+.Pa /etc/ppp/chap-secrets
+for CHAP).
+Both secrets files have the same format.
+The secrets files can contain secrets for
+.Nm
+to use in authenticating itself to other systems, as well as secrets for
+.Nm
+to use when authenticating other systems to itself.
+.Pp
+Each line in a secrets file contains one secret.
+Any following words on the same line are taken to be a list
+of acceptable IP addresses for that client.
+If there are only 3 words on the line, or if the first word is
+.Qq \- ,
+then all IP addresses are disallowed.
+To allow any address, use
+.Qq * .
+A word starting with
+.Qq \&!
+indicates that the specified address is
+.Em not
+acceptable.
+An address may be followed by
+.Qq /
+and a number
+.Ar n ,
+to indicate a whole subnet, i.e., all addresses which have the same value
+in the most significant
+.Ar n
+bits.
+Case is significant in the client and server names and in the secret.
+.Pp
+If the secret starts with an `@', what follows is assumed to be the
+name of a file from which to read the secret.
+A
+.Qq *
+as the client or server name matches any name.
+When selecting a secret,
+.Nm
+takes the best match, i.e., the match with the fewest wildcards.
+.Pp
+Thus a secrets file contains both secrets for use in authenticating
+other hosts, plus secrets which we use for authenticating ourselves to
+others.
+When
+.Nm
+is authenticating the peer (checking the peer's identity), it chooses a
+secret with the peer's name in the first field and the name of the local
+system in the second field.
+The name of the local system defaults to the hostname, with the domain
+name appended if the
+.Cm domain
+option is used.
+This default can be overridden with the
+.Cm name
+option, except when the
+.Cm usehostname
+option is used.
+.Pp
+When
+.Nm
+is choosing a secret to use in authenticating itself to the peer,
+it first determines what name it is going to use to identify
+itself to the peer.
+This name can be specified by the user with the
+.Cm user
+option.
+If this option is not used, the name defaults to the name of the local system,
+determined as described in the previous paragraph.
+Then
+.Nm
+looks for a secret with this name in the first field and the peer's name
+in the second field.
+.Nm
+will know the name of the peer if CHAP authentication is being used, because
+the peer will have sent it in the challenge packet.
+However, if PAP is being used,
+.Nm
+will have to determine the peer's name from the options specified by the user.
+The user can specify the peer's name directly with the
+.Cm remotename
+option.
+Otherwise, if the remote IP address was specified by a name
+(rather than in numeric form), that name will be used as the peer's name.
+Failing that,
+.Nm
+will use the null string as the peer's name.
+.Pp
+When authenticating the peer with PAP, the supplied password is first
+compared with the secret from the secrets file.
+If the password doesn't match the secret, the password is encrypted using
+.Xr crypt 3
+and checked against the secret again.
+Thus secrets for authenticating the peer can be stored in encrypted form
+if desired.
+If the
+.Cm papcrypt
+option is given, the first (unencrypted) comparison is omitted,
+for better security.
+.Pp
+Furthermore, if the
+.Cm login
+option was specified, the username and password are also checked against
+the system password database.
+Thus, the system administrator can set up the pap-secrets file to allow PPP
+access only to certain users, and to restrict the set of IP addresses
+that each user can use.
+Typically, when using the
+.Cm login
+option, the secret in
+.Pa /etc/ppp/pap-secrets
+would be
+.Pq ,
+which will match any password supplied by the peer.
+This avoids the need to have the same secret in two places.
+.Pp
+Authentication must be satisfactorily completed before IPCP
+(or any other Network Control Protocol) can be started.
+If the peer is required to authenticate itself, and fails to do so,
+.Nm
+will terminate the link (by closing LCP).
+If IPCP negotiates an unacceptable IP address for the remote host,
+IPCP will be closed.
+IP packets can only be sent or received when IPCP is open.
+.Pp
+In some cases it is desirable to allow some hosts which can't
+authenticate themselves to connect and use one of a restricted set of
+IP addresses, even when the local host generally requires authentication.
+If the peer refuses to authenticate itself when requested,
+.Nm
+takes that as equivalent to authenticating with PAP
+using the empty string for the username and password.
+Thus, by adding a line to the pap-secrets file which specifies the empty
+string for the client and password, it is possible to allow restricted
+access to hosts which refuse to authenticate themselves.
+.Sh ROUTING
+When IPCP negotiation is completed successfully,
+.Nm
+will inform the kernel of the local and remote IP addresses for the PPP
+interface.
+This is sufficient to create a host route to the remote end of the
+link, which will enable the peers to exchange IP packets.
+Communication with other machines generally requires further
+modification to routing tables and/or ARP
+(Address Resolution Protocol) tables.
+In most cases the
+.Cm defaultroute
+and/or
+.Cm proxyarp
+options are sufficient for this, but in some cases
+further intervention is required.
+The
+.Pa /etc/ppp/ip-up
+script can be used for this.
+.Pp
+Sometimes it is desirable to add a default route through the remote
+host, as in the case of a machine whose only connection to the
+Internet is through the PPP interface.
+The
+.Cm defaultroute
+option causes
+.Nm
+to create such a default route when IPCP comes up, and
+delete it when the link is terminated.
+.Pp
+In some cases it is desirable to use proxy ARP, for example on a
+server machine connected to a LAN, in order to allow other hosts to
+communicate with the remote host.
+The
+.Cm proxyarp
+option causes
+.Nm
+to look for a network interface on the same subnet as the remote
+host (an interface supporting broadcast and ARP, which is up and not a
+point-to-point or loopback interface).
+If found,
+.Nm
+creates a permanent, published ARP entry with the IP address of the remote host
+and the hardware address of the network interface found.
+.Pp
+When the
+.Cm demand
+option is used, the interface IP addresses have
+already been set at the point when IPCP comes up.
+If
+.Nm
+has not been able to negotiate the same addresses that it used to configure
+the interface (for example when the peer is an ISP that uses dynamic
+IP address assignment),
+.Nm
+has to change the interface IP addresses to the negotiated addresses.
+This may disrupt existing connections, and the use of demand dialling with
+peers that do dynamic IP address assignment is not recommended.
+.Sh SCRIPTS
+.Nm
+invokes scripts at various stages in its processing which can be
+used to perform site-specific ancillary processing.
+These scripts are usually shell scripts, but could be executable code files
+instead.
+.Nm
+does not wait for the scripts to finish.
+.\" The scripts are executed as root (with the real and effective user ID set to 0),
+.\" so that they can do things such as update routing tables or run
+.\" privileged daemons.
+.\" Be careful that the contents of these scripts do not compromise your system's
+.\" security.
+.Nm
+runs the scripts with standard input, output and error redirected to
+.Pa /dev/null ,
+and with an environment that is empty except for some environment variables
+that give information about the link.
+The environment variables that
+.Nm
+sets are:
+.Bl -tag -width "PEERNAME"
+.It Ev DEVICE
+The name of the serial tty device being used.
+.It Ev IFNAME
+The name of the network interface being used.
+.It Ev IPLOCAL
+The IP address for the local end of the link.
+This is only set when IPCP has come up.
+.It Ev IPREMOTE
+The IP address for the remote end of the link.
+This is only set when IPCP has come up.
+.It Ev PEERNAME
+The authenticated name of the peer.
+This is only set if the peer authenticates itself.
+.It Ev SPEED
+The baud rate of the tty device.
+.It Ev UID
+The real user ID of the user who invoked
+.Nm pppd .
+.El
+.Pp
+.Nm
+invokes the following scripts, if they exist.
+It is not an error if they don't exist.
+.Bl -tag -width Ds
+.It Pa /etc/ppp/auth-up
+A program or script which is executed after the remote system
+successfully authenticates itself.
+It is executed with the parameters
+.Pp
+.Ar interface-name peer-name user-name tty-device speed
+.Pp
+Note that this script is not executed if the peer doesn't authenticate
+itself, for example when the
+.Cm noauth
+option is used.
+.It Pa /etc/ppp/auth-down
+A program or script which is executed when the link goes down, if
+.Pa /etc/ppp/auth-up
+was previously executed.
+It is executed in the same manner with the same parameters as
+.Pa /etc/ppp/auth-up .
+.It Pa /etc/ppp/ip-up
+A program or script which is executed when the link is available for
+sending and receiving IP packets (that is, IPCP has come up).
+It is executed with the parameters
+.Pp
+.Ar interface-name tty-device speed local-IP-address remote-IP-address ipparam
+.It Pa /etc/ppp/ip-down
+A program or script which is executed when the link is no longer
+available for sending and receiving IP packets.
+This script can be used for undoing the effects of the
+.Pa /etc/ppp/ip-up
+script.
+It is invoked in the same manner and with the same parameters as the ip-up
+script.
+.El
+.Sh FILES
+.Bl -tag -width Ds
+.It Pa /etc/ppp/pap-secrets
+Usernames, passwords and IP addresses for PAP authentication.
+This file should be owned by root and not readable or writable by any other
+user.
+.Nm
+will log a warning if this is not the case.
+.It Pa /etc/ppp/chap-secrets
+Names, secrets and IP addresses for CHAP authentication.
+As for
+.Pa /etc/ppp/pap-secrets ,
+this file should be owned by root and not readable or writable
+by any other user.
+.Nm
+will log a warning if this is not the case.
+.It Pa /etc/ppp/options
+System default options for
+.Nm pppd ,
+read before user default options or command-line options.
+.It Pa ~/.ppprc
+User default options, read before
+.Pf /etc/ppp/options. Ar ttyname .
+.It Pa /etc/ppp/options. Ns Ar ttyname
+System default options for the serial port being used, read after
+.Pa ~/.ppprc .
+In forming the
+.Ar ttyname
+part of this filename, an initial /dev/ is stripped from the port name (if
+present), and any slashes in the remaining part are converted to dots.
+.It Pa /etc/ppp/peers
+A directory containing options files which may contain privileged
+options, even if
+.Nm
+was invoked by a user other than root.
+The system administrator can create options files in this directory to
+permit non-privileged users to dial out without requiring the peer to
+authenticate, but only to certain trusted peers.
+.El
+.Sh EXAMPLES
+The following examples assume that the
+.Pa /etc/ppp/options
+file contains the
+.Cm auth
+option (as in the default
+.Pa /etc/ppp/options
+file in the PPP distribution).
+.Pp
+Probably the most common use of
+.Nm
+is to dial out to an ISP.
+This can be done with a command such as
+.Pp
+.Dl pppd call isp
+.Pp
+where the
+.Pa /etc/ppp/peers/isp
+file is set up by the system administrator to contain something like this:
+.Bd -literal -offset indent
+ttyS0 19200 crtscts
+connect '/usr/sbin/chat -v -f /etc/ppp/chat-isp'
+noauth
+.Ed
+.Pp
+In this example, we are using chat to dial the ISP's modem and go
+through any logon sequence required.
+The
+.Pa /etc/ppp/chat-isp
+file contains the script used by chat; it could for example contain
+something like this:
+.Bd -literal -offset indent
+ABORT "NO CARRIER"
+ABORT "NO DIALTONE"
+ABORT "ERROR"
+ABORT "NO ANSWER"
+ABORT "BUSY"
+ABORT "Username/Password Incorrect"
+"" "at"
+OK "at&d0&c1"
+OK "atdt2468135"
+"name:" "^Umyuserid"
+"word:" "\eqmypassword"
+"ispts" "\eq^Uppp"
+"~-^Uppp-~"
+.Ed
+.Pp
+See the
+.Xr chat 8
+man page for details of chat scripts.
+.Pp
+.Nm
+can also be used to provide a dial-in PPP service for users.
+If the users already have login accounts, the simplest way to set up the
+PPP service is to let the users log in to their accounts and run
+.Nm
+(installed setuid-root) with a command such as
+.Pp
+.Dl pppd proxyarp
+.Pp
+To allow a user to use the PPP facilities, you need to allocate an IP
+address for that user's machine and create an entry in
+.Pa /etc/ppp/pap-secrets
+or
+.Pa /etc/ppp/chap-secrets
+(depending on which authentication method the PPP implementation on the
+user's machine supports), so that the user's
+machine can authenticate itself.
+For example, if Joe has a machine called
+.Qq joespc
+which is to be allowed to dial in to the machine called
+.Qq server
+and use the IP address joespc.my.net, you would add an entry like this to
+.Pa /etc/ppp/pap-secrets
+or
+.Pa /etc/ppp/chap-secrets :
+.Pp
+.Dl joespc	server	"joe's secret"	joespc.my.net
+.Pp
+Alternatively, you can create a username called (for example)
+.Qq ppp ,
+whose login shell is
+.Nm
+and whose home directory is
+.Pa /etc/ppp .
+Options to be used when
+.Nm
+is run this way can be put in
+.Pa /etc/ppp/.ppprc .
+.Pp
+If your serial connection is any more complicated than a piece of
+wire, you may need to arrange for some control characters to be escaped.
+In particular, it is often useful to escape XON (^Q) and
+XOFF (^S), using
+.Cm asyncmap a0000 .
+If the path includes a telnet, you probably should escape ^] as well
+.Cm ( asyncmap 200a0000 ) .
+If the path includes an rlogin, you will need to use the
+.Cm escape ff
+option on the end which is running the rlogin client, since many
+rlogin implementations are not transparent; they will remove the
+sequence (0xff, 0xff, 0x73, 0x73, followed by any 8 bytes) from the stream.
+.Sh DIAGNOSTICS
+Messages are sent to the
+.Xr syslogd 8
+daemon using facility
+.Dv LOG_DAEMON .
+(This can be overridden by recompiling
+.Nm
+with the macro
+.Dv LOG_PPP
+defined as the desired facility.)
+See the
+.Xr syslogd 8
+documentation for details of where the syslog daemon will write the
+messages.
+On most systems, the syslog daemon uses the
+.Pa /etc/syslog.conf
+file to specify the destination(s) for syslog messages.
+You may need to edit that file to suit.
+.Pp
+The
+.Cm debug
+option causes the contents of all control packets sent
+or received to be logged, that is, all LCP, PAP, CHAP or IPCP packets.
+This can be useful if the PPP negotiation does not succeed or if
+authentication fails.
+If debugging is enabled at compile time, the
+.Cm debug
+option also causes other debugging messages to be logged.
+.Pp
+Debugging can also be enabled or disabled by sending a SIGUSR1 signal
+to the
+.Nm
+process.
+This signal acts as a toggle.
+.Sh SEE ALSO
+.Xr cua 4 ,
+.Xr ppp 4 ,
+.Xr tty 4 ,
+.Xr chat 8 ,
+.Xr syslogd 8 ,
+.Xr tcpdump 8
+.Rs
+.%A V. Jacobson
+.%D February 1990
+.%R RFC 1144
+.%T Compressing TCP/IP Headers for Low-Speed Serial Links
+.Re
+.Rs
+.%A R. Rivest
+.%D April 1992
+.%R RFC 1321
+.%T The MD5 Message-Digest Algorithm
+.Re
+.Rs
+.%A G. McGregor
+.%D May 1992
+.%R RFC 1332
+.%T The PPP Internet Protocol Control Protocol (IPCP)
+.Re
+.Rs
+.%A B. Lloyd
+.%A W. Simpson
+.%D October 1992
+.%R RFC 1334
+.%T PPP Authentication Protocols
+.Re
+.Rs
+.%A W. Simpson
+.%D July 1994
+.%R RFC 1661
+.%T The Point-to-Point Protocol (PPP)
+.Re
+.Rs
+.%A W. Simpson
+.%D July 1994
+.%R RFC 1662
+.%T PPP in HDLC-like Framing
+.Re
+.Rs
+.%A W. Simpson
+.%D August 1996
+.%R RFC 1994
+.%T PPP Challenge Handshake Authentication Protocol (CHAP)
+.Re
+.Sh NOTES
+Some limited degree of control can be exercised over a running
+.Nm
+process by sending it a signal from the list below.
+.Bl -tag -width Ds
+.It SIGINT , SIGTERM
+These signals cause
+.Nm
+to terminate the link (by closing LCP), restore the serial device settings,
+and exit.
+.It SIGHUP
+This signal causes
+.Nm
+to terminate the link, restore the serial device settings,
+and close the serial device.
+If the
+.Cm persist
+or
+.Cm demand
+option has been specified,
+.Nm
+will try to reopen the serial device and start another connection
+(after the holdoff period).
+Otherwise
+.Nm
+will exit.
+If this signal is received during the holdoff period, it causes
+.Nm
+to end the holdoff period immediately.
+.It SIGUSR1
+This signal toggles the state of the
+.Cm debug
+option.
+.It SIGUSR2
+This signal causes
+.Nm
+to renegotiate compression.
+This can be useful to re-enable compression after it has been disabled
+as a result of a fatal decompression error.
+(Fatal decompression errors generally indicate a bug
+in one or other implementation.)
+.El
+.Sh AUTHORS
+.An Paul Mackerras Aq Mt Paul.Mackerras@samba.org ,
+based on earlier work by Drew Perkins, Brad Clements, Karl Fox, Greg Christy,
+and Brad Parker.
+.Sh BUGS
+Scripts should be run as root,
+but are not.