privileges when opening the device.  Thus, by creating an appropriatefile under /etc/ppp/peers, the system administrator can allow users toestablish a ppp connection via a device which they would not normallyhave permission to access.  Otherwise pppd uses the invoking user'sreal UID when opening the device..SH AUTHENTICATIONAuthentication is the process whereby one peer convinces the other ofits identity.  This involves the first peer sending its name to theother, together with some kind of secret information which could onlycome from the genuine authorized user of that name.  In such anexchange, we will call the first peer the "client" and the other the"server".  The client has a name by which it identifies itself to theserver, and the server also has a name by which it identifies itselfto the client.  Generally the genuine client shares some secret (orpassword) with the server, and authenticates itself by proving that itknows that secret.  Very often, the names used for authenticationcorrespond to the internet hostnames of the peers, but this is notessential..LPAt present, pppd supports two authentication protocols: the PasswordAuthentication Protocol (PAP) and the Challenge HandshakeAuthentication Protocol (CHAP).  PAP involves the client sending itsname and a cleartext password to the server to authenticate itself.In contrast, the server initiates the CHAP authentication exchange bysending a challenge to the client (the challenge packet includes theserver's name).  The client must respond with a response whichincludes its name plus a hash value derived from the shared secret andthe challenge, in order to prove that it knows the secret..LPThe PPP protocol, being symmetrical, allows both peers to require theother to authenticate itself.  In that case, two separate andindependent authentication exchanges will occur.  The two exchangescould use different authentication protocols, and in principle,different names could be used in the two exchanges..LPThe default behaviour of pppd is to agree to authenticate ifrequested, and to not require authentication from the peer.  However,pppd will not agree to authenticate itself with a particular protocolif it has no secrets which could be used to do so..LPPppd stores secrets for use in authentication in secretsfiles (/etc/ppp/pap-secrets for PAP, /etc/ppp/chap-secrets for CHAP).Both secrets files have the same format.  The secrets files cancontain secrets for pppd to use in authenticating itself to othersystems, as well as secrets for pppd to use when authenticating othersystems to itself..LPEach line in a secrets file contains one secret.  A given secret isspecific to a particular combination of client and server - it canonly 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 ofthe client, the name of the server, and the secret.  These fields maybe followed by a list of the IP addresses that the specified clientmay use when connecting to the specified server..LPA secrets file is parsed into words as for a options file, so theclient name, server name and secrets fields must each be one word,with any embedded spaces or other special characters quoted orescaped.  Note that case is significant in the client and server namesand in the secret..LPIf the secret starts with an `@', what follows is assumed to be thename of a file from which to read the secret.  A "*" as the client orserver name matches any name.  When selecting a secret, pppd takes thebest match, i.e.  the match with the fewest wildcards..LPAny following words on the same line are taken to be a list ofacceptable IP addresses for that client.  If there are only 3 words onthe line, or if the first word is "-", then all IP addresses aredisallowed.  To allow any address, use "*".  A word starting with "!"indicates that the specified address is \fInot\fR acceptable.  Anaddress may be followed by "/" and a number \fIn\fR, to indicate awhole subnet, i.e. all addresses which have the same value in the mostsignificant \fIn\fR bits.  In this form, the address may be followedby a plus sign ("+") to indicate that one address from the subnet isauthorized, based on the ppp network interface unit number in use.In this case, the host part of the address will be set to the unitnumber plus one..LPThus a secrets file contains both secrets for use in authenticatingother hosts, plus secrets which we use for authenticating ourselves toothers.  When pppd is authenticating the peer (checking the peer'sidentity), it chooses a secret with the peer's name in the firstfield and the name of the local system in the second field.  Thename of the local system defaults to the hostname, with the domainname appended if the \fIdomain\fR option is used.  This default can beoverridden with the \fIname\fR option, except when the\fIusehostname\fR option is used..LPWhen pppd is choosing a secret to use in authenticating itself to thepeer, it first determines what name it is going to use to identifyitself 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 tothe name of the local system, determined as described in the previousparagraph.  Then pppd looks for a secret with this name in the firstfield and the peer's name in the second field.  Pppd will know thename of the peer if CHAP authentication is being used, because thepeer will have sent it in the challenge packet.  However, if PAP is beingused, pppd will have to determine the peer's name from the optionsspecified by the user.  The user can specify the peer's name directlywith the \fIremotename\fR option.  Otherwise, if the remote IP addresswas specified by a name (rather than in numeric form), that name willbe used as the peer's name.  Failing that, pppd will use the nullstring as the peer's name..LPWhen authenticating the peer with PAP, the supplied password is firstcompared with the secret from the secrets file.  If the passworddoesn't match the secret, the password is encrypted using crypt() andchecked against the secret again.  Thus secrets for authenticating thepeer can be stored in encrypted form if desired.  If the\fIpapcrypt\fR option is given, the first (unencrypted) comparison isomitted, for better security..LPFurthermore, if the \fIlogin\fR option was specified, the username andpassword are also checked against the system password database.  Thus,the system administrator can set up the pap-secrets file to allow PPPaccess only to certain users, and to restrict the set of IP addressesthat each user can use.  Typically, when using the \fIlogin\fR option,the secret in /etc/ppp/pap-secrets would be "", which will match anypassword supplied by the peer.  This avoids the need to have the samesecret in two places..LPAuthentication must be satisfactorily completed before IPCP (or anyother Network Control Protocol) can be started.  If the peer isrequired to authenticate itself, and fails to do so, pppd willterminated the link (by closing LCP).  If IPCP negotiates anunacceptable IP address for the remote host, IPCP will be closed.  IPpackets can only be sent or received when IPCP is open..LPIn some cases it is desirable to allow some hosts which can'tauthenticate themselves to connect and use one of a restricted set ofIP addresses, even when the local host generally requiresauthentication.  If the peer refuses to authenticate itself whenrequested, pppd takes that as equivalent to authenticating with PAPusing the empty string for the username and password.  Thus, by addinga line to the pap-secrets file which specifies the empty string forthe client and password, it is possible to allow restricted access tohosts which refuse to authenticate themselves..SH ROUTING.LPWhen IPCP negotiation is completed successfully, pppd will inform thekernel of the local and remote IP addresses for the ppp interface.This is sufficient to create a host route to the remote end of thelink, which will enable the peers to exchange IP packets.Communication with other machines generally requires furthermodification to routing tables and/or ARP (Address ResolutionProtocol) tables.  In most cases the \fIdefaultroute\fR and/or\fIproxyarp\fR options are sufficient for this, but in some casesfurther intervention is required.  The /etc/ppp/ip-up script can beused for this..LPSometimes it is desirable to add a default route through the remotehost, as in the case of a machine whose only connection to theInternet is through the ppp interface.  The \fIdefaultroute\fR optioncauses pppd to create such a default route when IPCP comes up, anddelete it when the link is terminated..LPIn some cases it is desirable to use proxy ARP, for example on aserver machine connected to a LAN, in order to allow other hosts tocommunicate with the remote host.  The \fIproxyarp\fR option causespppd to look for a network interface on the same subnet as the remotehost (an interface supporting broadcast and ARP, which is up and not apoint-to-point or loopback interface).  If found, pppd creates apermanent, published ARP entry with the IP address of the remote hostand the hardware address of the network interface found..LPWhen the \fIdemand\fR option is used, the interface IP addresses havealready been set at the point when IPCP comes up.  If pppd has notbeen able to negotiate the same addresses that it used to configurethe interface (for example when the peer is an ISP that uses dynamicIP address assignment), pppd has to change the interface IP addressesto the negotiated addresses.  This may disrupt existing connections,and the use of demand dialling with peers that do dynamic IP addressassignment is not recommended..SH EXAMPLES.LPThe following examples assume that the /etc/ppp/options file containsthe \fIauth\fR option (as in the default /etc/ppp/options file in theppp distribution)..LPProbably the most common use of pppd is to dial out to an ISP.  Thiscan be done with a command such as.IPpppd call isp.LPwhere the /etc/ppp/peers/isp file is set up by the systemadministrator to contain something like this:.IPttyS0 19200 crtscts.brconnect '/usr/sbin/chat -v -f /etc/ppp/chat-isp'.brnoauth.LPIn this example, we are using chat to dial the ISP's modem and gothrough any logon sequence required.  The /etc/ppp/chat-isp filecontains the script used by chat; it could for example containsomething like this:.IPABORT "NO CARRIER".brABORT "NO DIALTONE".brABORT "ERROR".brABORT "NO ANSWER".brABORT "BUSY".brABORT "Username/Password Incorrect".br"" "at".brOK "at&d0&c1".brOK "atdt2468135".br"name:" "^Umyuserid".br"word:" "\\qmypassword".br"ispts" "\\q^Uppp".br"~-^Uppp-~".LPSee the chat(8) man page for details of chat scripts..LPPppd can also be used to provide a dial-in ppp service for users.  Ifthe users already have login accounts, the simplest way to set up theppp service is to let the users log in to their accounts and run pppd(installed setuid-root) with a command such as.IPpppd proxyarp.LPTo allow a user to use the PPP facilities, you need to allocate an IPaddress for that user's machine and create an entry in/etc/ppp/pap-secrets or /etc/ppp/chap-secrets (depending on whichauthentication method the PPP implementation on the user's machinesupports), so that the user'smachine can authenticate itself.  For example, if Joe has a machinecalled "joespc" which is to be allowed to dial in to the machinecalled "server" and use the IP address joespc.my.net, you would add anentry like this to /etc/ppp/pap-secrets or /etc/ppp/chap-secrets:.IPjoespc	server	"joe's secret"	joespc.my.net.LPAlternatively, 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..LPIf your serial connection is any more complicated than a piece ofwire, you may need to arrange for some control characters to beescaped.  In particular, it is often useful to escape XON (^Q) andXOFF (^S), using \fIasyncmap a0000\fR.  If the path includes a telnet,you probably should escape ^] as well (\fIasyncmap 200a0000\fR).  Ifthe path includes an rlogin, you will need to use the \fIescape ff\fRoption on the end which is running the rlogin client, since manyrlogin implementations are not transparent; they will remove thesequence [0xff, 0xff, 0x73, 0x73, followed by any 8 bytes] from thestream..SH DIAGNOSTICS.LPMessages are sent to the syslog daemon using facility LOG_DAEMON.(This can be overriden by recompiling pppd with the macroLOG_PPP defined as the desired facility.)  In order to see the errorand debug messages, you will need to edit your /etc/syslog.conf fileto direct the messages to the desired output device or file..LPThe \fIdebug\fR option causes the contents of all control packets sentor 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 ifauthentication fails.If debugging is enabled at compile time, the \fIdebug\fR option alsocauses other debugging messages to be logged..LPDebugging can also be enabled or disabled by sending a SIGUSR1 signalto the pppd process.  This signal acts as a toggle..SH EXIT STATUSThe exit status of pppd is set to indicate whether any error wasdetected, or the reason for the link being terminated.  The valuesused are:.TP.B 0Pppd has detached, or otherwise the connection was successfullyestablished and terminated at the peer's request..TP.B 1An immediately fatal error of some kind occurred, such as an essentialsystem call failing, or running out of virtual memory..TP.B 2An error was detected in processing the options given, such as twomutually exclusive options being used..TP.B 3Pppd is not setuid-root and the invoking user is not root.