From 40fc236df0b0f5d9f61030264e4c82e88719a52e Mon Sep 17 00:00:00 2001 From: Mystery Man Date: Sat, 14 Sep 2002 18:25:46 +0000 Subject: This commit was manufactured by cvs2svn to create tag 'V1_1_9_48mdk'. --- mdk-stage1/ppp/pppd/pppd.8 | 1591 -------------------------------------------- 1 file changed, 1591 deletions(-) delete mode 100644 mdk-stage1/ppp/pppd/pppd.8 (limited to 'mdk-stage1/ppp/pppd/pppd.8') diff --git a/mdk-stage1/ppp/pppd/pppd.8 b/mdk-stage1/ppp/pppd/pppd.8 deleted file mode 100644 index ab091cd83..000000000 --- a/mdk-stage1/ppp/pppd/pppd.8 +++ /dev/null @@ -1,1591 +0,0 @@ -.\" manual page [] for pppd 2.4 -.\" $Id$ -.\" SH section heading -.\" SS subsection heading -.\" LP paragraph -.\" IP indented paragraph -.\" TP hanging label -.TH PPPD 8 -.SH NAME -pppd \- Point to Point Protocol daemon -.SH SYNOPSIS -.B pppd -[ -.I tty_name -] [ -.I speed -] [ -.I options -] -.SH DESCRIPTION -.LP -The Point-to-Point Protocol (PPP) provides a method for transmitting -datagrams over serial point-to-point links. PPP -is composed of three parts: a method for encapsulating datagrams over -serial links, an extensible Link Control Protocol (LCP), and -a family of Network Control Protocols (NCP) for establishing -and configuring different network-layer protocols. -.LP -The encapsulation scheme is provided by driver code in the kernel. -Pppd provides the basic LCP, authentication support, and an NCP for -establishing and configuring the Internet Protocol (IP) (called the IP -Control Protocol, IPCP). -.SH FREQUENTLY USED OPTIONS -.TP -.I -Communicate over the named device. The string "/dev/" is prepended if -necessary. If no device name is given, or if the name of the terminal -connected to the standard input is given, pppd will use that terminal, -and will not fork to put itself in the background. A value for this -option from a privileged source cannot be overridden by a -non-privileged user. -.TP -.I -Set the baud rate to (a decimal number). On systems such as -4.4BSD and NetBSD, any speed can be specified. Other systems -(e.g. SunOS) allow only a limited set of speeds. -.TP -.B asyncmap \fI -Set the async character map to . This map describes which -control characters cannot be successfully received over the serial -line. Pppd will ask the peer to send these characters as a 2-byte -escape sequence. The argument is a 32 bit hex number with each bit -representing a character to escape. Bit 0 (00000001) represents the -character 0x00; bit 31 (80000000) represents the character 0x1f or ^_. -If multiple \fIasyncmap\fR options are given, the values are ORed -together. If no \fIasyncmap\fR option is given, no async character -map will be negotiated for the receive direction; the peer should then -escape \fIall\fR control characters. To escape transmitted -characters, use the \fIescape\fR option. -.TP -.B auth -Require the peer to authenticate itself before allowing network -packets to be sent or received. This option is the default if the -system has a default route. If neither this option nor the -\fInoauth\fR option is specified, pppd will only allow the peer to use -IP addresses to which the system does not already have a route. -.TP -.B call \fIname -Read options from the file /etc/ppp/peers/\fIname\fR. This file may -contain privileged options, such as \fInoauth\fR, even if pppd -is not being run by root. The \fIname\fR string may not begin with / -or include .. as a pathname component. The format of the options file -is described below. -.TP -.B connect \fIscript -Use the executable or shell command specified by \fIscript\fR to set -up the serial line. This script would typically use the chat(8) -program to dial the modem and start the remote ppp session. A value -for this option from a privileged source cannot be overridden by a -non-privileged user. -.TP -.B crtscts -Use hardware flow control (i.e. RTS/CTS) to control the flow of -data on the serial port. If neither the \fIcrtscts\fR, the -\fInocrtscts\fR, the \fIcdtrcts\fR nor the \fInocdtrcts\fR option -is given, the hardware flow control setting for the serial port is -left unchanged. -Some serial ports (such as Macintosh serial ports) lack a true -RTS output. Such serial ports use this mode to implement -unidirectional flow control. The serial port will -suspend transmission when requested by the modem (via CTS) -but will be unable to request the modem stop sending to the -computer. This mode retains the ability to use DTR as -a modem control line. -.TP -.B 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 \fInodefaultroute\fR option has been specified. -.TP -.B disconnect \fIscript -Run the executable or shell command specified by \fIscript\fR after -pppd has terminated the link. This script 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. A value for this option from a privileged -source cannot be overridden by a non-privileged user. -.TP -.B escape \fIxx,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 \fIescape\fR option, -unlike the \fIasyncmap\fR 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. -.TP -.B file \fIname -Read options from file \fIname\fR (the format is described below). -The file must be readable by the user who has invoked pppd. -.TP -.B init \fIscript -Run the executable or shell command specified by \fIscript\fR to -initialize the serial line. This script would typically use the -chat(8) program to configure the modem to enable auto answer. A value -for this option from a privileged source cannot be overridden by a -non-privileged user. -.TP -.B lock -Specifies that pppd should create a UUCP-style lock file for the -serial device to ensure exclusive access to the device. -.TP -.B mru \fIn -Set the MRU [Maximum Receive Unit] value to \fIn\fR. Pppd -will ask the peer to send packets of no more than \fIn\fR bytes. The -minimum MRU value is 128. The default MRU value is 1500. A value of -296 is recommended for slow links (40 bytes for TCP/IP header + 256 -bytes of data). (Note that for IPv6 MRU must be at least 1280) -.TP -.B mtu \fIn -Set the MTU [Maximum Transmit Unit] value to \fIn\fR. Unless the -peer requests a smaller value via MRU negotiation, pppd will -request that the kernel networking code send data packets of no more -than \fIn\fR bytes through the PPP network interface. (Note that for -IPv6 MTU must be at least 1280) -.TP -.B passive -Enables the "passive" option in the LCP. With this option, pppd will -attempt to initiate a connection; if no reply is received from the -peer, pppd will then just wait passively for a valid LCP packet from -the peer, instead of exiting, as it would without this option. -.SH OPTIONS -.TP -.I \fB:\fI -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 -\fInoipdefault\fR -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, pppd -will not accept a different value from the peer in the IPCP -negotiation, unless the \fIipcp-accept-local\fR and/or -\fIipcp-accept-remote\fR options are given, respectively. -.TP -.B ipv6 \fI\fR,\fI -Set the local and/or remote 64-bit interface identifier. Either one may be -omitted. The identifier must be specified in standard ascii notation of -IPv6 addresses (e.g. ::dead:beef). If the -\fIipv6cp-use-ipaddr\fR -option is given, the local identifier is the local IPv4 address (see above). -On systems which supports a unique persistent id, such as EUI-48 derived -from the Ethernet MAC address, \fIipv6cp-use-persistent\fR option can be -used to replace the \fIipv6 ,\fR option. Otherwise the -identifier is randomized. -.TP -.B active-filter \fIfilter-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 -\fBidle\fR 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 \fIfilter-expression\fR syntax is as described for tcpdump(1), -except that qualifiers which are inappropriate for a PPP link, such as -\fBether\fR and \fBarp\fR, 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. This option -is currently only available under NetBSD, and then only -if both the kernel and pppd were compiled with PPP_FILTER defined. -.TP -.B allow-ip \fIaddress(es) -Allow peers to use the given IP address or subnet without -authenticating themselves. The parameter is parsed as for each -element of the list of allowed IP addresses in the secrets files (see -the AUTHENTICATION section below). -.TP -.B bsdcomp \fInr,nt -Request that the peer compress packets that it sends, using the -BSD-Compress scheme, with a maximum code size of \fInr\fR bits, and -agree to compress packets sent to the peer with a maximum code size of -\fInt\fR bits. If \fInt\fR is not specified, it defaults to the value -given for \fInr\fR. Values in the range 9 to 15 may be used for -\fInr\fR and \fInt\fR; larger values give better compression but -consume more kernel memory for compression dictionaries. -Alternatively, a value of 0 for \fInr\fR or \fInt\fR disables -compression in the corresponding direction. Use \fInobsdcomp\fR or -\fIbsdcomp 0\fR to disable BSD-Compress compression entirely. -.TP -.B cdtrcts -Use a non-standard hardware flow control (i.e. DTR/CTS) to control -the flow of data on the serial port. If neither the \fIcrtscts\fR, -the \fInocrtscts\fR, the \fIcdtrcts\fR nor the \fInocdtrcts\fR -option is given, the hardware flow control setting for the serial -port is left unchanged. -Some serial ports (such as Macintosh serial ports) lack a true -RTS output. Such serial ports use this mode to implement true -bi-directional flow control. The sacrifice is that this flow -control mode does not permit using DTR as a modem control line. -.TP -.B chap-interval \fIn -If this option is given, pppd will rechallenge the peer every \fIn\fR -seconds. -.TP -.B chap-max-challenge \fIn -Set the maximum number of CHAP challenge transmissions to \fIn\fR -(default 10). -.TP -.B chap-restart \fIn -Set the CHAP restart interval (retransmission timeout for challenges) -to \fIn\fR seconds (default 3). -.TP -.B connect-delay \fIn -Wait for up \fIn\fR milliseconds after the connect script finishes for -a valid PPP packet from the peer. At the end of this time, or when a -valid PPP packet is received from the peer, pppd will commence -negotiation by sending its first LCP packet. The default value is -1000 (1 second). This wait period only applies if the \fBconnect\fR -or \fBpty\fR option is used. -.TP -.B debug -Enables connection debugging facilities. -If this option is given, pppd will log the contents of all -control packets sent or received in a readable form. The packets are -logged through syslog with facility \fIdaemon\fR and level -\fIdebug\fR. This information can be directed to a file by setting up -/etc/syslog.conf appropriately (see syslog.conf(5)). -.TP -.B default-asyncmap -Disable asyncmap negotiation, forcing all control characters to be -escaped for both the transmit and the receive direction. -.TP -.B default-mru -Disable MRU [Maximum Receive Unit] negotiation. With this option, -pppd will use the default MRU value of 1500 bytes for both the -transmit and receive direction. -.TP -.B deflate \fInr,nt -Request that the peer compress packets that it sends, using the -Deflate scheme, with a maximum window size of \fI2**nr\fR bytes, and -agree to compress packets sent to the peer with a maximum window size -of \fI2**nt\fR bytes. If \fInt\fR is not specified, it defaults to -the value given for \fInr\fR. Values in the range 9 to 15 may be used -for \fInr\fR and \fInt\fR; larger values give better compression but -consume more kernel memory for compression dictionaries. -Alternatively, a value of 0 for \fInr\fR or \fInt\fR disables -compression in the corresponding direction. Use \fInodeflate\fR or -\fIdeflate 0\fR to disable Deflate compression entirely. (Note: pppd -requests Deflate compression in preference to BSD-Compress if the peer -can do either.) -.TP -.B 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. Pppd will initially -configure the interface and enable it for IP traffic without -connecting to the peer. When traffic is available, pppd will -connect to the peer and perform negotiation, authentication, etc. -When this is completed, pppd will commence passing data packets -(i.e., IP packets) across the link. - -The \fIdemand\fR option implies the \fIpersist\fR option. If this -behaviour is not desired, use the \fInopersist\fR option after the -\fIdemand\fR option. The \fIidle\fR and \fIholdoff\fR -options are also useful in conjuction with the \fIdemand\fR option. -.TP -.B domain \fId -Append the domain name \fId\fR to the local host name for authentication -purposes. For example, if gethostname() returns the name porsche, but -the fully qualified domain name is porsche.Quotron.COM, you could -specify \fIdomain Quotron.COM\fR. Pppd would then use the name -\fIporsche.Quotron.COM\fR 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. -.TP -.B dryrun -With the \fBdryrun\fR option, pppd will print out all the option -values which have been set and then exit, after parsing the command -line and options files and checking the option values, but before -initiating the link. The option values are logged at level info, and -also printed to standard output unless the device on standard output -is the device that pppd would be using to communicate with the peer. -.TP -.B dump -With the \fBdump\fR option, pppd will print out all the option values -which have been set. This option is like the \fBdryrun\fR option -except that pppd proceeds as normal rather than exiting. -.TP -.B endpoint \fI -Sets the endpoint discriminator sent by the local machine to the peer -during multilink negotiation to \fI\fR. The default is to use -the MAC address of the first ethernet interface on the system, if any, -otherwise the IPv4 address corresponding to the hostname, if any, -provided it is not in the multicast or locally-assigned IP address -ranges, or the localhost address. The endpoint discriminator can be -the string \fBnull\fR or of the form \fItype\fR:\fIvalue\fR, where -type is a decimal number or one of the strings \fBlocal\fR, \fBIP\fR, -\fBMAC\fR, \fBmagic\fR, or \fBphone\fR. The value is an IP address in -dotted-decimal notation for the \fBIP\fR type, or a string of bytes in -hexadecimal, separated by periods or colons for the other types. For -the MAC type, the value may also be the name of an ethernet or similar -network interface. This option is currently only available under -Linux. -.TP -.B hide-password -When logging the contents of PAP packets, this option causes pppd to -exclude the password string from the log. This is the default. -.TP -.B holdoff \fIn -Specifies how many seconds to wait before re-initiating the link after -it terminates. This option only has any effect if the \fIpersist\fR -or \fIdemand\fR option is used. The holdoff period is not applied if -the link was terminated because it was idle. -.TP -.B idle \fIn -Specifies that pppd should disconnect if the link is idle for \fIn\fR -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 \fIpersist\fR option without the \fIdemand\fR option. -If the \fBactive-filter\fR -option is given, data packets which are rejected by the specified -activity filter also count as the link being idle. -.TP -.B ipcp-accept-local -With this option, pppd will accept the peer's idea of our local IP -address, even if the local IP address was specified in an option. -.TP -.B ipcp-accept-remote -With this option, pppd will accept the peer's idea of its (remote) IP -address, even if the remote IP address was specified in an option. -.TP -.B ipcp-max-configure \fIn -Set the maximum number of IPCP configure-request transmissions to -\fIn\fR (default 10). -.TP -.B ipcp-max-failure \fIn -Set the maximum number of IPCP configure-NAKs returned before starting -to send configure-Rejects instead to \fIn\fR (default 10). -.TP -.B ipcp-max-terminate \fIn -Set the maximum number of IPCP terminate-request transmissions to -\fIn\fR (default 3). -.TP -.B ipcp-restart \fIn -Set the IPCP restart interval (retransmission timeout) to \fIn\fR -seconds (default 3). -.TP -.B ipparam \fIstring -Provides an extra parameter to the ip-up and ip-down scripts. If this -option is given, the \fIstring\fR supplied is given as the 6th -parameter to those scripts. -.TP -.B ipv6cp-max-configure \fIn -Set the maximum number of IPv6CP configure-request transmissions to -\fIn\fR (default 10). -.TP -.B ipv6cp-max-failure \fIn -Set the maximum number of IPv6CP configure-NAKs returned before starting -to send configure-Rejects instead to \fIn\fR (default 10). -.TP -.B ipv6cp-max-terminate \fIn -Set the maximum number of IPv6CP terminate-request transmissions to -\fIn\fR (default 3). -.TP -.B ipv6cp-restart \fIn -Set the IPv6CP restart interval (retransmission timeout) to \fIn\fR -seconds (default 3). -.TP -.B ipx -Enable the IPXCP and IPX protocols. This option is presently only -supported under Linux, and only if your kernel has been configured to -include IPX support. -.TP -.B ipx-network \fIn -Set the IPX network number in the IPXCP configure request frame to -\fIn\fR, a hexadecimal number (without a leading 0x). There is no -valid default. If this option is not specified, the network number is -obtained from the peer. If the peer does not have the network number, -the IPX protocol will not be started. -.TP -.B ipx-node \fIn\fB:\fIm -Set the IPX node numbers. The two node numbers are separated from each -other with a colon character. The first number \fIn\fR is the local -node number. The second number \fIm\fR is the peer's node number. Each -node number is a hexadecimal number, at most 10 digits long. The node -numbers on the ipx-network must be unique. There is no valid -default. If this option is not specified then the node numbers are -obtained from the peer. -.TP -.B ipx-router-name \fI -Set the name of the router. This is a string and is sent to the peer -as information data. -.TP -.B ipx-routing \fIn -Set the routing protocol to be received by this option. More than one -instance of \fIipx-routing\fR may be specified. The '\fInone\fR' -option (0) may be specified as the only instance of ipx-routing. The -values may be \fI0\fR for \fINONE\fR, \fI2\fR for \fIRIP/SAP\fR, and -\fI4\fR for \fINLSP\fR. -.TP -.B ipxcp-accept-local -Accept the peer's NAK for the node number specified in the ipx-node -option. If a node number was specified, and non-zero, the default is -to insist that the value be used. If you include this option then you -will permit the peer to override the entry of the node number. -.TP -.B ipxcp-accept-network -Accept the peer's NAK for the network number specified in the -ipx-network option. If a network number was specified, and non-zero, the -default is to insist that the value be used. If you include this -option then you will permit the peer to override the entry of the node -number. -.TP -.B ipxcp-accept-remote -Use the peer's network number specified in the configure request -frame. If a node number was specified for the peer and this option was -not specified, the peer will be forced to use the value which you have -specified. -.TP -.B ipxcp-max-configure \fIn -Set the maximum number of IPXCP configure request frames which the -system will send to \fIn\fR. The default is 10. -.TP -.B ipxcp-max-failure \fIn -Set the maximum number of IPXCP NAK frames which the local system will -send before it rejects the options. The default value is 3. -.TP -.B ipxcp-max-terminate \fIn -Set the maximum nuber of IPXCP terminate request frames before the -local system considers that the peer is not listening to them. The -default value is 3. -.TP -.B kdebug \fIn -Enable debugging code in the kernel-level PPP driver. The argument -values depend on the specific kernel driver, but in general a value of -1 will enable general kernel debug messages. (Note that these -messages are usually only useful for debugging the kernel driver -itself.) For the Linux 2.2.x kernel driver, the value is a sum of -bits: 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 syslog(1) to a file as directed in the -/etc/syslog.conf configuration file. -.TP -.B ktune -Enables pppd to alter kernel settings as appropriate. Under Linux, -pppd will enable IP forwarding (i.e. set /proc/sys/net/ipv4/ip_forward -to 1) if the \fIproxyarp\fR option is used, and will enable the -dynamic IP address option (i.e. set /proc/sys/net/ipv4/ip_dynaddr to -1) in demand mode if the local address changes. -.TP -.B lcp-echo-failure \fIn -If this option is given, pppd will presume the peer to be dead -if \fIn\fR LCP echo-requests are sent without receiving a valid LCP -echo-reply. If this happens, pppd will terminate the -connection. Use of this option requires a non-zero value for the -\fIlcp-echo-interval\fR parameter. This option can be used to enable -pppd 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. -.TP -.B lcp-echo-interval \fIn -If this option is given, pppd will send an LCP echo-request frame to -the peer every \fIn\fR seconds. Normally the peer should respond to -the echo-request by sending an echo-reply. This option can be used -with the \fIlcp-echo-failure\fR option to detect that the peer is no -longer connected. -.TP -.B lcp-max-configure \fIn -Set the maximum number of LCP configure-request transmissions to -\fIn\fR (default 10). -.TP -.B lcp-max-failure \fIn -Set the maximum number of LCP configure-NAKs returned before starting -to send configure-Rejects instead to \fIn\fR (default 10). -.TP -.B lcp-max-terminate \fIn -Set the maximum number of LCP terminate-request transmissions to -\fIn\fR (default 3). -.TP -.B lcp-restart \fIn -Set the LCP restart interval (retransmission timeout) to \fIn\fR -seconds (default 3). -.TP -.B linkname \fIname\fR -Sets the logical name of the link to \fIname\fR. Pppd will create a -file named \fBppp-\fIname\fB.pid\fR in /var/run (or /etc/ppp on some -systems) containing its process ID. This can be useful in determining -which instance of pppd is responsible for the link to a given peer -system. This is a privileged option. -.TP -.B local -Don't use the modem control lines. With this option, pppd 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. -.TP -.B logfd \fIn -Send log messages to file descriptor \fIn\fR. Pppd will send log -messages to at most one file or file descriptor (as well as sending -the log messages to syslog), so this option and the \fBlogfile\fR -option are mutually exclusive. The default is for pppd to send log -messages to stdout (file descriptor 1), unless the serial port is -already open on stdout. -.TP -.B logfile \fIfilename -Append log messages to the file \fIfilename\fR (as well as sending the -log messages to syslog). The file is opened with the privileges of -the user who invoked pppd, in append mode. -.TP -.B 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 /etc/ppp/pap-secrets file as well as the -system password database to be allowed access. -.TP -.B maxconnect \fIn -Terminate the connection when it has been available for network -traffic for \fIn\fR seconds (i.e. \fIn\fR seconds after the first -network control protocol comes up). -.TP -.B maxfail \fIn -Terminate after \fIn\fR consecutive failed connection attempts. A -value of 0 means no limit. The default value is 10. -.TP -.B modem -Use the modem control lines. This option is the default. With this -option, pppd 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 \fIcrtscts\fR option. -.TP -.B mp -Enables the use of PPP multilink; this is an alias for the `multilink' -option. This option is currently only available under Linux. -.TP -.B mpshortseq -Enables the use of short (12-bit) sequence numbers in multilink -headers, as opposed to 24-bit sequence numbers. This option is only -available under Linux, and only has any effect if multilink is -enabled (see the multilink option). -.TP -.B mrru \fIn -Sets the Maximum Reconstructed Receive Unit to \fIn\fR. The MRRU is -the maximum size for a received packet on a multilink bundle, and is -analogous to the MRU for the individual links. This option is -currently only available under Linux, and only has any effect if -multilink is enabled (see the multilink option). -.TP -.B ms-dns \fI -If pppd is acting as a server for Microsoft Windows clients, this -option allows pppd 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 pppd under the name \fBdns-addr\fR.) -.TP -.B ms-wins \fI -If pppd is acting as a server for Microsoft Windows or "Samba" -clients, this option allows pppd 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. -.TP -.B multilink -Enables the use of the PPP multilink protocol. If the peer also -supports multilink, then this link can become part of a bundle between -the local system and the peer. If there is an existing bundle to the -peer, pppd will join this link to that bundle, otherwise pppd will -create a new bundle. See the MULTILINK section below. This option is -currently only available under Linux. -.TP -.B name \fIname -Set the name of the local system for authentication purposes to -\fIname\fR. This is a privileged option. With this option, pppd will -use lines in the secrets files which have \fIname\fR as the second -field when looking for a secret to use in authenticating the peer. In -addition, unless overridden with the \fIuser\fR option, \fIname\fR -will be used as the name to send to the peer when authenticating the -local system to the peer. (Note that pppd does not append the domain -name to \fIname\fR.) -.TP -.B netmask \fIn -Set the interface netmask to \fIn\fR, a 32 bit netmask in "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, pppd -will always use 255.255.255.255 for the netmask, if that is the only -appropriate value for a point-to-point interface.) -.TP -.B noaccomp -Disable Address/Control compression in both directions (send and -receive). -.TP -.B noauth -Do not require the peer to authenticate itself. This option is -privileged. -.TP -.B nobsdcomp -Disables BSD-Compress compression; \fBpppd\fR will not request or -agree to compress packets using the BSD-Compress scheme. -.TP -.B noccp -Disable CCP (Compression Control Protocol) negotiation. This option -should only be required if the peer is buggy and gets confused by -requests from pppd for CCP negotiation. -.TP -.B nocrtscts -Disable hardware flow control (i.e. RTS/CTS) on the serial port. -If neither the \fIcrtscts\fR nor the \fInocrtscts\fR nor the -\fIcdtrcts\fR nor the \fInocdtrcts\fR option is given, the hardware -flow control setting for the serial port is left unchanged. -.TP -.B nocdtrcts -This option is a synonym for \fInocrtscts\fR. Either of these options will -disable both forms of hardware flow control. -.TP -.B nodefaultroute -Disable the \fIdefaultroute\fR option. The system administrator who -wishes to prevent users from creating default routes with pppd -can do so by placing this option in the /etc/ppp/options file. -.TP -.B nodeflate -Disables Deflate compression; pppd will not request or agree to -compress packets using the Deflate scheme. -.TP -.B 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, pppd will fork to become a background process. -.TP -.B noendpoint -Disables pppd from sending an endpoint discriminator to the peer or -accepting one from the peer (see the MULTILINK section below). This -option should only be required if the peer is buggy. -.TP -.B noip -Disable IPCP negotiation and IP communication. This option should -only be required if the peer is buggy and gets confused by requests -from pppd for IPCP negotiation. -.TP -.B noipv6 -Disable IPv6CP negotiation and IPv6 communication. This option should -only be required if the peer is buggy and gets confused by requests -from pppd for IPv6CP negotiation. -.TP -.B 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 specified explicitly on the -command line or in an options file). -.TP -.B noipx -Disable the IPXCP and IPX protocols. This option should only be -required if the peer is buggy and gets confused by requests from pppd -for IPXCP negotiation. -.TP -.B noktune -Opposite of the \fIktune\fR option; disables pppd from changing system -settings. -.TP -.B nolog -Do not send log messages to a file or file descriptor. This option -cancels the \fBlogfd\fR and \fBlogfile\fR options. -.TP -.B nomagic -Disable magic number negotiation. With this option, pppd cannot -detect a looped-back line. This option should only be needed if the -peer is buggy. -.TP -.B nomp -Disables the use of PPP multilink. This option is currently only -available under Linux. -.TP -.B nompshortseq -Disables the use of short (12-bit) sequence numbers in the PPP -multilink protocol, forcing the use of 24-bit sequence numbers. This -option is currently only available under Linux, and only has any -effect if multilink is enabled. -.TP -.B nomultilink -Disables the use of PPP multilink. This option is currently only -available under Linux. -.TP -.B nopcomp -Disable protocol field compression negotiation in both the receive and -the transmit direction. -.TP -.B nopersist -Exit once a connection has been made and terminated. This is the -default unless the \fIpersist\fR or \fIdemand\fR option has been -specified. -.TP -.B nopredictor1 -Do not accept or agree to Predictor-1 compression. -.TP -.B noproxyarp -Disable the \fIproxyarp\fR option. The system administrator who -wishes to prevent users from creating proxy ARP entries with pppd can -do so by placing this option in the /etc/ppp/options file. -.TP -.B notty -Normally, pppd requires a terminal device. With this option, pppd -will allocate itself a pseudo-tty master/slave pair and use the slave -as its terminal device. Pppd will create a child process to act as a -`character shunt' to transfer characters between the pseudo-tty master -and its standard input and output. Thus pppd will transmit characters -on its standard output and receive characters on its standard input -even if they are not terminal devices. This option increases the -latency and CPU overhead of transferring data over the ppp interface -as all of the characters sent and received must flow through the -character shunt process. An explicit device name may not be given if -this option is used. -.TP -.B novj -Disable Van Jacobson style TCP/IP header compression in both the -transmit and the receive direction. -.TP -.B novjccomp -Disable the connection-ID compression option in Van Jacobson style -TCP/IP header compression. With this option, pppd will not omit the -connection-ID byte from Van Jacobson compressed TCP/IP headers, nor -ask the peer to do so. -.TP -.B papcrypt -Indicates that all secrets in the /etc/ppp/pap-secrets file which are -used for checking the identity of the peer are encrypted, and thus -pppd should not accept a password which, before encryption, is -identical to the secret from the /etc/ppp/pap-secrets file. -.TP -.B pap-max-authreq \fIn -Set the maximum number of PAP authenticate-request transmissions to -\fIn\fR (default 10). -.TP -.B pap-restart \fIn -Set the PAP restart interval (retransmission timeout) to \fIn\fR -seconds (default 3). -.TP -.B pap-timeout \fIn -Set the maximum time that pppd will wait for the peer to authenticate -itself with PAP to \fIn\fR seconds (0 means no limit). -.TP -.B pass-filter \fIfilter-expression -Specifies a packet filter to applied 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 daemons (such as -routed) using up link bandwidth, or to provide a basic firewall -capability. -The \fIfilter-expression\fR syntax is as described for tcpdump(1), -except that qualifiers which are inappropriate for a PPP link, such as -\fBether\fR and \fBarp\fR, 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 \fBinbound\fR and \fBoutbound\fR qualifiers. This -option is currently only available under NetBSD, and then only if both -the kernel and pppd were compiled with PPP_FILTER defined. -.TP -.B persist -Do not exit after a connection is terminated; instead try to reopen -the connection. -.TP -.B plugin \fIfilename -Load the shared library object file \fIfilename\fR as a plugin. This -is a privileged option. -.TP -.B 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. -.TP -.B privgroup \fIgroup-name -Allows members of group \fIgroup-name\fR to use privileged options. -This is a privileged option. Use of this option requires care as -there is no guarantee that members of \fIgroup-name\fR cannot use pppd -to become root themselves. Consider it equivalent to putting the -members of \fIgroup-name\fR in the kmem or disk group. -.TP -.B 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. -.TP -.B pty \fIscript -Specifies that the command \fIscript\fR is to be used to communicate -rather than a specific terminal device. Pppd will allocate itself a -pseudo-tty master/slave pair and use the slave as its terminal -device. The \fIscript\fR will be run in a child process with the -pseudo-tty master as its standard input and output. An explicit -device name may not be given if this option is used. (Note: if the -\fIrecord\fR option is used in conjuction with the \fIpty\fR option, -the child process will have pipes on its standard input and output.) -.TP -.B receive-all -With this option, pppd will accept all control characters from the -peer, including those marked in the receive asyncmap. Without this -option, pppd will discard those characters as specified in RFC1662. -This option should only be needed if the peer is buggy. -.TP -.B record \fIfilename -Specifies that pppd should record all characters sent and received to -a file named \fIfilename\fR. This file is opened in append mode, -using the user's user-ID and permissions. This option is implemented -using a pseudo-tty and a process to transfer characters between the -pseudo-tty and the real serial device, so it will increase the latency -and CPU overhead of transferring data over the ppp interface. The -characters are stored in a tagged format with timestamps, which can be -displayed in readable form using the pppdump(8) program. -.TP -.B remotename \fIname -Set the assumed name of the remote system for authentication purposes -to \fIname\fR. -.TP -.B refuse-chap -With this option, pppd will not agree to authenticate itself to the -peer using CHAP. -.TP -.B refuse-pap -With this option, pppd will not agree to authenticate itself to the -peer using PAP. -.TP -.B require-chap -Require the peer to authenticate itself using CHAP [Challenge -Handshake Authentication Protocol] authentication. -.TP -.B require-pap -Require the peer to authenticate itself using PAP [Password -Authentication Protocol] authentication. -.TP -.B show-password -When logging the contents of PAP packets, this option causes pppd to -show the password string in the log message. -.TP -.B silent -With this option, pppd 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 pppd). -.TP -.B sync -Use synchronous HDLC serial encoding instead of asynchronous. -The device used by pppd with this option must have sync support. -Currently supports Microgate SyncLink adapters -under Linux and FreeBSD 2.2.8 and later. -.TP -.B updetach -With this option, pppd will detach from its controlling terminal once -it has successfully established the ppp connection (to the point where -the first network control protocol, usually the IP control protocol, -has come up). -.TP -.B 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 \fIname\fR option). This option is not normally needed since the -\fIname\fR option is privileged. -.TP -.B usepeerdns -Ask the peer for up to 2 DNS server addresses. The addresses supplied -by the peer (if any) are passed to the /etc/ppp/ip-up script in the -environment variables DNS1 and DNS2. In addition, pppd will create an -/etc/ppp/resolv.conf file containing one or two nameserver lines with -the address(es) supplied by the peer. -.TP -.B user \fIname -Sets the name used for authenticating the local system to the peer to -\fIname\fR. -.TP -.B vj-max-slots \fIn -Sets the number of connection slots to be used by the Van Jacobson -TCP/IP header compression and decompression code to \fIn\fR, which -must be between 2 and 16 (inclusive). -.TP -.B welcome \fIscript -Run the executable or shell command specified by \fIscript\fR before -initiating PPP negotiation, after the connect script (if any) has -completed. A value for this option from a privileged source cannot be -overridden by a non-privileged user. -.TP -.B xonxoff -Use software flow control (i.e. XON/XOFF) to control the flow of data on -the serial port. -.SH OPTIONS FILES -Options can be taken from files as well as the command line. Pppd -reads options from the files /etc/ppp/options, ~/.ppprc and -/etc/ppp/options.\fIttyname\fR (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 options.\fIttyname\fR -file is read.) In forming the name of the options.\fIttyname\fR 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 (\\) quotes the following character. -A hash (#) starts a comment, which continues until the end of the -line. There is no restriction on using the \fIfile\fR or \fIcall\fR -options within an options file. -.SH SECURITY -.I pppd -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. This control is provided through restrictions on which IP -addresses the peer may use, based on its authenticated identity (if -any), and through restrictions on which options a non-privileged user -may use. Several of pppd's options are privileged, in particular -those which permit potentially insecure configurations; these options -are only accepted in files which are under the control of the system -administrator, or if pppd is being run by root. -.PP -The default behaviour of pppd is to allow an unauthenticated peer to -use a given IP address only if the system does not already have a -route to that IP address. For example, a system with a -permanent connection to the wider internet will normally have a -default route, and thus all peers will have to authenticate themselves -in order to set up a connection. On such a system, the \fIauth\fR -option is the default. On the other hand, a system where the -PPP link is the only connection to the internet will not normally have -a default route, so the peer will be able to use almost any IP address -without authenticating itself. -.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 pppd, either on the command line, in the -user's ~/.ppprc file, or in an options file read using the \fIfile\fR -option. Privileged options may be used in /etc/ppp/options file or in -an options file read using the \fIcall\fR option. If pppd is being -run by the root user, privileged options can be used without -restriction. -.PP -When opening the device, pppd uses either the invoking user's user ID -or the root UID (that is, 0), depending on whether the device name was -specified by the user or the system administrator. If the device name -comes from a privileged source, that is, /etc/ppp/options or an -options file read using the \fIcall\fR option, pppd uses full root -privileges when opening the device. Thus, by creating an appropriate -file under /etc/ppp/peers, the system administrator can allow users to -establish a ppp connection via a device which they would not normally -have permission to access. Otherwise pppd uses the invoking user's -real UID when opening the device. -.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 "client" and the other the -"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. -.LP -At present, pppd 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. -.LP -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. -.LP -The default behaviour of pppd is to agree to authenticate if -requested, and to not require authentication from the peer. However, -pppd will not agree to authenticate itself with a particular protocol -if it has no secrets which could be used to do so. -.LP -Pppd stores secrets for use in authentication in secrets -files (/etc/ppp/pap-secrets for PAP, /etc/ppp/chap-secrets for CHAP). -Both secrets files have the same format. The secrets files can -contain secrets for pppd to use in authenticating itself to other -systems, as well as secrets for pppd to use when authenticating other -systems to itself. -.LP -Each line in a secrets file contains one secret. A given secret is -specific to a particular combination of client and server - it can -only be used by that client to authenticate itself to that server. -Thus each line in a secrets file has at least 3 fields: the name of -the client, the name of the server, and the secret. These fields may -be followed by a list of the IP addresses that the specified client -may use when connecting to the specified server. -.LP -A secrets file is parsed into words as for a options file, so the -client name, server name and secrets fields must each be one word, -with any embedded spaces or other special characters quoted or -escaped. Note that case is significant in the client and server names -and in the secret. -.LP -If the secret starts with an `@', what follows is assumed to be the -name of a file from which to read the secret. A "*" as the client or -server name matches any name. When selecting a secret, pppd takes the -best match, i.e. the match with the fewest wildcards. -.LP -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 "-", then all IP addresses are -disallowed. To allow any address, use "*". A word starting with "!" -indicates that the specified address is \fInot\fR acceptable. An -address may be followed by "/" and a number \fIn\fR, to indicate a -whole subnet, i.e. all addresses which have the same value in the most -significant \fIn\fR bits. In this form, the address may be followed -by a plus sign ("+") to indicate that one address from the subnet is -authorized, based on the ppp network interface unit number in use. -In this case, the host part of the address will be set to the unit -number plus one. -.LP -Thus a secrets file contains both secrets for use in authenticating -other hosts, plus secrets which we use for authenticating ourselves to -others. When pppd 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 \fIdomain\fR option is used. This default can be -overridden with the \fIname\fR option, except when the -\fIusehostname\fR option is used. -.LP -When pppd 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 -\fIuser\fR 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 pppd looks for a secret with this name in the first -field and the peer's name in the second field. Pppd 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, pppd 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 \fIremotename\fR 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, pppd will use the null -string as the peer's name. -.LP -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 crypt() and -checked against the secret again. Thus secrets for authenticating the -peer can be stored in encrypted form if desired. If the -\fIpapcrypt\fR option is given, the first (unencrypted) comparison is -omitted, for better security. -.LP -Furthermore, if the \fIlogin\fR 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 \fIlogin\fR option, -the secret in /etc/ppp/pap-secrets would be "", which will match any -password supplied by the peer. This avoids the need to have the same -secret in two places. -.LP -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, pppd will -terminated 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. -.LP -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, pppd 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 -.LP -When IPCP negotiation is completed successfully, pppd 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 \fIdefaultroute\fR and/or -\fIproxyarp\fR options are sufficient for this, but in some cases -further intervention is required. The /etc/ppp/ip-up script can be -used for this. -.LP -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 \fIdefaultroute\fR option -causes pppd to create such a default route when IPCP comes up, and -delete it when the link is terminated. -.LP -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 \fIproxyarp\fR option causes -pppd 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, pppd creates a -permanent, published ARP entry with the IP address of the remote host -and the hardware address of the network interface found. -.LP -When the \fIdemand\fR option is used, the interface IP addresses have -already been set at the point when IPCP comes up. If pppd 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), pppd 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 MULTILINK -Multilink PPP provides the capability to combine two or more PPP links -between a pair of machines into a single `bundle', which appears as a -single virtual PPP link which has the combined bandwidth of the -individual links. Currently, multilink PPP is only supported under -Linux. -.LP -Pppd detects that the link it is controlling is connected to the same -peer as another link using the peer's endpoint discriminator and the -authenticated identity of the peer (if it authenticates itself). The -endpoint discriminator is a block of data which is hopefully unique -for each peer. Several types of data can be used, including -locally-assigned strings of bytes, IP addresses, MAC addresses, -randomly strings of bytes, or E-164 phone numbers. The endpoint -discriminator sent to the peer by pppd can be set using the endpoint -option. -.LP -In circumstances the peer may send no endpoint discriminator or a -non-unique value. The optional bundle option adds an extra string -which is added to the peer's endpoint discriminator and authenticated -identity when matching up links to be joined together in a bundle. -The bundle option can also be used to allow the establishment of -multiple bundles between the local system and the peer. Pppd uses a -TDB database in /var/run/pppd.tdb to match up links. -.LP -Assuming that multilink is enabled and the peer is willing to -negotiate multilink, then when pppd is invoked to bring up the first -link to the peer, it will detect that no other link is connected to -the peer and create a new bundle, that is, another ppp network -interface unit. When another pppd is invoked to bring up another link -to the peer, it will detect the existing bundle and join its link to -it. Currently, if the first pppd terminates (for example, because of -a hangup or a received signal) the bundle is destroyed. -.SH EXAMPLES -.LP -The following examples assume that the /etc/ppp/options file contains -the \fIauth\fR option (as in the default /etc/ppp/options file in the -ppp distribution). -.LP -Probably the most common use of pppd is to dial out to an ISP. This -can be done with a command such as -.IP -pppd call isp -.LP -where the /etc/ppp/peers/isp file is set up by the system -administrator to contain something like this: -.IP -ttyS0 19200 crtscts -.br -connect '/usr/sbin/chat -v -f /etc/ppp/chat-isp' -.br -noauth -.LP -In this example, we are using chat to dial the ISP's modem and go -through any logon sequence required. The /etc/ppp/chat-isp file -contains the script used by chat; it could for example contain -something like this: -.IP -ABORT "NO CARRIER" -.br -ABORT "NO DIALTONE" -.br -ABORT "ERROR" -.br -ABORT "NO ANSWER" -.br -ABORT "BUSY" -.br -ABORT "Username/Password Incorrect" -.br -"" "at" -.br -OK "at&d0&c1" -.br -OK "atdt2468135" -.br -"name:" "^Umyuserid" -.br -"word:" "\\qmypassword" -.br -"ispts" "\\q^Uppp" -.br -"~-^Uppp-~" -.LP -See the chat(8) man page for details of chat scripts. -.LP -Pppd 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 pppd -(installed setuid-root) with a command such as -.IP -pppd proxyarp -.LP -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 -/etc/ppp/pap-secrets or /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 "joespc" which is to be allowed to dial in to the machine -called "server" and use the IP address joespc.my.net, you would add an -entry like this to /etc/ppp/pap-secrets or /etc/ppp/chap-secrets: -.IP -joespc server "joe's secret" joespc.my.net -.LP -Alternatively, you can create a username called (for example) "ppp", -whose login shell is pppd and whose home directory is /etc/ppp. -Options to be used when pppd is run this way can be put in -/etc/ppp/.ppprc. -.LP -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 \fIasyncmap a0000\fR. If the path includes a telnet, -you probably should escape ^] as well (\fIasyncmap 200a0000\fR). If -the path includes an rlogin, you will need to use the \fIescape ff\fR -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 -.LP -Messages are sent to the syslog daemon using facility LOG_DAEMON. -(This can be overriden by recompiling pppd with the macro -LOG_PPP defined as the desired facility.) In order to see the error -and debug messages, you will need to edit your /etc/syslog.conf file -to direct the messages to the desired output device or file. -.LP -The \fIdebug\fR 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 \fIdebug\fR option also -causes other debugging messages to be logged. -.LP -Debugging can also be enabled or disabled by sending a SIGUSR1 signal -to the pppd process. This signal acts as a toggle. -.SH EXIT STATUS -The exit status of pppd is set to indicate whether any error was -detected, or the reason for the link being terminated. The values -used are: -.TP -.B 0 -Pppd has detached, or otherwise the connection was successfully -established and terminated at the peer's request. -.TP -.B 1 -An immediately fatal error of some kind occurred, such as an essential -system call failing, or running out of virtual memory. -.TP -.B 2 -An error was detected in processing the options given, such as two -mutually exclusive options being used. -.TP -.B 3 -Pppd is not setuid-root and the invoking user is not root. -.TP -.B 4 -The kernel does not support PPP, for example, the PPP kernel driver is -not included or cannot be loaded. -.TP -.B 5 -Pppd terminated because it was sent a SIGINT, SIGTERM or SIGHUP -signal. -.TP -.B 6 -The serial port could not be locked. -.TP -.B 7 -The serial port could not be opened. -.TP -.B 8 -The connect script failed (returned a non-zero exit status). -.TP -.B 9 -The command specified as the argument to the \fIpty\fR option could -not be run. -.TP -.B 10 -The PPP negotiation failed, that is, it didn't reach the point where -at least one network protocol (e.g. IP) was running. -.TP -.B 11 -The peer system failed (or refused) to authenticate itself. -.TP -.B 12 -The link was established successfully and terminated because it was -idle. -.TP -.B 13 -The link was established successfully and terminated because the -connect time limit was reached. -.TP -.B 14 -Callback was negotiated and an incoming call should arrive shortly. -.TP -.B 15 -The link was terminated because the peer is not responding to echo -requests. -.TP -.B 16 -The link was terminated by the modem hanging up. -.TP -.B 17 -The PPP negotiation failed because serial loopback was detected. -.TP -.B 18 -The init script failed (returned a non-zero exit status). -.TP -.B 19 -We failed to authenticate ourselves to the peer. -.SH SCRIPTS -Pppd 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. -Pppd 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. Pppd runs the scripts with -standard input, output and error redirected to /dev/null, and with an -environment that is empty except for some environment variables that -give information about the link. The environment variables that pppd -sets are: -.TP -.B DEVICE -The name of the serial tty device being used. -.TP -.B IFNAME -The name of the network interface being used. -.TP -.B IPLOCAL -The IP address for the local end of the link. This is only set when -IPCP has come up. -.TP -.B IPREMOTE -The IP address for the remote end of the link. This is only set when -IPCP has come up. -.TP -.B PEERNAME -The authenticated name of the peer. This is only set if the peer -authenticates itself. -.TP -.B SPEED -The baud rate of the tty device. -.TP -.B ORIG_UID -The real user-id of the user who invoked pppd. -.TP -.B PPPLOGNAME -The username of the real user-id that invoked pppd. This is always set. -.P -For the ip-down and auth-down scripts, pppd also sets the following -variables giving statistics for the connection: -.TP -.B CONNECT_TIME -The number of seconds from when the PPP negotiation started until the -connection was terminated. -.TP -.B BYTES_SENT -The number of bytes sent (at the level of the serial port) during the -connection. -.TP -.B BYTES_RCVD -The number of bytes received (at the level of the serial port) during -the connection. -.TP -.B LINKNAME -The logical name of the link, set with the \fIlinkname\fR option. -.P -Pppd invokes the following scripts, if they exist. It is not an error -if they don't exist. -.TP -.B /etc/ppp/auth-up -A program or script which is executed after the remote system -successfully authenticates itself. It is executed with the parameters -.IP -\fIinterface-name peer-name user-name tty-device speed\fR -.IP -Note that this script is not executed if the peer doesn't authenticate -itself, for example when the \fInoauth\fR option is used. -.TP -.B /etc/ppp/auth-down -A program or script which is executed when the link goes down, if -/etc/ppp/auth-up was previously executed. It is executed in the same -manner with the same parameters as /etc/ppp/auth-up. -.TP -.B /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 -.IP -\fIinterface-name tty-device speed local-IP-address -remote-IP-address ipparam\fR -.TP -.B /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 /etc/ppp/ip-up script. It is -invoked in the same manner and with the same parameters as the ip-up -script. -.TP -.B /etc/ppp/ipv6-up -Like /etc/ppp/ip-up, except that it is executed when the link is available -for sending and receiving IPv6 packets. It is executed with the parameters -.IP -\fIinterface-name tty-device speed local-link-local-address -remote-link-local-address ipparam\fR -.TP -.B /etc/ppp/ipv6-down -Similar to /etc/ppp/ip-down, but it is executed when IPv6 packets can no -longer be transmitted on the link. It is executed with the same parameters -as the ipv6-up script. -.TP -.B /etc/ppp/ipx-up -A program or script which is executed when the link is available for -sending and receiving IPX packets (that is, IPXCP has come up). It is -executed with the parameters -.IP -\fIinterface-name tty-device speed network-number local-IPX-node-address -remote-IPX-node-address local-IPX-routing-protocol remote-IPX-routing-protocol -local-IPX-router-name remote-IPX-router-name ipparam pppd-pid\fR -.IP -The local-IPX-routing-protocol and remote-IPX-routing-protocol field -may be one of the following: -.IP -NONE to indicate that there is no routing protocol -.br -RIP to indicate that RIP/SAP should be used -.br -NLSP to indicate that Novell NLSP should be used -.br -RIP NLSP to indicate that both RIP/SAP and NLSP should be used -.TP -.B /etc/ppp/ipx-down -A program or script which is executed when the link is no longer -available for sending and receiving IPX packets. This script can be -used for undoing the effects of the /etc/ppp/ipx-up script. It is -invoked in the same manner and with the same parameters as the ipx-up -script. -.SH FILES -.TP -.B /var/run/ppp\fIn\fB.pid \fR(BSD or Linux), \fB/etc/ppp/ppp\fIn\fB.pid \fR(others) -Process-ID for pppd process on ppp interface unit \fIn\fR. -.TP -.B /var/run/ppp-\fIname\fB.pid \fR(BSD or Linux), \fB/etc/ppp/ppp-\fIname\fB.pid \fR(others) -Process-ID for pppd process for logical link \fIname\fR (see the -\fIlinkname\fR option). -.TP -.B /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. Pppd will log a warning if this is not the case. -.TP -.B /etc/ppp/chap-secrets -Names, secrets and IP addresses for CHAP authentication. As for -/etc/ppp/pap-secrets, this file should be owned by root and not -readable or writable by any other user. Pppd will log a warning if -this is not the case. -.TP -.B /etc/ppp/options -System default options for pppd, read before user default options or -command-line options. -.TP -.B ~/.ppprc -User default options, read before /etc/ppp/options.\fIttyname\fR. -.TP -.B /etc/ppp/options.\fIttyname -System default options for the serial port being used, read after -~/.ppprc. In forming the \fIttyname\fR 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. -.TP -.B /etc/ppp/peers -A directory containing options files which may contain privileged -options, even if pppd 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. -.SH SEE ALSO -.TP -.B RFC1144 -Jacobson, V. -\fICompressing TCP/IP headers for low-speed serial links.\fR -February 1990. -.TP -.B RFC1321 -Rivest, R. -.I The MD5 Message-Digest Algorithm. -April 1992. -.TP -.B RFC1332 -McGregor, G. -.I PPP Internet Protocol Control Protocol (IPCP). -May 1992. -.TP -.B RFC1334 -Lloyd, B.; Simpson, W.A. -.I PPP authentication protocols. -October 1992. -.TP -.B RFC1661 -Simpson, W.A. -.I The Point\-to\-Point Protocol (PPP). -July 1994. -.TP -.B RFC1662 -Simpson, W.A. -.I PPP in HDLC-like Framing. -July 1994. -.TP -.B RFC2472 -Haskin, D. -.I IP Version 6 over PPP -December 1998. -.SH NOTES -The following signals have the specified effect when sent to pppd. -.TP -.B SIGINT, SIGTERM -These signals cause pppd to terminate the link (by closing LCP), -restore the serial device settings, and exit. -.TP -.B SIGHUP -This signal causes pppd to terminate the link, restore the serial -device settings, and close the serial device. If the \fIpersist\fR or -\fIdemand\fR option has been specified, pppd will try to reopen the -serial device and start another connection (after the holdoff period). -Otherwise pppd will exit. If this signal is received during the -holdoff period, it causes pppd to end the holdoff period immediately. -.TP -.B SIGUSR1 -This signal toggles the state of the \fIdebug\fR option. -.TP -.B SIGUSR2 -This signal causes pppd 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.) - -.SH AUTHORS -Paul Mackerras (Paul.Mackerras@cs.anu.edu.au), based on earlier work by -Drew Perkins, -Brad Clements, -Karl Fox, -Greg Christy, -and -Brad Parker. -- cgit v1.2.1