SYNOPSIS
     *PPPConnect [<driver>] [speed] [options]

DESCRIPTION
     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 Pro-
     tocol (LCP), and a family of Network Control Protocols (NCP)
     for establishing and configuring different network-layer
     protocols.

     The encapsulation scheme is provided by driver code in the
     kernel.  pppd provides the basic LCP, authentication sup-
     port, and an NCP for establishing and configuring the Inter-
     net Protocol (IP) (called the IP Control Protocol, IPCP).

FREQUENTLY USED OPTIONS
     <driver>
          If the blockdriver version of PPP is being used then
          this option takes the form <driver>[:<port>].
          Load the named blockdriver from SerialDev:Modules, and
          use the given port for communication. If this is not
          specified, the previously used driver will be used.
          The PPP module contains the Internal driver, which
          will be used if this option is never specified.

	  If the DeviceFS serial interface version of PPP is being
	  used then the named device is used for communication.
	  If this is not specified, the previously used device will
	  be used. devices:$.Serial1 is used if this option is
	  never specified.

     <speed>
          Set the baud rate to <speed>. The available speeds
          depend on the device you are using. If not specified,
          it will use the current setting of the chosen driver.

     asyncmap <map>
          Set the async character map to <map>.  This map
          describes which control characters cannot be success-
          fully received over the serial line.  PPP 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 asyncmap options are given, the values are
          ORed together.  If no asyncmap option is given, no
          async character map will be negotiated for the receive
          direction; the peer will then escape all control char-
          acters.

     auth Require the peer to authenticate itself before allowing
          network packets to be sent or received.

     crtscts
          Use hardware flow control (i.e. RTS/CTS) to control the
          flow of data on the serial port.

     xonxoff
          Use software flow control (i.e. XON/XOFF) to control
          the flow of data on the serial port. If neither this
          option nor the previous is used, the current state
          of the driver will be used

     -crtscts
          A synonym for xonxoff.

     defaultroute
          Add a default route to the system routing tables, using
          the peer as the gateway, when IPCP negotiation is suc-
          cessfully completed.  This entry is removed when the
          PPP connection is broken.

     escape xx,yy,...
          Specifies that certain characters should be escaped on
          transmission (regardless of whether the peer requests
          them to be escaped with its async control character
          map).  The characters to be escaped are specified as a
          list of hex numbers separated by commas.  Note that
          almost any character can be specified for the escape
          option, unlike the asyncmap option which only allows
          control characters to be specified.  The characters
          which may not be escaped are those with hex values 0x20
          - 0x3f or 0x5e.

     file <f>
          Read options from file <f> (the format is described
          below).

     mru <n>
          Set the MRU [Maximum Receive Unit] value to <n> for
          negotiation.  pppd will ask the peer to send packets of
          no more than <n> 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).

     netmask <n>
          Set the interface netmask to <n>, a 32 bit netmask in
          "decimal dot" notation (e.g. 255.255.255.0).

     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 does without this option).

     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 old versions of pppd).

