.\" manual page [] for pppd 2.4.\" $Id: pppd.8,v 1.57 2001/03/12 22:49:25 paulus Exp $.\" SH section heading.\" SS subsection heading.\" LP paragraph.\" IP indented paragraph.\" TP hanging label.TH PPPD 8.SH NAMEpppd \- Point to Point Protocol daemon.SH SYNOPSIS.B pppd[.I tty_name] [.I speed] [.I options].SH DESCRIPTION.LPThe Point-to-Point Protocol (PPP) provides a method for transmittingdatagrams over serial point-to-point links.  PPPis composed of three parts: a method for encapsulating datagrams overserial links, an extensible Link Control Protocol (LCP), anda family of Network Control Protocols (NCP) for establishingand configuring different network-layer protocols..LPThe encapsulation scheme is provided by driver code in the kernel.Pppd provides the basic LCP, authentication support, and an NCP forestablishing and configuring the Internet Protocol (IP) (called the IPControl Protocol, IPCP)..SH FREQUENTLY USED OPTIONS.TP.I <tty_name>Communicate over the named device.  The string "/dev/" is prepended ifnecessary.  If no device name is given, or if the name of the terminalconnected to the standard input is given, pppd will use that terminal,and will not fork to put itself in the background.  A value for thisoption from a privileged source cannot be overridden by anon-privileged user..TP.I <speed>Set the baud rate to <speed> (a decimal number).  On systems such as4.4BSD and NetBSD, any speed can be specified.  Other systems(e.g. SunOS) allow only a limited set of speeds..TP.B asyncmap \fI<map>Set the async character map to <map>.  This map describes whichcontrol characters cannot be successfully received over the serialline.  Pppd will ask the peer to send these characters as a 2-byteescape sequence.  The argument is a 32 bit hex number with each bitrepresenting a character to escape.  Bit 0 (00000001) represents thecharacter 0x00; bit 31 (80000000) represents the character 0x1f or ^_.If multiple \fIasyncmap\fR options are given, the values are ORedtogether.  If no \fIasyncmap\fR option is given, no async charactermap will be negotiated for the receive direction; the peer should thenescape \fIall\fR control characters.  To escape transmittedcharacters, use the \fIescape\fR option..TP.B authRequire the peer to authenticate itself before allowing networkpackets to be sent or received.  This option is the default if thesystem has a default route.  If neither this option nor the\fInoauth\fR option is specified, pppd will only allow the peer to useIP addresses to which the system does not already have a route..TP.B call \fInameRead options from the file /etc/ppp/peers/\fIname\fR.  This file maycontain privileged options, such as \fInoauth\fR, even if pppdis not being run by root.  The \fIname\fR string may not begin with /or include .. as a pathname component.  The format of the options fileis described below..TP.B connect \fIscriptUse the executable or shell command specified by \fIscript\fR to setup the serial line.  This script would typically use the chat(8)program to dial the modem and start the remote ppp session.  A valuefor this option from a privileged source cannot be overridden by anon-privileged user..TP.B crtsctsUse hardware flow control (i.e. RTS/CTS) to control the flow ofdata on the serial port.  If neither the \fIcrtscts\fR, the\fInocrtscts\fR, the \fIcdtrcts\fR nor the \fInocdtrcts\fR optionis given, the hardware flow control setting for the serial port isleft unchanged.Some serial ports (such as Macintosh serial ports) lack a trueRTS output. Such serial ports use this mode to implementunidirectional flow control. The serial port willsuspend transmission when requested by the modem (via CTS)but will be unable to request the modem stop sending to thecomputer. This mode retains the ability to use DTR asa modem control line..TP.B defaultrouteAdd a default route to the system routing tables, using the peer asthe gateway, when IPCP negotiation is successfully completed.This entry is removed when the PPP connection is broken.  This optionis privileged if the \fInodefaultroute\fR option has been specified..TP.B disconnect \fIscriptRun the executable or shell command specified by \fIscript\fR afterpppd has terminated the link.  This script could, for example, issuecommands to the modem to cause it to hang up if hardware modem controlsignals were not available.  The disconnect script is not run if themodem has already hung up.  A value for this option from a privilegedsource 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 itsasync control character map).  The characters to be escaped arespecified as a list of hex numbers separated by commas.  Note thatalmost any character can be specified for the \fIescape\fR option,unlike the \fIasyncmap\fR option which only allows control charactersto be specified.  The characters which may not be escaped are thosewith hex values 0x20 - 0x3f or 0x5e..TP.B file \fInameRead 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 \fIscriptRun the executable or shell command specified by \fIscript\fR toinitialize the serial line.  This script would typically use thechat(8) program to configure the modem to enable auto answer.  A valuefor this option from a privileged source cannot be overridden by anon-privileged user..TP.B lockSpecifies that pppd should create a UUCP-style lock file for theserial device to ensure exclusive access to the device..TP.B mru \fInSet the MRU [Maximum Receive Unit] value to \fIn\fR. Pppdwill ask the peer to send packets of no more than \fIn\fR bytes.  Theminimum MRU value is 128.  The default MRU value is 1500.  A value of296 is recommended for slow links (40 bytes for TCP/IP header + 256bytes of data).  (Note that for IPv6 MRU must be at least 1280).TP.B mtu \fInSet the MTU [Maximum Transmit Unit] value to \fIn\fR.  Unless thepeer requests a smaller value via MRU negotiation, pppd willrequest that the kernel networking code send data packets of no morethan \fIn\fR bytes through the PPP network interface.  (Note that for IPv6 MTU must be at least 1280).TP.B passiveEnables the "passive" option in the LCP.  With this option, pppd willattempt to initiate a connection; if no reply is received from thepeer, pppd will then just wait passively for a valid LCP packet fromthe peer, instead of exiting, as it would without this option..SH OPTIONS.TP.I <local_IP_address>\fB:\fI<remote_IP_address>Set the local and/or remote interface IP addresses.  Either one may beomitted.  The IP addresses can be specified with a host name or indecimal dot notation (e.g. 150.234.56.78).  The default localaddress is the (first) IP address of the system (unless the\fInoipdefault\fRoption is given).  The remote address will be obtained from the peerif not specified in any option.  Thus, in simple cases, this option isnot required.  If a local and/or remote IP address is specified withthis option, pppdwill not accept a different value from the peer in the IPCPnegotiation, unless the \fIipcp-accept-local\fR and/or\fIipcp-accept-remote\fR options are given, respectively..TP.B ipv6 \fI<local_interface_identifier>\fR,\fI<remote_interface_identifier>Set the local and/or remote 64-bit interface identifier. Either one may beomitted. The identifier must be specified in standard ascii notation ofIPv6 addresses (e.g. ::dead:beef). If the\fIipv6cp-use-ipaddr\fRoption is given, the local identifier is the local IPv4 address (see above).On systems which supports a unique persistent id, such as EUI-48 derivedfrom the Ethernet MAC address, \fIipv6cp-use-persistent\fR option can beused to replace the \fIipv6 <local>,<remote>\fR option. Otherwise the identifier is randomized..TP.B active-filter \fIfilter-expressionSpecifies a packet filter to be applied to data packets to determinewhich packets are to be regarded as link activity, and therefore resetthe idle timer, or cause the link to be brought up in demand-diallingmode.  This option is useful in conjunction with the\fBidle\fR option if there are packets being sent or receivedregularly 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 filterexpression should be enclosed in single-quotes to prevent whitespacein the expression from being interpreted by the shell. This optionis currently only available under NetBSD, and then onlyif 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 withoutauthenticating themselves.  The parameter is parsed as for eachelement of the list of allowed IP addresses in the secrets files (seethe AUTHENTICATION section below)..TP.B bsdcomp \fInr,ntRequest that the peer compress packets that it sends, using theBSD-Compress scheme, with a maximum code size of \fInr\fR bits, andagree 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 valuegiven for \fInr\fR.  Values in the range 9 to 15 may be used for\fInr\fR and \fInt\fR; larger values give better compression butconsume more kernel memory for compression dictionaries.Alternatively, a value of 0 for \fInr\fR or \fInt\fR disablescompression in the corresponding direction.  Use \fInobsdcomp\fR or\fIbsdcomp 0\fR to disable BSD-Compress compression entirely..TP.B cdtrctsUse a non-standard hardware flow control (i.e. DTR/CTS) to controlthe flow of data on the serial port.  If neither the \fIcrtscts\fR,the \fInocrtscts\fR, the \fIcdtrcts\fR nor the \fInocdtrcts\fRoption is given, the hardware flow control setting for the serialport is left unchanged.Some serial ports (such as Macintosh serial ports) lack a trueRTS output. Such serial ports use this mode to implement truebi-directional flow control. The sacrifice is that this flowcontrol mode does not permit using DTR as a modem control line..TP.B chap-interval \fInIf this option is given, pppd will rechallenge the peer every \fIn\fRseconds..TP.B chap-max-challenge \fInSet the maximum number of CHAP challenge transmissions to \fIn\fR(default 10)..TP.B chap-restart \fInSet the CHAP restart interval (retransmission timeout for challenges)to \fIn\fR seconds (default 3)..TP.B connect-delay \fInWait for up \fIn\fR milliseconds after the connect script finishes fora valid PPP packet from the peer.  At the end of this time, or when avalid PPP packet is received from the peer, pppd will commencenegotiation by sending its first LCP packet.  The default value is1000 (1 second).  This wait period only applies if the \fBconnect\fRor \fBpty\fR option is used..TP.B debugEnables connection debugging facilities.If this option is given, pppd will log the contents of allcontrol packets sent or received in a readable form.  The packets arelogged 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-asyncmapDisable asyncmap negotiation, forcing all control characters to beescaped for both the transmit and the receive direction..TP.B default-mruDisable MRU [Maximum Receive Unit] negotiation.  With this option,pppd will use the default MRU value of 1500 bytes for both thetransmit and receive direction..TP.B deflate \fInr,ntRequest that the peer compress packets that it sends, using theDeflate scheme, with a maximum window size of \fI2**nr\fR bytes, andagree to compress packets sent to the peer with a maximum window sizeof \fI2**nt\fR bytes.  If \fInt\fR is not specified, it defaults tothe value given for \fInr\fR.  Values in the range 9 to 15 may be usedfor \fInr\fR and \fInt\fR; larger values give better compression butconsume more kernel memory for compression dictionaries.Alternatively, a value of 0 for \fInr\fR or \fInt\fR disablescompression in the corresponding direction.  Use \fInodeflate\fR or\fIdeflate 0\fR to disable Deflate compression entirely.  (Note: pppdrequests Deflate compression in preference to BSD-Compress if the peercan do either.).TP.B demandInitiate the link only on demand, i.e. when data traffic is present.With this option, the remote IP address must be specified by the useron the command line or in an options file.  Pppd will initiallyconfigure the interface and enable it for IP traffic withoutconnecting to the peer.  When traffic is available, pppd willconnect 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 thisbehaviour is not desired, use the \fInopersist\fR option after the\fIdemand\fR option.  The \fIidle\fR and \fIholdoff\fRoptions are also useful in conjuction with the \fIdemand\fR option..TP.B domain \fIdAppend the domain name \fId\fR to the local host name for authenticationpurposes.  For example, if gethostname() returns the name porsche, butthe fully qualified domain name is porsche.Quotron.COM, you couldspecify \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 itselfto the peer.  This option is privileged..TP