OPTIONS
     <local_IP_address>:<remote_IP_address>
          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 noipde-
          fault 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 ipcp-accept-
          local and/or ipcp-accept-remote options are given,
          respectively.

     -all Don't request or allow negotiation of any options for
          LCP and IPCP (use default values).

     -ac  Disable Address/Control compression negotiation (use
          default, i.e.  address/control field disabled).

     -am  Disable asyncmap negotiation (use the default asyncmap,
          i.e. escape all control characters).

     -as <n>
          Same as asyncmap <n>

     -ip  Disable IP address negotiation (with this option, the
          remote IP address must be specified with an option on
          the command line or in an options file).

     -mn  Disable magic number negotiation.  With this option,
          pppd cannot detect a looped-back line.

     -mru Disable MRU [Maximum Receive Unit] negotiation (use
          default, i.e. 1500).

     -p   Same as the passive option.

     -pc  Disable protocol field compression negotiation (use
          default, i.e.  protocol field compression disabled).

     +ua <p>
          Agree to authenticate using PAP [Password Authentica-
          tion Protocol] if requested by the peer, and use the
          data in file <p> for the user and password to send to
          the peer. The file contains the remote user name, fol-
          lowed by a newline, followed by the remote password,
          followed by a newline.  This option is obsolescent.

     +pap Require the peer to authenticate itself using PAP.

     -pap Don't agree to authenticate using PAP.

     +chap
          Require the peer to authenticate itself using CHAP
          [Cryptographic Handshake Authentication Protocol]
          authentication.

     -chap
          Don't agree to authenticate using CHAP.

     -vj  Disable negotiation of Van Jacobson style IP header
          compression. This is the default above line speeds
          of 19200 baud, as Van Jacobson suffers from
          diminishing returns at high line speeds, and can be
          badly affected by a poor link. The main aim of
          VJ compression is to improve responsiveness of
          interactive traffic, eg typing via Telnet, over
          slow lines. It will not generally speed up file
          transfers, such as FTP.
          
     +vj  Enable negotiation of Van Jacobson stype IP header
          compression. This is the default at line speeds
          of 19200 baud or below.

     domain <d>
          Append the domain name <d> 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 would use the
          domain option to set the domain name to Quotron.COM.

     modem
          Use the modem control lines, ie signal to the modem
          using DTR, and check for hang-ups via DCD.

     local
          Don't use the modem control lines.

     mtu <n>
          Set the MTU [Maximum Transmit Unit] value to <n>.
          Unless the peer requests a smaller value via MRU nego-
          tiation, pppd will request that the kernel networking
          code send data packets of no more than n bytes through
          the PPP network interface.

     name <n>
          Set the name of the local system for authentication
          purposes to <n>, used especially for CHAP authentication.

     user <u>
          Set the user name to use for authenticating this
          machine with the peer using PAP to <u>.

     usehostname
          Enforce the use of the hostname as the name of the
          local system for authentication purposes (overrides the
          name option).

     remotename <n>
          Set the assumed name of the remote system for authenti-
          cation purposes to <n>.

     dialler
          Use the Dialler module for timeouts and maintaining
          connection
     
     nodialler
          Do not Use the Dialler module for timeouts and maintaining
          connection. (DEFAULT.)
     
     autodial
          Enable autodialling if using Dialler.
     
     noautodial
          Disable autodialling if using Dialler. (DEFAULT.)

(NOT IMPLEMENTED: Need SIOCGIFHWADDR from a future Internet module)
     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.

     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 dur-
          ing IPCP negotiation (unless it specified explicitly on
          the command line or in an options file).

     lcp-echo-interval <n>
          If this option is given, pppd will send an LCP echo-
          request frame to the peer every n seconds.  Under
          Linux, the echo-request is sent when no packets have
          been received from the peer for n seconds.  Normally
          the peer should respond to the echo-request by sending
          an echo-reply.  This option can be used with the lcp-
          echo-failure option to detect that the peer is no
          longer connected.

     lcp-echo-failure <n>
          If this option is given, pppd will presume the peer to
          be dead if n LCP echo-requests are sent without receiv-
          ing a valid LCP echo-reply.  If this happens, pppd will
          terminate the connection.  Use of this option requires
          a non-zero value for the lcp-echo-interval 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.

     lcp-restart <n>
          Set the LCP restart interval (retransmission timeout)
          to <n> seconds (default 3).

     lcp-max-terminate <n>
          Set the maximum number of LCP terminate-request
          transmissions to <n> (default 3).

     lcp-max-configure <n>
          Set the maximum number of LCP configure-request
          transmissions to <n> (default 10).

     lcp-max-failure <n>
          Set the maximum number of LCP configure-NAKs returned
          before starting to send configure-Rejects instead to
          <n> (default 10).

     ipcp-restart <n>
          Set the IPCP restart interval (retransmission timeout)
          to <n> seconds (default 3).

     ipcp-max-terminate <n>
          Set the maximum number of IPCP terminate-request
          transmissions to <n> (default 3).

     ipcp-max-configure <n>
          Set the maximum number of IPCP configure-request
          transmissions to <n> (default 10).

     ipcp-max-failure <n>
          Set the maximum number of IPCP configure-NAKs returned
          before starting to send configure-Rejects instead to
          <n> (default 10).

     pap-restart <n>
          Set the PAP restart interval (retransmission timeout)
          to <n> seconds (default 3).

     pap-max-authreq <n>
          Set the maximum number of PAP authenticate-request
          transmissions to <n> (default 10).

     chap-restart <n>
          Set the CHAP restart interval (retransmission timeout
          for challenges) to <n> seconds (default 3).

     chap-max-challenge <n>
          Set the maximum number of CHAP challenge transmissions
          to <n> (default 10).

     chap-interval <n>
          If this option is given, pppd will rechallenge the peer
          every <n> seconds.

     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.

     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.

OPTIONS FILES
     Options can be taken from files as well as the command line.
     PPP reads options from the files InetDbase:PPP.options
     before looking at the command line.  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 quotes (").
     A backslash (\) quotes the following character.  A hash (#)
     starts a comment, which continues until the end of the line.

AUTHENTICATION
     PPP 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 secu-
     rity of the server or the network it's on.  In part this is
     provided by the InetDbase:PPP.options file, where the
     administrator can place options to require authentication
     whenever PPP is run, and in part by the PAP and CHAP secrets
     files, where the administrator can restrict the set of IP
     addresses which individual users may use.

     The default behaviour of PPP is to agree to authenticate if
     requested, and to not require authentication from the peer.
     However, PPP will not agree to authenticate itself with a
     particular protocol if it has no secrets which could be used
     to do so.

     Authentication is based on secrets, which are selected from
     secrets files (InetDBase:PPP.PAPSecrets for PAP,
     InetDBase:PPP.CHAPSecret for CHAP).  Both secrets files have
     the same format, and both can store secrets for several comb-
     inations of server (authenticating peer) and client (peer
     being authenticated).  Note that pppd can be both a server
     and client, and that different protocols can be used in the
     two directions if desired.

     A secrets file is parsed into words as for a options file.
     A secret is specified by a line containing at least 3 words,
     in the order client, server, secret.  Any following words on
     the same line are taken to be a list of acceptable IP
     addresses for that client.  If there are only 3 words on the
     line, it is assumed that any IP address is OK; to disallow
     all IP addresses, use "-".  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.

     Thus a secrets file contains both secrets for use in authen-
     ticating other hosts, plus secrets which we use for authen-
     ticating ourselves to others.  Which secret to use is chosen
     based on the names of the host (the `local name') and its
     peer (the `remote name').  The local name is set as follows:

     if the usehostname option is given,
        then the local name is the hostname of this machine (with
        the domain appended, if given)

     else if the name option is given,
        then use the argument of the first name option seen

     else if the local IP address is specified with a hostname,
        then use that name
        
     else use the hostname of this machine (with the domain appended,
        if given)
        
     When authenticating ourselves using PAP, there is also a
     `username' which is the local name by default, but can be
     set with the user option or the +ua option.

     The remote name is set as follows:

     if the remotename option is given,
        then use the argument of the last remotename option seen

     else if the remote IP address is specified with a hostname,
        then use that host name

     else the remote name is the null string "".

     Secrets are selected from the PAP secrets file as follows:

     * For authenticating the peer, look for a secret with client
       == username specified in the PAP authenticate-request, and
       server == local name.

     * For authenticating ourselves to the peer, look for a
       secret with client == our username, server == remote name.

     When authenticating the peer with PAP, a secret of ""
     matches any password supplied by the peer.  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.
     Thus, the system administrator can set up the PAP secrets
     file to allow PPP access only to certain users, and to res-
     trict the set of IP addresses that each user can use.

     Secrets are selected from the CHAP secrets file as follows:

     * For authenticating the peer, look for a secret with client
       == name specified in the CHAP-Response message, and server
       == local name.

     * For authenticating ourselves to the peer, look for a
       secret with client == local name, and server == name
       specified in the CHAP-Challenge message.

     Authentication must be satisfactorily completed before IPCP
     (or any other Network Control Protocol) can be started.  If
     authentication fails, 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.

     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.

ROUTING
     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
     some cases this will be done automatically through the
     actions of the routed or gated daemons, but in most cases
     some further intervention is required.

     Sometimes it is desirable to add a default route through the
     remote host, as in the case of a machine whose only connec-
     tion to the Internet is through the ppp interface.  The
     defaultroute option causes PPP to create such a default
     route when IPCP comes up, and delete it when the link is
     terminated.

     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 proxy-
     arp 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, PPP creates a permanent,
     published ARP entry with the IP address of the remote host
     and the hardware address of the network interface found.
     (Not implemented yet)

EXAMPLES
     In the simplest case, you can connect the serial ports of
     two machines and issue a command like

          *PPPConnect InternalPC 9600 passive

     If you are using a modem, you will need to run a dialler,
     such as Chat, to make the initial connection.
     
     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 asyncmap a0000.
     
     If you need to authenticate yourself to the remote end, using
     PAP, you would use a command like
     
     	  *PPPConnect 115200 user m.jones
     
     and have a line in your PAP secrets file
     
          m.jones * abcdefg
     
     meaning that user m.jones should be authenticated to any host
     with the password abcdefg.
     
     To close the link, issue the command
           
          *PPPDisconnect

DIAGNOSTICS
     The contents of all control packets sent or received are logged,
     that is, all LCP, PAP, CHAP or IPCP packets.  This can be useful
     if the PPP negotiation  does not succeed. The log can be
     displayed using the *PPPLog command.
     
     The *PPPInfo command provides standard network driver statistics.

FILES
     InetDBase: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 parame-
          ters interface-name driver speed local-IP-address
          remote-IP-address.

          This file is restricted in what it can do. In particular
          it should not start a new application (eg running
          ifconfig).
          
     InetDBase:PPP.IP-Down
          A program or script which is executed when the link is
          no longer available for sending and receiving IP pack-
          ets.  This script can be used for undoing the effects
          of the InetDBase:PPP.IP-Up script.  It is invoked with the
          same parameters as the ip-up script. The same restrictions
          apply

     InetDBase:PPP.PAPSecrets
          Usernames, passwords and IP addresses for PAP authenti-
          cation.

     InetDBase:PPP.CHAPSecret
          Names, secrets and IP addresses for CHAP authentica-
          tion.

     InetDBase:PPP.Options
          System default options for PPP, read before command-
          line options.

NOTES
     If you wish to check the state of the PPP connection from
     an application, there are two things you need to check.
     Using socketioctl(SIOCGIFFLAGS) will tell you whether the
     IP layer is up (the IFF_UP flags). To tell whether the
     PPP daemon is actually active you will need to use the
     PPP_Stats SWI to examine the running flag; the
     IFF_RUNNING flag from the socketioctl does not correctly
     indicate the state of the daemon.
     
SEE ALSO
     RFC1144
          Jacobson, V.  Compressing TCP/IP headers for low-speed
          serial 1990 February.

     RFC1321
          Rivest, R.  The MD5 Message-Digest Algorithm. 1992
          April.

     RFC1332
          McGregor, G.  PPP Internet Protocol Control Protocol
          (IPCP).  1992 May.

     RFC1334
          Lloyd, B.; Simpson, W.A.  PPP authentication protocols.
          1992 October.

     RFC1548
          Simpson, W.A.  The Point-to-Point Protocol (PPP). 1993
          December.

     RFC1549
          Simpson, W.A.  PPP in HDLC Framing. 1993 December

AUTHORS
     Drew Perkins, Brad Clements, Karl Fox, Greg Christy, Brad
     Parker (brad@fcr.com), Paul Mackerras (paulus@cs.anu.edu.au),
     Kevin Bracey
